diff options
Diffstat (limited to 'devel/bmake/files/make.1')
| -rw-r--r-- | devel/bmake/files/make.1 | 367 |
1 files changed, 290 insertions, 77 deletions
diff --git a/devel/bmake/files/make.1 b/devel/bmake/files/make.1 index 179f8e20668..5241ec12307 100644 --- a/devel/bmake/files/make.1 +++ b/devel/bmake/files/make.1 @@ -1,4 +1,4 @@ -.\" $NetBSD: make.1,v 1.1.1.9 2011/06/18 22:18:01 bsiegert Exp $ +.\" $NetBSD: make.1,v 1.1.1.10 2015/05/19 21:36:44 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 May 29, 2011 +.Dd April 9, 2015 .Dt MAKE 1 .Os .Sh NAME @@ -37,41 +37,19 @@ .Nd maintain program dependencies .Sh SYNOPSIS .Nm -.Op Fl BeikNnqrstWX -.Bk -words +.Op Fl BeikNnqrstWwX .Op Fl C Ar directory -.Ek -.Bk -words .Op Fl D Ar variable -.Ek -.Bk -words .Op Fl d Ar flags -.Ek -.Bk -words .Op Fl f Ar makefile -.Ek -.Bk -words .Op Fl I Ar directory -.Ek -.Bk -words .Op Fl J Ar private -.Ek -.Bk -words .Op Fl j Ar max_jobs -.Ek -.Bk -words .Op Fl m Ar directory -.Ek -.Bk -words .Op Fl T Ar file -.Ek -.Bk -words .Op Fl V Ar variable -.Ek .Op Ar variable=value -.Bk -words .Op Ar target ... -.Ek .Sh DESCRIPTION .Nm is a program designed to simplify the maintenance of other programs. @@ -95,7 +73,7 @@ This manual page is intended as a reference document only. For a more thorough description of .Nm and makefiles, please refer to -.%T "Make \- A Tutorial" . +.%T "PMake \- A Tutorial" . .Pp .Nm will prepend the contents of the @@ -126,7 +104,7 @@ Turn on debugging, and specify which portions of .Nm are to print debugging information. Unless the flags are preceded by -.Ql - +.Ql \- they are added to the .Va MAKEFLAGS environment variable and will be processed by any child make processes. @@ -225,6 +203,10 @@ Print debugging information about makefile parsing. Print debugging information about suffix-transformation rules. .It Ar t Print debugging information about target list maintenance. +.It Ar V +Force the +.Fl V +option to print raw values of variables. .It Ar v Print debugging information about variable assignment. .It Ar x @@ -368,6 +350,8 @@ contains a then the value will be expanded before printing. .It Fl W Treat any warnings during makefile parsing as errors. +.It Fl w +Print entering and leaving directory messages, pre and post processing. .It Fl X Don't export variables passed on the command line to the environment individually. @@ -457,17 +441,29 @@ The value need not necessarily be used to describe existing files. Expansion is in directory order, not alphabetically as done in the shell. .Sh SHELL COMMANDS -Each target may have associated with it a series of shell commands, normally +Each target may have associated with it one or more lines of shell +commands, normally used to create the target. -Each of the commands in this script +Each of the lines in this script .Em must be preceded by a tab. -While any target may appear on a dependency line, only one of these -dependencies may be followed by a creation script, unless the +(For historical reasons, spaces are not accepted.) +While targets can appear in many dependency lines if desired, by +default only one of these rules may be followed by a creation +script. +If the .Ql Ic \&:: -operator is used. +operator is used, however, all rules may include scripts and the +scripts are executed in the order found. .Pp -If the first characters of the command line are any combination of +Each line is treated as a separate shell command, unless the end of +line is escaped with a backslash +.Pq Ql \e +in which case that line and the next are combined. +.\" The escaped newline is retained and passed to the shell, which +.\" normally ignores it. +.\" However, the tab at the beginning of the following line is removed. +If the first characters of the command are any combination of .Ql Ic @ , .Ql Ic + , or @@ -485,7 +481,63 @@ This is similar to the effect of the .MAKE special source, except that the effect can be limited to a single line of a script. A .Ql Ic \- +in compatibility mode causes any non-zero exit status of the command line to be ignored. +.Pp +When +.Nm +is run in jobs mode with +.Fl j Ar max_jobs , +the entire script for the target is fed to a +single instance of the shell. +In compatibility (non-jobs) mode, each command is run in a separate process. +If the command contains any shell meta characters +.Pq Ql #=|^(){};&<>*?[]:$`\e\en +it will be passed to the shell; otherwise +.Nm +will attempt direct execution. +If a line starts with +.Ql Ic \- +and the shell has ErrCtl enabled then failure of the command line +will be ignored as in compatibility mode. +Otherwise +.Ql Ic \- +affects the entire job; +the script will stop at the first command line that fails, +but the target will not be deemed to have failed. +.Pp +Makefiles should be written so that the mode of +.Nm +operation does not change their behavior. +For example, any command which needs to use +.Dq cd +or +.Dq chdir +without potentially changing the directory for subsequent commands +should be put in parentheses so it executes in a subshell. +To force the use of one shell, escape the line breaks so as to make +the whole script one command. +For example: +.Bd -literal -offset indent +avoid-chdir-side-effects: + @echo Building $@ in `pwd` + @(cd ${.CURDIR} && ${MAKE} $@) + @echo Back in `pwd` + +ensure-one-shell-regardless-of-mode: + @echo Building $@ in `pwd`; \e + (cd ${.CURDIR} && ${MAKE} $@); \e + echo Back in `pwd` +.Ed +.Pp +Since +.Nm +will +.Xr chdir 2 +to +.Ql Va .OBJDIR +before executing any targets, each child process +starts with that as its current working directory. .Sh VARIABLE ASSIGNMENTS Variables in make are much like variables in the shell, and, by tradition, consist of all upper-case letters. @@ -596,13 +648,19 @@ Variables defined in the makefile or in included makefiles. Variables defined as part of the command line. .It Local variables Variables that are defined specific to a certain target. +.El +.Pp +Local variables are all built in and their values vary magically from +target to target. +It is not currently possible to define new local variables. The seven local variables are as follows: -.Bl -tag -width ".ARCHIVE" +.Bl -tag -width ".ARCHIVE" -offset indent .It Va .ALLSRC The list of all sources for this target; also known as .Ql Va \&\*[Gt] . .It Va .ARCHIVE -The name of the archive file. +The name of the archive file; also known as +.Ql Va \&! . .It Va .IMPSRC In suffix-transformation rules, the name/path of the source from which the target is to be transformed (the @@ -611,7 +669,8 @@ source); also known as .Ql Va \&\*[Lt] . It is not defined in explicit rules. .It Va .MEMBER -The name of the archive member. +The name of the archive member; also known as +.Ql Va % . .It Va .OODATE The list of sources for this target that were deemed out-of-date; also known as @@ -620,31 +679,41 @@ known as The file prefix of the target, containing only the file portion, no suffix or preceding directory components; also known as .Ql Va * . +The suffix must be one of the known suffixes declared with +.Ic .SUFFIXES +or it will not be recognized. .It Va .TARGET The name of the target; also known as .Ql Va @ . .El .Pp The shorter forms -.Ql Va @ , +.Ql ( Va \*[Gt] , +.Ql Va \&! , +.Ql Va \*[Lt] , +.Ql Va % , .Ql Va \&? , -.Ql Va \&\*[Lt] , -.Ql Va \&\*[Gt] , +.Ql Va * , and -.Ql Va * +.Ql Va @ ) are permitted for backward -compatibility with historical makefiles and are not recommended. -The six variables -.Ql Va "@F" , -.Ql Va "@D" , -.Ql Va "\*[Lt]F" , -.Ql Va "\*[Lt]D" , -.Ql Va "*F" , +compatibility with historical makefiles and legacy POSIX make and are +not recommended. +.Pp +Variants of these variables with the punctuation followed immediately by +.Ql D +or +.Ql F , +e.g. +.Ql Va $(@D) , +are legacy forms equivalent to using the +.Ql :H and -.Ql Va "*D" -are permitted for compatibility with +.Ql :T +modifiers. +These forms are accepted for compatibility with .At V -makefiles and are not recommended. +makefiles and POSIX but are not recommended. .Pp Four of the local variables may be used in sources on dependency lines because they expand to the proper value for each target on the line. @@ -654,7 +723,6 @@ These variables are .Ql Va .ARCHIVE , and .Ql Va .MEMBER . -.El .Ss Additional built-in variables In addition, .Nm @@ -678,6 +746,10 @@ was executed. Refer to the description of .Ql Ev PWD for more details. +.It Va .INCLUDEDFROMDIR +The directory of the file this Makefile was included from. +.It Va .INCLUDEDFROMFILE +The filename of the file this Makefile was included from. .It Ev MAKE The name that .Nm @@ -697,6 +769,10 @@ and cannot be confused with the special target with the same name. Names the makefile (default .Ql Pa .depend ) from which generated dependencies are read. +.It Va .MAKE.EXPAND_VARIABLES +A boolean that controls the default behavior of the +.Fl V +option. .It Va .MAKE.EXPORTED The list of variables exported by .Nm . @@ -713,6 +789,9 @@ 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 . +If +.Va .MAKE.JOB.PREFIX +is empty, no token is printed. .br For example: .Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}] @@ -788,6 +867,9 @@ will not create .meta files in This can be overridden by setting .Va bf to a value which represents True. +.It Pa env +For debugging, it can be useful to inlcude the environment +in the .meta file. .It Pa verbose If in "meta" mode, print a clue about the target being built. This is useful if the build is otherwise running silently. @@ -799,6 +881,11 @@ This keyword causes them to be ignored for determining whether a target is out of date in "meta" mode. See also .Ic .NOMETA_CMP . +.It Pa silent= Ar bf +If +.Va bf +is True, when a .meta file is created, mark the target +.Ic .SILENT . .El .It Va .MAKE.META.BAILIWICK In "meta" mode, provides a list of prefixes which @@ -818,6 +905,11 @@ In "meta" mode, this variable contains a list of all the meta files used (updated or not). This list can be used to process the meta files to extract dependency information. +.It Va .MAKE.META.IGNORE_PATHS +Provides a list of path prefixes that should be ignored; +because the contents are expected to change over time. +The default list includes: +.Ql Pa /dev /etc /proc /tmp /var/run /var/tmp .It Va .MAKE.META.PREFIX Defines the message printed for each meta file updated in "meta verbose" mode. The default value is: @@ -836,6 +928,13 @@ by appending their names to is re-exported whenever .Ql Va .MAKEOVERRIDES is modified. +.It Va .MAKE.PATH_FILEMON +If +.Nm +was built with +.Xr filemon 4 +support, this is set to the path of the device node. +This allows makefiles to test for this support. .It Va .MAKE.PID The process-id of .Nm . @@ -918,6 +1017,9 @@ This variable and are both set only while the .Ql Pa Makefiles are being parsed. +If you want to retain their current values, assign them to a variable +using assignment with expansion: +.Pq Ql Cm \&:= . .It Va .PATH A variable that represents the list of directories that .Nm @@ -1008,6 +1110,13 @@ may be used. The wildcard characters may be escaped with a backslash .Pq Ql \e . +As a consequence of the way values are split into words, matched, +and then joined, a construct like +.Dl ${VAR:M*} +will normalise the inter-word spacing, removing all leading and +trailing space, and converting multiple consecutive spaces +to single spaces. +. .It Cm \&:N Ns Ar pattern This is identical to .Ql Cm \&:M , @@ -1151,7 +1260,7 @@ The modifier is just like the .Cm \&:S modifier except that the old and new strings, instead of being -simple strings, are a regular expression (see +simple strings, are an extended regular expression (see .Xr regex 3 ) string .Ar pattern @@ -1181,6 +1290,15 @@ and are orthogonal; the former specifies whether multiple words are potentially affected, the latter whether multiple substitutions can potentially occur within each affected word. +.Pp +As for the +.Cm \&:S +modifier, the +.Ar pattern +and +.Ar replacement +are subjected to variable expansion before being parsed as +regular expressions. .It Cm \&:T Replaces each word in the variable with its last component. .It Cm \&:u @@ -1249,6 +1367,9 @@ The ODE convention is that should start and end with a period. For example. .Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@} +.Pp +However a single character variable is often more readable: +.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@} .It Cm \&:U Ns Ar newval If the variable is undefined .Ar newval @@ -1270,6 +1391,8 @@ The path of the node which has the same name as the variable is the value. If no such node exists or its path is null, then the name of the variable is used. +In order for this modifier to work, the name (node) must at least have +appeared on the rhs of a dependency. .Sm off .It Cm \&:\&! Ar cmd Cm \&! .Sm on @@ -1330,7 +1453,7 @@ For the purposes of the modifier, the words are indexed both forwards using positive integers (where index 1 represents the first word), and backwards using negative integers -(where index -1 represents the last word). +(where index \-1 represents the last word). .Pp The .Ar range @@ -1429,6 +1552,11 @@ except for internal variables (those that start with This is not affected by the .Fl X flag, so should be used with caution. +For compatibility with other +.Nm +programs +.Ql export variable=value +is also accepted. .Pp Appending a variable name to .Va .MAKE.EXPORTED @@ -1683,7 +1811,7 @@ or .Fl t options were specified. Normally used to mark recursive -.Nm Ns 's . +.Nm Ns s . .It Ic .META Create a meta file for the target, even if it is flagged as .Ic .PHONY , @@ -1693,6 +1821,7 @@ or Usage in conjunction with .Ic .MAKE is the most likely case. +In "meta" mode, the target is out-of-date if the meta file is missing. .It Ic .NOMETA Do not create a meta file for the target. Meta files are also not created for @@ -1705,6 +1834,20 @@ targets. Ignore differences in commands when deciding if target is out of date. This is useful if the command contains a value which always changes. If the number of commands change, though, the target will still be out of date. +The same effect applies to any command line that uses the variable +.Va .OODATE , +which can be used for that purpose even when not otherwise needed or desired: +.Bd -literal -offset indent + +skip-compare-for-some: + @echo this will be compared + @echo this will not ${.OODATE:M.NOMETA_CMP} + @echo this will also be compared + +.Ed +The +.Cm \&:M +pattern suppresses any expansion of the unwanted variable. .It Ic .NOPATH Do not search for the target in the directories specified by .Ic .PATH . @@ -1888,6 +2031,12 @@ If the source is the special .Ic .DOTLAST target, then the current working directory is searched last. +.It Ic .PATH. Ns Va suffix +Like +.Ic .PATH +but applies only to files with a particular suffix. +The suffix must have been previously declared with +.Ic .SUFFIXES . .It Ic .PHONY Apply the .Ic .PHONY @@ -1944,8 +2093,8 @@ character when used outside of any quoting characters. Example: .Bd -literal \&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e - check="set -e" ignore="set +e" \e - echo="set -v" quiet="set +v" filter="set +v" \e + check="set \-e" ignore="set +e" \e + echo="set \-v" quiet="set +v" filter="set +v" \e echoFlag=v errFlag=e newline="'\en'" .Ed .It Ic .SILENT @@ -1956,6 +2105,10 @@ If no sources are specified, the .Ic .SILENT attribute is applied to every command in the file. +.It Ic .STALE +This target gets run when a dependency file contains stale entries, having +.Va .ALLSRC +set to the name of that dependency file. .It Ic .SUFFIXES Each source specifies a suffix to .Nm . @@ -1966,7 +2119,7 @@ Example: .Bd -literal \&.SUFFIXES: .o \&.c.o: - cc -o ${.TARGET} -c ${.IMPSRC} + cc \-o ${.TARGET} \-c ${.IMPSRC} .Ed .El .Sh ENVIRONMENT @@ -2006,13 +2159,11 @@ system makefile system makefile directory .El .Sh COMPATIBILITY -The basic make syntax is compatible between different versions of make, +The basic make syntax is compatible between different versions of make; however the special variables, variable modifiers and conditionals are not. -.Pp -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. +.Ss Older versions +An incomplete list of changes in older versions of +.Nm : .Pp The way that .for loop variables are substituted changed after .Nx 5.0 @@ -2020,20 +2171,75 @@ 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. .Pp -Unlike other +The way that parallel makes are scheduled changed in +.Nx 4.0 +so that .ORDER and .WAIT apply recursively to the dependent nodes. +The algorithms used may change again in the future. +.Ss Other make dialects +Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not +support most of the features of .Nm -programs, this implementation by default executes all commands for a given -target using a single shell invocation. -This is done for both efficiency and to simplify error handling in remote -command invocations. -Typically this is transparent to the user, unless the target commands change -the current working directory using -.Dq cd -or -.Dq chdir . -To be compatible with Makefiles that do this, one can use -.Fl B -to disable this behavior. +as described in this manual. +Most notably: +.Bl -bullet -offset indent +.It +The +.Ic .WAIT +and +.Ic .ORDER +declarations and most functionality pertaining to parallelization. +(GNU make supports parallelization but lacks these features needed to +control it effectively.) +.It +Directives, including for loops and conditionals and most of the +forms of include files. +(GNU make has its own incompatible and less powerful syntax for +conditionals.) +.It +All built-in variables that begin with a dot. +.It +Most of the special sources and targets that begin with a dot, +with the notable exception of +.Ic .PHONY , +.Ic .PRECIOUS , +and +.Ic .SUFFIXES . +.It +Variable modifiers, except for the +.Dl :old=new +string substitution, which does not portably support globbing with +.Ql % +and historically only works on declared suffixes. +.It +The +.Ic $> +variable even in its short form; most makes support this functionality +but its name varies. +.El +.Pp +Some features are somewhat more portable, such as assignment with +.Ic += , +.Ic ?= , +and +.Ic != . +The +.Ic .PATH +functionality is based on an older feature +.Ic VPATH +found in GNU make and many versions of SVR4 make; however, +historically its behavior is too ill-defined (and too buggy) to rely +upon. +.Pp +The +.Ic $@ +and +.Ic $< +variables are more or less universally portable, as is the +.Ic $(MAKE) +variable. +Basic use of suffix rules (for files only in the current directory, +not trying to chain transformations together, etc.) is also reasonably +portable. .Sh SEE ALSO .Xr mkdep 1 .Sh HISTORY @@ -2044,10 +2250,17 @@ command appeared in This .Nm implementation is based on Adam De Boor's pmake program which was written -for Sprint at Berkeley. +for Sprite at Berkeley. It was designed to be a parallel distributed make running jobs on different machines using a daemon called .Dq customs . +.Pp +Historically the target/dependency +.Dq FRC +has been used to FoRCe rebuilding (since the target/dependency +does not exist... unless someone creates an +.Dq FRC +file). .Sh BUGS The .Nm |