diff options
Diffstat (limited to 'devel/bmake/files/bmake.1')
| -rw-r--r-- | devel/bmake/files/bmake.1 | 212 |
1 files changed, 158 insertions, 54 deletions
diff --git a/devel/bmake/files/bmake.1 b/devel/bmake/files/bmake.1 index 50908ded1b9..74071f6beb0 100644 --- a/devel/bmake/files/bmake.1 +++ b/devel/bmake/files/bmake.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: bmake.1,v 1.2 2008/03/09 19:54:29 joerg Exp $ +.\" $NetBSD: bmake.1,v 1.3 2009/09/18 21:27:25 joerg Exp $ .\" .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. @@ -29,7 +29,7 @@ .\" .\" from: @(#)make.1 8.4 (Berkeley) 3/19/94 .\" -.Dd November 19, 2006 +.Dd September 7, 2009 .Dt MAKE 1 .Os .Sh NAME @@ -39,6 +39,9 @@ .Nm .Op Fl BeikNnqrstWX .Bk -words +.Op Fl C Ar directory +.Ek +.Bk -words .Op Fl D Ar variable .Ek .Bk -words @@ -104,6 +107,16 @@ The options are as follows: .It Fl B Try to be backwards compatible by executing a single shell per command and by executing the commands to make the sources of a dependency line in sequence. +.It Fl C Ar directory +Change to +.Ar directory +before reading the makefiles or doing anything else. +If multiple +.Fl C +options are specified, each is interpreted relative to the previous one: +.Fl C Pa / Fl C Pa etc +is equivalent to +.Fl C Pa /etc . .It Fl D Ar variable Define .Ar variable @@ -117,6 +130,13 @@ Unless the flags are preceded by they are added to the .Va MAKEFLAGS environment variable and will be processed by any child make processes. +By default, debugging information is printed to standard error, +but this can be changed using the +.Ar F +debugging flag. +The debugging output is always unbuffered; in addition, if debugging +is enabled but debugging output is not directed to standard output, +then the standard output is line buffered. .Ar Flags is one or more of the following: .Bl -tag -width Ds @@ -125,17 +145,35 @@ Print all possible debugging information; equivalent to specifying all of the debugging flags. .It Ar a Print debugging information about archive searching and caching. +.It Ar C +Print debugging information about current working directory. .It Ar c Print debugging information about conditional evaluation. .It Ar d Print debugging information about directory searching and caching. .It Ar e Print debugging information about failed commands and targets. -.It Ar F -Use the rest of -.Ql flags -as the name of the file to which the debug output is written. -If the filename ends +.It Ar F Ns Oo Sy \&+ Oc Ns Ar filename +Specify where debugging output is written. +This must be the last flag, because it consumes the remainder of +the argument. +If the character immediately after the +.Ql F +flag is +.Ql \&+ , +then the file will be opened in append mode; +otherwise the file will be overwritten. +If the file name is +.Ql stdout +or +.Ql stderr +then debugging output will be written to the +standard output or standard error output file descriptors respectively +(and the +.Ql \&+ +option has no effect). +Otherwise, the output will be written to the named file. +If the file name ends .Ql .%d then the .Ql %d @@ -153,23 +191,31 @@ Print the input graph before exiting on error. Print debugging information about running multiple shells. .It Ar l Print commands in Makefiles regardless of whether or not they are prefixed by -.Ql @ +.Ql @ or other "quiet" flags. Also known as "loud" behavior. .It Ar m Print debugging information about making targets, including modification dates. .It Ar n -Don't delete the temporary command scripts created in +Don't delete the temporary command scripts created when running commands. +These temporary scripts are created in the directory +referred to by the +.Ev TMPDIR +environment variable, or in .Pa /tmp -when running commands. -These are created via -.Xr mkstemp 3 +if +.Ev TMPDIR +is unset or set to the empty string. +The temporary scripts are created by +.Xr mkstemp 3 , and have names of the form -.Pa /tmp/makeXXXXX . +.Pa makeXXXXXX . .Em NOTE : -This can create many file in -.Pa /tmp +This can create many files in +.Ev TMPDIR +or +.Pa /tmp , so use with care. .It Ar p Print debugging information about makefile parsing. @@ -223,6 +269,14 @@ may have running at any one time. Turns compatibility mode off, unless the .Ar B flag is also specified. +When compatibility mode is off, all commands associated with a +target are executed in a single shell invocation as opposed to the +traditional one shell invocation per line. +This can break traditional scripts which change directories on each +command invocation and then expect to start with a fresh environment +on the next line. +It is more efficient to correct the scripts rather than turn backwards +compatibility on. .It Fl k Continue processing after errors are encountered, but only on those targets that do not depend on the target whose creation caused the error. @@ -345,7 +399,9 @@ line are compressed into a single space. .Sh FILE DEPENDENCY SPECIFICATIONS Dependency lines consist of one or more targets, an operator, and zero or more sources. -This creates a relationship where the targets ``depend'' on the sources +This creates a relationship where the targets +.Dq depend +on the sources and are usually created from them. The exact relationship between the target and the source is determined by the operator that separates them. @@ -472,6 +528,14 @@ If the variable name contains only a single letter, the surrounding braces or parentheses are not required. This shorter form is not recommended. .Pp +If the variable name contains a dollar, then the name itself is expanded first. +This allows almost arbitrary variable names, however names containing dollar, +braces, parenthesis, or whitespace are really best avoided! +.Pp +If the result of expanding a variable contains a dollar sign +.Pq Ql \&$ +the string is expanded again. +.Pp Variable substitution occurs at two distinct times, depending on where the variable is being used. Variables in dependency lines are expanded as the line is read. @@ -499,9 +563,12 @@ The list of all sources for this target; also known as .It Va .ARCHIVE The name of the archive file. .It Va .IMPSRC -The name/path of the source from which the target is to be transformed -(the ``implied'' source); also known as +In suffix-transformation rules, the name/path of the source from which the +target is to be transformed (the +.Dq implied +source); also known as .Ql Va \&\*[Lt] . +It is not defined in explicit rules. .It Va .MEMBER The name of the archive member. .It Va .OODATE @@ -547,7 +614,7 @@ These variables are and .Ql Va .MEMBER . .El -.Ss Additional inbuilt variables +.Ss Additional built-in variables In addition, .Nm sets or knows about the following variables: @@ -593,23 +660,34 @@ The list of makefiles read by .Nm , which is useful for tracking dependencies. Each makefile is recorded only once, regardless of the number of times read. +.It Va .MAKE.LEVEL +The recursion depth of +.Nm . +The initial instance of +.Nm +will be 0, and an incremented value is put into the environment +to be seen by the next generation. +This allows tests like: +.Li .if ${.MAKE.LEVEL} == 0 +to protect things which should only be evaluated in the initial instance of +.Nm . .It Va .MAKE.PID -The process-id of +The process-id of .Nm . .It Va .MAKE.PPID -The parent process-id of +The parent process-id of .Nm . .It Va .MAKE.JOB.PREFIX -If +If .Nm is run with .Ar j -then output for each target is prefixed with a token +then output for each target is prefixed with a token .Ql --- target --- the first part of which can be controlled via .Va .MAKE.JOB.PREFIX . .br -For example: +For example: .Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}] would produce tokens like .Ql ---make[1234] target --- @@ -694,7 +772,7 @@ may be used. .Pp .Ql Va .OBJDIR may be modified in the makefile as a global variable. -In all cases, +In all cases, .Nm will .Xr chdir 2 @@ -751,10 +829,22 @@ is set to the value of for all programs which .Nm executes. +.It Ev VPATH +Colon-separated +.Pq Dq \&: +lists of directories that +.Nm +will search for files. +The variable is supported for compatibility with old make programs only, +use +.Ql Va .PATH +instead. .El .Ss Variable modifiers Variable expansion may be modified to select or modify each word of the -variable (where a ``word'' is white-space delimited sequence of characters). +variable (where a +.Dq word +is white-space delimited sequence of characters). The general format of a variable expansion is as follows: .Pp .Dl ${variable[:modifier[:...]]} @@ -963,11 +1053,16 @@ Remove adjacent duplicate words (like .Sm off .It Cm \&:\&? Ar true_string Cm \&: Ar false_string .Sm on -If the variable (actually an expression; see below) -evaluates to true, return as its value the +If the variable name (not its value), when parsed as a .if conditional +expression, evaluates to true, return as its value the .Ar true_string , otherwise return the .Ar false_string . +Since the variable name is used as the expression, \&:\&? must be the +first modifier after the variable name itself - which will, of course, +usually contain variable expansions. +If the expression is a single token, it will likely be treated as a check +for the name being defined. .It Ar :old_string=new_string This is the .At V @@ -1052,25 +1147,14 @@ The variable is assigned the value .Ar str after substitution. This modifier and its variations are useful in -obscure situations such as wanting to apply modifiers to -.Cm \&.for -loop iteration variables which won't work due to the way -.Cm \&.for -loops are implemented. +obscure situations such as wanting to set a variable when shell commands +are being parsed. These assignment modifiers always expand to nothing, so if appearing in a rule line by themselves should be preceded with something to keep .Nm happy. -As in: -.Bd -literal -use_foo: \&.USE -\&.for i in ${\&.TARGET} ${\&.TARGET:R}\&.gz - @: ${t::=$i} - @echo t:R:T=${t:R:T} -\&.endfor - -.Ed +.Pp The .Ql Cm \&:: helps avoid false matches with the @@ -1199,8 +1283,7 @@ The possible conditionals are as follows: Export the specified global variable. If no variable is provided, all globals are exported except for internal variables (those that start with -.Ql \&. -). +.Ql \&. ) . This is not affected by the .Fl X flag, so should be used with caution. @@ -1368,19 +1451,25 @@ of a string comparison. .Pp When .Nm -is evaluating one of these conditional expression, and it encounters -a word it doesn't recognize, either the ``make'' or ``defined'' +is evaluating one of these conditional expressions, and it encounters +a (white-space separated) word it doesn't recognize, either the +.Dq make +or +.Dq defined expression is applied to it, depending on the form of the conditional. If the form is -.Ql Ic .ifdef -or +.Ql Ic .ifdef , .Ql Ic .ifndef , -the ``defined'' expression -is applied. +or +.Ql Ic .if +the +.Dq defined +expression is applied. Similarly, if the form is .Ql Ic .ifmake or -.Ql Ic .ifnmake , the ``make'' +.Ql Ic .ifnmake , the +.Dq make expression is applied. .Pp If the conditional evaluates to true the parsing of the makefile continues @@ -1519,9 +1608,9 @@ b1: .Ed the output is always +.Ql a , .Ql b1 , .Ql b , -.Ql a , .Ql x . .br The ordering imposed by @@ -1599,7 +1688,7 @@ could be built, unless is built by another part of the dependency graph, the following is a dependency loop: .Bd -literal -\&.ORDER a b +\&.ORDER: a b b: a .Ed .Pp @@ -1692,6 +1781,14 @@ command in the file. Each source specifies a suffix to .Nm . If no sources are specified, any previously specified suffixes are deleted. +It allows the creation of suffix-transformation rules. +.Pp +Example: +.Bd -literal +\&.SUFFIXES: .o +\&.c.o: + cc -o ${.TARGET} -c ${.IMPSRC} +.Ed .El .Sh ENVIRONMENT .Nm @@ -1703,8 +1800,9 @@ uses the following environment variables, if they exist: .Ev MAKEOBJDIR , .Ev MAKEOBJDIRPREFIX , .Ev MAKESYSPATH , +.Ev PWD , and -.Ev PWD . +.Ev TMPDIR . .Pp .Ev MAKEOBJDIRPREFIX and @@ -1736,6 +1834,12 @@ The way that parallel makes are scheduled changed in .Nx 4.0 so that .ORDER and .WAIT apply recursively to the dependant nodes. The algorithms used may change again in the future. +.Pp +The way that .for loop variables are substituted changed after +.Nx 5.0 +so that they still appear to be variable expansions. +In particular this stops them being treated as syntax, and removes some +obscure problems using them in .if statements. .Sh SEE ALSO .Xr mkdep 1 .Sh HISTORY |