diff options
Diffstat (limited to 'usr.bin/make/make.1')
| -rw-r--r-- | usr.bin/make/make.1 | 1843 |
1 files changed, 0 insertions, 1843 deletions
diff --git a/usr.bin/make/make.1 b/usr.bin/make/make.1 deleted file mode 100644 index 63da1aa..0000000 --- a/usr.bin/make/make.1 +++ /dev/null @@ -1,1843 +0,0 @@ -.\" Copyright (c) 1990, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)make.1 8.8 (Berkeley) 6/13/95 -.\" $FreeBSD$ -.\" -.Dd May 30, 2012 -.Dt MAKE 1 -.Os -.Sh NAME -.Nm make -.Nd maintain program dependencies -.Sh SYNOPSIS -.Nm -.Op Fl ABPSXeiknpqrstv -.Op Fl C Ar directory -.Op Fl D Ar variable -.Op Fl d Ar flags -.Op Fl E Ar variable -.Op Fl f Ar makefile -.Op Fl I Ar directory -.Bk -words -.Op Fl j Ar max_jobs -.Op Fl m Ar directory -.Ek -.Op Fl V Ar variable -.Op Fl x Ar warning_options -.Op Ar variable Ns No = Ns Ar value -.Op Ar target ... -.Sh DESCRIPTION -The -.Nm -utility is a program designed to simplify the maintenance of other programs. -Its input is a list of specifications -describing dependency relationships between the generation of -files and programs. -.Pp -First of all, the initial list of specifications will be read -from the system makefile, -.Pa sys.mk , -unless inhibited with the -.Fl r -option. -The standard -.Pa sys.mk -as shipped with -.Fx -also handles -.Xr make.conf 5 , -the default path to which -can be altered via the -.Nm -variable -.Va __MAKE_CONF . -.Pp -Then the first of -.Pa BSDmakefile , -.Pa makefile , -and -.Pa Makefile -that can be found in the current directory, object directory (see -.Va .OBJDIR ) , -or search path (see the -.Fl I -option) -will be read for the main list of dependency specifications. -A different makefile or list of them can be supplied via the -.Fl f -option(s). -Finally, if the file -.Pa .depend -can be found in any of the aforesaid locations, it will also be read (see -.Xr mkdep 1 ) . -.Pp -When -.Nm -searches for a makefile, its name takes precedence over its location. -For instance, -.Pa BSDmakefile -in the object directory will be favored over -.Pa Makefile -in the current directory. -.Pp -The options are as follows: -.Bl -tag -width Ds -.It Fl A -Make archive errors non-fatal, causing -.Nm -to just skip the remainder -or all of the archive and continue after printing a message. -.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. -This is turned on by default unless -.Fl j -is used. -.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 -to be 1, in the global context. -.It Fl d Ar flags -Turn on debugging, and specify which portions of -.Nm -are to print debugging information. -Argument -.Ar flags -is one or more of the following: -.Bl -tag -width Ds -.It Ar A -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 conditional evaluation. -.It Ar d -Print debugging information about directory searching and caching. -.It Ar f -Print debugging information about the execution of for loops. -.It Ar "g1" -Print the input graph before making anything. -.It Ar "g2" -Print the input graph after making everything, or before exiting -on error. -.It Ar j -Print debugging information about running multiple shells. -.It Ar l -Print commands in Makefiles regardless of whether or not they are prefixed -by @ or other "quiet" flags. -Also known as "loud" behavior. -.It Ar m -Print debugging information about making targets, including modification -dates. -.It Ar s -Print debugging information about suffix-transformation rules. -.It Ar t -Print debugging information about target list maintenance. -.It Ar v -Print debugging information about variable assignment. -.El -.It Fl E Ar variable -Specify a variable whose environment value (if any) will override -macro assignments within makefiles. -.It Fl e -Specify that environment values override macro assignments within -makefiles for all variables. -.It Fl f Ar makefile -Specify a makefile to read instead of the default one. -If -.Ar makefile -is not an absolute pathname, -.Nm -will search for it as described above. -In case -.Ar makefile -is -.Sq Fl , -standard input is read. -Multiple -.Fl f -options can be supplied, -and the makefiles will be read in that order. -Unlike the other command-line options, -.Fl f -is neither stored in -.Va .MAKEFLAGS -nor pushed down to sub-makes via -.Ev MAKEFLAGS . -See below for more details on these variables. -.It Fl I Ar directory -Specify a directory in which to search for makefiles and included makefiles. -Multiple -.Fl I -options can be specified to form a search path. -The system makefile directory (or directories, see the -.Fl m -option) is automatically appended at the tail of this path. -.It Fl i -Ignore non-zero exit of shell commands in the makefile. -Equivalent to specifying -.Sq Ic \- -before each command line in the makefile. -.It Fl j Ar max_jobs -Specify the maximum number of jobs that -.Nm -may have running at any one time. -Turns compatibility mode off, unless the -.Fl B -flag is also specified. -.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. -.It Fl m Ar directory -Specify a directory in which to search for -the system makefile and makefiles included via the <...> style. -Multiple -.Fl m -options can be specified to form a search path. -This path will override the default system include path, -.Pa /usr/share/mk . -The system include path will always be appended to the search path used -for "..."-style inclusions and makefile searches (see the -.Fl I -option). -.Pp -If a file or directory name in the -.Fl m -argument (or the -.Ev MAKESYSPATH -environment variable) starts with the string -.Qq \&.../ -then -.Nm -will search for the specified file or directory named in the remaining part -of the argument string. -The search starts with the current directory of the Makefile and then works -upward towards the root of the filesystem. -If the search is successful, -then the resulting directory replaces the -.Qq \&.../ -specification in the -.Fl m -argument. -If used, this feature allows -.Nm -to easily search in the current source tree for customized sys.mk files -(e.g. by using -.Qq \&.../mk/sys.mk -as an argument). -Note that a -.Fl C -that are earlier on the command line affect where -.Fl m Qq \&.../ -searches. -.It Fl n -Display the commands that would have been executed, but do not actually -execute them. -.It Fl P -Collate the output of a given job and display it only when the job finishes, -instead of mixing the output of parallel jobs together. -This option has no effect unless -.Fl j -is used too. -.It Fl p -Only print the input graph, not executing any commands. -The output is the same as -.Fl d Ar g1 . -When combined with -.Fl f Pa /dev/null , -only the builtin rules of -.Nm -are displayed. -.It Fl Q -Be extra quiet. -For multi-job makes, this will cause file banners not to be generated. -.It Fl q -Do not execute any commands, but exit 0 if the specified targets are -up-to-date and 1, otherwise. -.It Fl r -Do not process the system makefile. -.It Fl S -Stop processing when an error is encountered. -Default behaviour. -This is needed to negate the -.Fl k -option during recursive builds. -.It Fl s -Do not echo any commands as they are executed. -Equivalent to specifying -.Sq Ic @ -before each command line in the makefile. -.It Fl t -Rather than re-building a target as specified in the makefile, create it -or update its modification time to make it appear up-to-date. -.It Fl V Ar variable -Print -.Nm Ns 's -idea of the value of -.Ar variable , -in the global context. -Do not build any targets. -Multiple instances of this option may be specified; -the variables will be printed one per line, -with a blank line for each null or undefined variable. -If -.Ar variable -contains a -.Sq Ic $ -then the value will be expanded before printing. -.It Fl v -Be extra verbose. -Print any extra information. -.It Fl X -When using the -.Fl V -option to print the values of variables, -do not recursively expand the values. -.It Ar variable Ns No = Ns Ar value -Set the value of the variable -.Ar variable -to -.Ar value . -.It Fl x Ar warning_options -Specify extended warning options. -This option may be specified several times. -A -.Ar warning_option -can be prefixed with -.Dq Li no -in which case the warning is switched off. -The currently available options are: -.Bl -tag -width indent -.It Li dirsyntax -Warn if anything except blanks and comments follows an -.Ic .endif -or -.Ic .else -directive. -.El -.Pp -See also the -.Ic .WARN -special target. -.El -.Pp -There are seven different types of lines in a makefile: file dependency -specifications, shell commands, variable assignments, include statements, -conditional directives, for loops, and comments. -.Pp -In general, lines may be continued from one line to the next by ending -them with a backslash -.Pq Ql \e . -The trailing newline character and initial whitespace on the following -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 -.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. -The three operators are as follows: -.Bl -tag -width flag -.It Ic \&: -A target is considered out-of-date if its modification time is less than -those of any of its sources. -Sources for a target accumulate over dependency lines when this operator -is used. -The target is removed if -.Nm -is interrupted. -.It Ic \&! -Targets are always re-created, but not until all sources have been -examined and re-created as necessary. -Sources for a target accumulate over dependency lines when this operator -is used. -The target is removed if -.Nm -is interrupted. -.It Ic :: -If no sources are specified, the target is always re-created. -Otherwise, a target is considered out-of-date if any of its sources has -been modified more recently than the target. -Sources for a target do not accumulate over dependency lines when this -operator is used. -The target will not be removed if -.Nm -is interrupted. -.El -.Pp -Targets and sources may contain the shell wildcard expressions -.Ql \&? , -.Ql * , -.Ql [] -and -.Ql {} . -The expressions -.Ql \&? , -.Ql * -and -.Ql [] -may only be used as part of the final -component of the target or source, and must be used to describe existing -files. -The expression -.Ql {} -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 -used to create the target. -Each of the commands 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 -.Sq Ic :: -operator is used. -.Pp -If the first characters of the command line are -.Sq Ic @ , -.Sq Ic \- , -and/or -.Sq Ic + , -the command is treated specially. -A -.Sq Ic @ -causes the command not to be echoed before it is executed. -A -.Sq Ic \- -causes any non-zero exit status of the command line to be ignored. -A -.Sq Ic + -causes the command to be executed even if -.Fl n -is specified on the command line. -.Sh VARIABLE ASSIGNMENTS -Variables in -.Nm -are much like variables in the shell, and, by tradition, -consist of all upper-case letters. -The five operators that can be used to assign values to variables are as -follows: -.Bl -tag -width Ds -.It Ic = -Assign the value to the variable. -Any previous value is overridden. -.It Ic += -Append the value to the current value of the variable. -.It Ic ?= -Assign the value to the variable if it is not already defined. -.It Ic := -Assign with expansion, i.e., expand the value before assigning it -to the variable. -Normally, expansion is not done until the variable is referenced. -.It Ic != -Expand the value and pass it to the shell for execution and assign -the result to the variable. -Any newlines in the result are replaced with spaces. -.El -.Pp -Any whitespace before the assigned -.Ar value -is removed; if the value is being appended, a single space is inserted -between the previous contents of the variable and the appended value. -.Pp -Variables are expanded by surrounding the variable name with either -curly braces -.Pq Ql {} -or parentheses -.Pq Ql () -and preceding it with -a dollar sign -.Pq Ql $ . -If the variable name contains only a single letter, the surrounding -braces or parentheses are not required. -This shorter form is not recommended. -.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. -Variables in shell commands are expanded when the shell command is -executed. -.Pp -The four different classes of variables (in order of increasing precedence) -are: -.Bl -tag -width Ds -.It Environment variables -Variables defined as part of -.Nm Ns 's -environment. -.It Global variables -Variables defined in the makefile or in included makefiles. -.It Command line variables -Variables defined as part of the command line and variables -obtained from the -.Ev MAKEFLAGS -environment variable or the -.Ic .MAKEFLAGS -target. -.It Local variables -Variables that are defined specific to a certain target. -.El -.Pp -If the name of an environment variable appears in a makefile -on the left-hand side of an assignment, -a global variable with the same name is created, and the latter -shadows the former as per their relative precedences. -The environment is not changed in this case, and the change -is not exported to programs executed by -.Nm . -However, a command-line variable actually replaces -the environment variable of the same name if the latter exists, -which is visible to child programs. -.Pp -There are seven local variables in -.Nm : -.Bl -tag -width ".ARCHIVE" -.It Va .ALLSRC -The list of all sources for this target; also known as -.Sq Va > . -.It Va .ARCHIVE -The name of the archive file; also known as -.Sq Va \&! . -.It Va .IMPSRC -The name/path of the source from which the target is to be transformed -(the -.Dq implied -source); also known as -.Sq Va < . -.It Va .MEMBER -The name of the archive member; also known as -.Sq Va % . -.It Va .OODATE -The list of sources for this target that were deemed out-of-date; also -known as -.Sq Va \&? . -.It Va .PREFIX -The file prefix of the file, containing only the file portion, no suffix -or preceding directory components; also known as -.Sq Va * . -.It Va .TARGET -The name of the target; also known as -.Sq Va @ . -.El -.Pp -The shorter forms -.Sq Va @ , -.Sq Va \&! , -.Sq Va < , -.Sq Va % , -.Sq Va \&? , -.Sq Va > , -and -.Sq Va * -are permitted for backward -compatibility and are not recommended. -The six variables -.Sq Va @F , -.Sq Va @D , -.Sq Va <F , -.Sq Va <D , -.Sq Va *F , -and -.Sq Va *D -are -permitted for compatibility with -.At V -makefiles and 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. -These variables are -.Va .TARGET , -.Va .PREFIX , -.Va .ARCHIVE , -and -.Va .MEMBER . -.Pp -In addition, -.Nm -sets or knows about the following internal variables or environment -variables: -.Bl -tag -width ".Va .MAKEFILE_LIST" -.It Va $ -A single dollar sign -.Ql $ , -i.e.\& -.Ql $$ -expands to a single dollar -sign. -.It Va MAKE -The name that -.Nm -was executed with -.Pq Va argv Ns Op 0 . -.It Va .CURDIR -A path to the directory where -.Nm -was executed. -The -.Nm -utility sets -.Va .CURDIR -to the canonical path given by -.Xr getcwd 3 . -.It Va .OBJDIR -A path to the directory where the targets are built. -At startup, -.Nm -searches for an alternate directory to place target files. -It will attempt to change into this special directory -and will search this directory for makefiles -not found in the current directory. -The following directories are tried in order: -.Pp -.Bl -enum -compact -.It -${MAKEOBJDIRPREFIX}/`pwd -P` -.It -${MAKEOBJDIR} -.It -obj.${MACHINE} -.It -obj -.It -/usr/obj/`pwd -P` -.El -.Pp -The first directory that -.Nm -successfully changes into is used. -If either -.Ev MAKEOBJDIRPREFIX -or -.Ev MAKEOBJDIR -is set in the environment but -.Nm -is unable to change into the corresponding directory, -then the current directory is used -without checking the remainder of the list. -If they are undefined and -.Nm -is unable to change into any of the remaining three directories, -then the current directory is used. -Note, that -.Ev MAKEOBJDIRPREFIX -and -.Ev MAKEOBJDIR -must be environment variables and should not be set on -.Nm Ns 's -command line. -.Pp -The -.Nm -utility sets -.Va .OBJDIR -to the canonical path given by -.Xr getcwd 3 . -.It Va .MAKEFILE_LIST -As -.Nm -reads various makefiles, including the default files and any -obtained from the command line and -.Ic .include -and -.Ic .sinclude -directives, their names will be automatically appended to the -.Va .MAKEFILE_LIST -variable. -They are added right before -.Nm -begins to parse them, so that the name of the current makefile is the -last word in this variable. -.It Ev MAKEFLAGS -The environment variable -.Ev MAKEFLAGS -may initially contain anything that -may be specified on -.Nm Ns 's -command line, -including -.Fl f -option(s). -After processing, its contents are stored in the -.Va .MAKEFLAGS -global variable, although any -.Fl f -options are omitted. -Then all options and variable assignments specified on -.Nm Ns 's -command line, except for -.Fl f , -are appended to the -.Va .MAKEFLAGS -variable. -.Pp -Whenever -.Nm -executes a program, it sets -.Ev MAKEFLAGS -in the program's environment to the current value of the -.Va .MAKEFLAGS -global variable. -Thus, if -.Ev MAKEFLAGS -in -.Nm Ns 's -environment contains any -.Fl f -options, they will not be pushed down to child programs automatically. -The -.Nm -utility effectively filters out -.Fl f -options from the environment and command line although it -passes the rest of its options down to sub-makes via -.Ev MAKEFLAGS -by default. -.Pp -When passing macro definitions and flag arguments in the -.Ev MAKEFLAGS -environment variable, -space and tab characters are quoted by preceding them with a backslash. -When reading the -.Ev MAKEFLAGS -variable from the environment, -all sequences of a backslash and one of space or tab -are replaced just with their second character -without causing a word break. -Any other occurrences of a backslash are retained. -Groups of unquoted space, tab and newline characters cause word -breaking. -.It Va .MAKEFLAGS -Initially, this global variable contains -.Nm Ns 's -current run-time options from the environment -and command line as described above, under -.Ev MAKEFLAGS . -By modifying the contents of the -.Va .MAKEFLAGS -global variable, the makefile can alter the contents of the -.Ev MAKEFLAGS -environment variable made available for all programs which -.Nm -executes. -This includes adding -.Fl f -option(s). -The current value of -.Va .MAKEFLAGS -is just copied verbatim to -.Ev MAKEFLAGS -in the environment of child programs. -.Pp -Note that any options entered to -.Va .MAKEFLAGS -neither affect the current instance of -.Nm -nor show up in its own copy of -.Ev MAKEFLAGS -instantly. -However, they do show up in the -.Ev MAKEFLAGS -environment variable of programs executed by -.Nm . -On the other hand, a direct assignment to -.Ev MAKEFLAGS -neither affects the current instance of -.Nm -nor is passed down to -.Nm Ns 's -children. -Compare with the -.Ic .MAKEFLAGS -special target below. -.It Va MFLAGS -This variable is provided for backward compatibility and -contains all the options from the -.Ev MAKEFLAGS -environment variable plus any options specified on -.Nm Ns 's -command line. -.It Va .MAKE.PID -The process-id of -.Nm . -.It Va .MAKE.PPID -The parent process-id of -.Nm . -.It Va .MAKE.JOB.PREFIX -If -.Nm -is run with -.Fl j Fl v -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: -.Li .MAKE.JOB.PREFIX=${.newline}---${MAKE:T}[${.MAKE.PID}] -would produce tokens like -.Ql ---make[1234] target --- -or -.Li .MAKE.JOB.PREFIX=---pid[${.MAKE.PID}],ppid[${.MAKE.PPID}] -would produce tokens like -.Ql ---pid[56789],ppid[1234] target --- -making it easier to track the degree of parallelism being achieved. -.It Va .TARGETS -List of targets -.Nm -is currently building. -.It Va .INCLUDES -See -.Ic .INCLUDES -special target. -.It Va .LIBS -See -.Ic .LIBS -special target. -.It Va MACHINE -Name of the machine architecture -.Nm -is running on, obtained from the -.Ev MACHINE -environment variable, or through -.Xr uname 3 -if not defined. -.It Va MACHINE_ARCH -Name of the machine architecture -.Nm -was compiled for, defined at compilation time. -.It Va VPATH -Makefiles may assign a colon-delimited list of directories to -.Va VPATH . -These directories will be searched for source files by -.Nm -after it has finished parsing all input makefiles. -.El -.Ss Variable Modifiers -Variable expansion may be modified to select or modify each word of the -variable (where a -.Dq word -is whitespace-delimited sequence of characters). -The general format of a variable expansion is as follows: -.Pp -.Dl {variable[:modifier[:...]]} -.Pp -Each modifier begins with a colon and one of the following -special characters. -The colon may be escaped with a backslash -.Pq Ql \e . -.Bl -tag -width Cm -.Sm off -.It Cm :C No / Ar pattern Xo -.No / Ar replacement -.No / Op Cm 1g -.Xc -.Sm on -Modify each word of the value, -substituting every match of the extended regular expression -.Ar pattern -(see -.Xr re_format 7 ) -with the -.Xr ed 1 Ns \-style -.Ar replacement -string. -Normally, the first occurrence of the pattern in -each word of the value is changed. -The -.Ql 1 -modifier causes the substitution to apply to at most one word; the -.Ql g -modifier causes the substitution to apply to as many instances of the -search pattern as occur in the word or words it is found in. -Note that -.Ql 1 -and -.Ql g -are orthogonal; the former specifies whether multiple words are -potentially affected, the latter whether multiple substitutions can -potentially occur within each affected word. -.It Cm :E -Replaces each word in the variable with its suffix. -.It Cm :H -Replaces each word in the variable with everything but the last component. -.It Cm :L -Converts variable to lower-case letters. -(deprecated) -.It Cm :M Ns Ar pattern -Select only those words that match the rest of the modifier. -The standard shell wildcard characters -.Pf ( Ql * , -.Ql \&? , -and -.Ql [] ) -may -be used. -The wildcard characters may be escaped with a backslash -.Pq Ql \e . -.It Cm :N Ns Ar pattern -This is identical to -.Cm :M , -but selects all words which do not match -the rest of the modifier. -.It Cm :O -Order every word in the variable alphabetically. -.It Cm :Q -Quotes every shell meta-character in the variable, so that it can be passed -safely through recursive invocations of -.Nm . -.It Cm :R -Replaces each word in the variable with everything but its suffix. -.Sm off -.It Cm :S No / Ar old_string Xo -.No / Ar new_string -.No / Op Cm g -.Xc -.Sm on -Modify the first occurrence of -.Ar old_string -in each word of the variable's value, replacing it with -.Ar new_string . -If a -.Ql g -is appended to the last slash of the pattern, all occurrences -in each word are replaced. -If -.Ar old_string -begins with a caret -.Pq Ql ^ , -.Ar old_string -is anchored at the beginning of each word. -If -.Ar old_string -ends with a dollar sign -.Pq Ql $ , -it is anchored at the end of each word. -Inside -.Ar new_string , -an ampersand -.Pq Ql & -is replaced by -.Ar old_string . -Any character may be used as a delimiter for the parts of the modifier -string. -The anchoring, ampersand, and delimiter characters may be escaped with a -backslash -.Pq Ql \e . -.Pp -Variable expansion occurs in the normal fashion inside both -.Ar old_string -and -.Ar new_string -with the single exception that a backslash is used to prevent the expansion -of a dollar sign -.Pq Ql $ , -not a preceding dollar sign as is usual. -.It Ar :old_string=new_string -This is the -.At V -style variable substitution. -It must be the last modifier specified. -If -.Ar old_string -or -.Ar new_string -do not contain the pattern matching character -.Ar % -then it is assumed that they are -anchored at the end of each word, so only suffixes or entire -words may be replaced. -Otherwise -.Ar % -is the substring of -.Ar old_string -to be replaced in -.Ar new_string . -.It Cm :T -Replaces each word in the variable with its last component. -.It Cm :tl -Converts variable to lower-case letters. -.It Cm :tu -Converts variable to upper-case letters. -.It Cm :U -Converts variable to upper-case letters. -(deprecated) -.It Cm :u -Remove adjacent duplicate words (like -.Xr uniq 1 ) . -.El -.Sh DIRECTIVES, CONDITIONALS, AND FOR LOOPS -Directives, conditionals, and for loops reminiscent -of the C programming language are provided in -.Nm . -All such structures are identified by a line beginning with a single -dot -.Pq Ql \&. -character. -The following directives are supported: -.Bl -tag -width Ds -.It Ic .include Ar <file> -.It Ic .include Ar \*qfile\*q -Include the specified makefile. -Variables between the angle brackets -or double quotes are expanded to form the file name. -If angle brackets -are used, the included makefile is expected to be in the system -makefile directory. -If double quotes are used, the including -makefile's directory and any directories specified using the -.Fl I -option are searched before the system -makefile directory. -.It Ic .sinclude Ar <file> -.It Ic .sinclude Ar \*qfile\*q -Like -.Ic .include , -but silently ignored if the file cannot be found and opened. -.It Ic .undef Ar variable -Un-define the specified global variable. -Only global variables may be un-defined. -.It Ic .error Ar message -Terminate processing of the makefile immediately. -The filename of the -makefile, the line on which the error was encountered and the specified -message are printed to the standard error output and -.Nm -terminates with exit code 1. -Variables in the message are expanded. -.It Ic .warning Ar message -Emit a warning message. -The filename of the makefile, -the line on which the warning was encountered, -and the specified message are printed to the standard error output. -Variables in the message are expanded. -.El -.Pp -Conditionals are used to determine which parts of the Makefile -to process. -They are used similarly to the conditionals supported -by the C pre-processor. -The following conditionals are supported: -.Bl -tag -width Ds -.It Xo -.Ic .if -.Oo \&! Oc Ns Ar expression -.Op Ar operator expression ... -.Xc -Test the value of an expression. -.It Xo -.Ic .ifdef -.Oo \&! Oc Ns Ar variable -.Op Ar operator variable ... -.Xc -Test the value of a variable. -.It Xo -.Ic .ifndef -.Oo \&! Oc Ns Ar variable -.Op Ar operator variable ... -.Xc -Test the value of a variable. -.It Xo -.Ic .ifmake -.Oo \&! Oc Ns Ar target -.Op Ar operator target ... -.Xc -Test the target being built. -.It Xo -.Ic .ifnmake -.Oo \&! Oc Ns Ar target -.Op Ar operator target ... -.Xc -Test the target being built. -.It Ic .else -Reverse the sense of the last conditional. -.It Xo -.Ic .elif -.Oo \&! Oc Ns Ar expression -.Op Ar operator expression ... -.Xc -A combination of -.Ic .else -followed by -.Ic .if . -.It Xo -.Ic .elifdef -.Oo \&! Oc Ns Ar variable -.Op Ar operator variable ... -.Xc -A combination of -.Ic .else -followed by -.Ic .ifdef . -.It Xo -.Ic .elifndef -.Oo \&! Oc Ns Ar variable -.Op Ar operator variable ... -.Xc -A combination of -.Ic .else -followed by -.Ic .ifndef . -.It Xo -.Ic .elifmake -.Oo \&! Oc Ns Ar target -.Op Ar operator target ... -.Xc -A combination of -.Ic .else -followed by -.Ic .ifmake . -.It Xo -.Ic .elifnmake -.Oo \&! Oc Ns Ar target -.Op Ar operator target ... -.Xc -A combination of -.Ic .else -followed by -.Ic .ifnmake . -.It Ic .endif -End the body of the conditional. -.El -.Pp -The -.Ar operator -may be any one of the following: -.Bl -tag -width "Cm XX" -.It Cm || -Logical -.Tn OR -.It Cm && -Logical -.Tn AND ; -of higher precedence than -.Sq Ic || . -.El -.Pp -As in C, -.Nm -will only evaluate a conditional as far as is necessary to determine -its value. -Parentheses may be used to change the order of evaluation. -The boolean operator -.Sq Ic !\& -may be used to logically negate an entire -conditional. -It is of higher precedence than -.Sq Ic && . -.Pp -The value of -.Ar expression -may be any of the following: -.Bl -tag -width Ic -.It Ic defined -Takes a variable name as an argument and evaluates to true if the variable -has been defined. -.It Ic make -Takes a target name as an argument and evaluates to true if the target -was specified as part of -.Nm Ns 's -command line or was declared the default target (either implicitly or -explicitly, see -.Va .MAIN ) -before the line containing the conditional. -.It Ic empty -Takes a variable, with possible modifiers, and evaluates to true if -the expansion of the variable would result in an empty string. -.It Ic exists -Takes a file name as an argument and evaluates to true if the file exists. -The file is searched for on the system search path (see -.Va .PATH ) . -.It Ic target -Takes a target name as an argument and evaluates to true if the target -has been defined. -.El -.Pp -An -.Ar expression -may also be a numeric or string comparison: -in this case, the left-hand side -.Ar must be -a variable expansion, whereas the right-hand side can be a -constant or a variable expansion. -Variable expansion is performed on both sides, after which the resulting -values are compared. -A value is interpreted as hexadecimal if it is -preceded by 0x, otherwise it is decimal; octal numbers are not supported. -.Pp -String comparison can only use the -.Sq Ic == -or -.Sq Ic != -operators, whereas numeric values (both integer and floating point) -can also be compared using the -.Sq Ic > , -.Sq Ic >= , -.Sq Ic < -and -.Sq Ic <= -operators. -.Pp -If no relational operator (and right-hand value) are given, an implicit -.Sq Ic != 0 -is used. -However be very careful in using this feature especially -when the left-hand side variable expansion returns a string. -.Pp -When -.Nm -is evaluating one of these conditional expressions, and it encounters -a word it does not recognize, either the -.Dq make -or -.Dq defined -expression is applied to it, depending on the form of the conditional. -If the form is -.Ic .if , -.Ic .ifdef -or -.Ic .ifndef , -the -.Dq defined -expression is applied. -Similarly, if the form is -.Ic .ifmake -or -.Ic .ifnmake , -the -.Dq make -expression is applied. -.Pp -If the conditional evaluates to true the parsing of the makefile continues -as before. -If it evaluates to false, the following lines are skipped. -In both cases this continues until a -.Ic .else -or -.Ic .endif -is found. -.Pp -For loops are typically used to apply a set of rules to a list of files. -The syntax of a for loop is: -.Pp -.Bl -tag -width indent -compact -.It Ic .for Ar variable Ic in Ar expression -.It <make-rules> -.It Ic .endfor -.El -.Pp -After the for -.Ar expression -is evaluated, it is split into words. -The -iteration -.Ar variable -is successively set to each word, and substituted in the -.Ic make-rules -inside the body of the for loop. -.Sh COMMENTS -Comments begin with a hash -.Pq Ql # -character, anywhere but in a shell -command line, and continue to the end of the line. -.Sh SPECIAL SOURCES -.Bl -tag -width Ic -.It Ic .IGNORE -Ignore any errors from the commands associated with this target, exactly -as if they all were preceded by a dash -.Pq Ql \- . -.It Ic .MAKE -Execute the commands associated with this target even if the -.Fl n -or -.Fl t -options were specified. -Normally used to mark recursive -.Nm Ns 's . -.It Ic .NOTMAIN -Normally -.Nm -selects the first target it encounters as the default target to be built -if no target was specified. -This source prevents this target from being selected. -.It Ic .OPTIONAL -If a target is marked with this attribute and -.Nm -cannot figure out how to create it, it will ignore this fact and assume -the file is not needed or already exists. -.It Ic .PRECIOUS -When -.Nm -is interrupted, it removes any partially made targets. -This source prevents the target from being removed. -.It Ic .SILENT -Do not echo any of the commands associated with this target, exactly -as if they all were preceded by an at sign -.Pq Ql @ . -.It Ic .USE -Turn the target into -.Nm Ns 's -version of a macro. -When the target is used as a source for another target, the other target -acquires the commands, sources, and attributes (except for -.Ic .USE ) -of the -source. -If the target already has commands, the -.Ic .USE -target's commands are appended -to them. -.It Ic .WAIT -If special -.Ic .WAIT -source appears in a dependency line, the sources that precede it are -made before the sources that succeed it in the line. -Loops are not being -detected and targets that form loops will be silently ignored. -.El -.Sh SPECIAL TARGETS -Special targets may not be included with other targets, i.e., they must be -the only target specified. -.Bl -tag -width Ic -.It Ic .BEGIN -Any command lines attached to this target are executed before anything -else is done. -.It Ic .DEFAULT -This is sort of a -.Ic .USE -rule for any target (that was used only as a -source) that -.Nm -cannot figure out any other way to create. -Only the shell script is used. -The -.Ic .IMPSRC -variable of a target that inherits -.Ic .DEFAULT Ns 's -commands is set -to the target's own name. -.It Ic .END -Any command lines attached to this target are executed after everything -else is done. -.It Ic .IGNORE -Mark each of the sources with the -.Ic .IGNORE -attribute. -If no sources are specified, this is the equivalent of specifying the -.Fl i -option. -.It Ic .INCLUDES -A list of suffixes that indicate files that can be included in a source -file. -The suffix must have already been declared with -.Ic .SUFFIXES ; -any suffix so declared will have the directories on its search path (see -.Ic .PATH ) -placed in the -.Va .INCLUDES -special variable, each preceded by a -.Fl I -flag. -.It Ic .INTERRUPT -If -.Nm -is interrupted, the commands for this target will be executed. -.It Ic .LIBS -This does for libraries what -.Ic .INCLUDES -does for include files, except that the flag used is -.Fl L . -.It Ic .MAIN -If no target is specified when -.Nm -is invoked, this target will be built. -This is always set, either -explicitly, or implicitly when -.Nm -selects the default target, to give the user a way to refer to the default -target on the command line. -.It Ic .MAKEFILEDEPS -Enable the -.Dq Remaking Makefiles -functionality, as explained in the -.Sx REMAKING MAKEFILES -section below. -.It Ic .MAKEFLAGS -This target provides a way to specify flags for -.Nm -when the makefile is used. -The flags are as if typed to the shell, though the -.Fl f -option will have -no effect. -Flags (except for -.Fl f ) -and variable assignments specified as the source -for this target are also appended to the -.Va .MAKEFLAGS -internal variable. -Please note the difference between this target and the -.Va .MAKEFLAGS -internal variable: specifying an option or variable -assignment as the source for this target will affect -.Em both -the current makefile and all processes that -.Nm -executes. -.It Ic .MFLAGS -Same as above, for backward compatibility. -.\" XXX: NOT YET!!!! -.\" .It Ic .NOTPARALLEL -.\" The named targets are executed in non parallel mode. If no targets are -.\" specified, then all targets are executed in non parallel mode. -.It Ic .NOTPARALLEL -Disable parallel mode. -.It Ic .NO_PARALLEL -Same as above, for compatibility with other -.Nm pmake -variants. -.It Ic .ORDER -The named targets are made in sequence. -.\" XXX: NOT YET!!!! -.\" .It Ic .PARALLEL -.\" The named targets are executed in parallel mode. If no targets are -.\" specified, then all targets are executed in parallel mode. -.It Ic .PATH -The sources are directories which are to be searched for files not -found in the current directory. -If no sources are specified, any previously specified directories are -deleted. -Where possible, use of -.Ic .PATH -is preferred over use of the -.Va VPATH -variable. -.It Ic .PATH\fIsuffix\fR -The sources are directories which are to be searched for suffixed files -not found in the current directory. -The -.Nm -utility -first searches the suffixed search path, before reverting to the default -path if the file is not found there. -This form is required for -.Ic .LIBS -and -.Ic .INCLUDES -to work. -.It Ic .PHONY -Apply the -.Ic .PHONY -attribute to any specified sources. -Targets with this attribute are always -considered to be out of date. -.It Ic .POSIX -Adjust -.Nm Ap s -behavior to match the applicable -.Tn POSIX -specifications. -(Note this disables the -.Dq Remaking Makefiles -feature.) -.It Ic .PRECIOUS -Apply the -.Ic .PRECIOUS -attribute to any specified sources. -If no sources are specified, the -.Ic .PRECIOUS -attribute is applied to every -target in the file. -.It Ic .SHELL -Select another shell. -The sources of this target have the format -.Ar key Ns = Ns Ar value . -The -.Ar key -is one of: -.Bl -tag -width ".Va hasErrCtl" -.It Va path -Specify the path to the new shell. -.It Va name -Specify the name of the new shell. -This may be either one of the three builtin shells (see below) or any -other name. -.It Va quiet -Specify the shell command to turn echoing off. -.It Va echo -Specify the shell command to turn echoing on. -.It Va filter -Usually shells print the echo off command before turning echoing off. -This is the exact string that will be printed by the shell and is used -to filter the shell output to remove the echo off command. -.It Va echoFlag -The shell option that turns echoing on. -.It Va errFlag -The shell option to turn on error checking. -If error checking is on, the shell should exit if a command returns -a non-zero status. -.It Va hasErrCtl -True if the shell has error control. -.It Va check -If -.Va hasErrCtl -is true then this is the shell command to turn error checking on. -If -.Va hasErrCtl -is false then this is a command template to echo commands for which error -checking is disabled. -The template must contain a -.Ql %s . -.It Va ignore -If -.Va hasErrCtl -is true, this is the shell command to turn error checking off. -If -.Va hasErrCtl -is false, this is a command template to execute a command so that errors -are ignored. -The template must contain a -.Ql %s . -.It Va meta -This is a string of meta characters of the shell. -.It Va builtins -This is a string holding all the shell's builtin commands separated by blanks. -The -.Va meta -and -.Va builtins -strings are used in compat mode. -When a command line contains neither a meta -character nor starts with a shell builtin, it is executed directly without -invoking a shell. -When one of these strings (or both) is empty all commands are executed -through a shell. -.It Va unsetenv -If true, remove the -.Ev ENV -environment variable before executing any command. -This is useful for the Korn-shell -.Pq Nm ksh . -.El -.Pp -Values that are strings must be surrounded by double quotes. -Boolean values are specified as -.Ql T -or -.Ql Y -(in either case) to mean true. -Any other value is taken to mean false. -.Pp -There are several uses of the -.Ic .SHELL -target: -.Bl -bullet -.It -Selecting one of the builtin shells. -This is done by just specifying the name of the shell with the -.Va name -keyword. -It is also possible to modify the parameters of the builtin shell by just -specifying other keywords (except for -.Va path ) . -.It -Using another executable for one of the builtin shells. -This is done by specifying the path to the executable with the -.Va path -keyword. -If the last component is the same as the name of the builtin shell, no -name needs to be specified; if it is different, the name must be given: -.Bd -literal -offset indent -\&.SHELL: path="/usr/local/bin/sh" -.Ed -.Pp -selects the builtin shell -.Dq Li sh -but will execute it from -.Pa /usr/local/bin/sh . -Like in the previous case, it is possible to modify parameters of the builtin -shell by just specifying them. -.It -Using an entirely different shell. -This is done by specifying all keywords. -.El -.Pp -The builtin shells are -.Dq Li sh , -.Dq Li csh -and -.Dq Li ksh . -Because -.Fx -has no -.Nm ksh -in -.Pa /bin , -it is unwise to specify -.Va name Ns = Ns Qq Li ksh -without also specifying a path. -.It Ic .SILENT -Apply the -.Ic .SILENT -attribute to any specified sources. -If no sources are specified, the -.Ic .SILENT -attribute is applied to every -command in the file. -.It Ic .SUFFIXES -Each source specifies a suffix to -.Nm . -If no sources are specified, any previous specified suffixes are deleted. -.It Ic .WARN -Each source specifies a warning flag as previously described for the -.Fl x -command line option. -Warning flags specified on the command line take precedence over flags -specified in the makefile. -Also, command line warning flags are pushed to sub-makes through the -.Ev MAKEFLAGS -environment variables so that a warning flag specified on the command -line will influence all sub-makes. -Several flags can be specified on a single -.Ic .WARN -target by separating them with blanks. -.El -.Sh REMAKING MAKEFILES -If the special target -.Ic .MAKEFILEDEPS -exists in the Makefile, -.Nm -enables the -.Dq Remaking Makefiles -feature. -After reading Makefile and all the files that are included using -.Ic .include -or -.Ic .sinclude -directives (source Makefiles) -.Nm -considers each source Makefile as a target and tries to rebuild it. -Both explicit and implicit rules are checked and all source Makefiles -are updated if necessary. If any of the source Makefiles were rebuilt, -.Nm -restarts from clean state. -.Pp -To prevent infinite loops the following source Makefile targets are ignored: -.Bl -bullet -.It -.Ic :: -targets that have no prerequisites -.It -.Ic \&! -targets -.It -targets that have -.Ic .PHONY -or -.Ic .EXEC -attributes -.It -targets without prerequisites and without commands -.El -.Pp -When remaking a source Makefile options -.Ic -t -(touch target), -.Ic -q -(query mode), and -.Ic -n -(no exec) do not take effect, unless source Makefile is specified -explicitly as a target in -.Nm -command line. -.Pp -Additionally, system makefiles and -.Ic .depend -are not considered as Makefiles that can be rebuilt. -.Sh ENVIRONMENT -The -.Nm -utility uses the following environment variables, if they exist: -.Ev MACHINE , -.Ev MAKE , -.Ev MAKEFLAGS , -.Ev MAKEOBJDIR , -.Ev MAKEOBJDIRPREFIX , -and -.Ev MAKESYSPATH . -.Sh FILES -.Bl -tag -width /usr/share/doc/psd/12.make -compact -.It Pa .depend -list of dependencies -.It Pa Makefile -list of dependencies -.It Pa makefile -list of dependencies -.It Pa obj -object directory -.It Pa sys.mk -system makefile -.It Pa /usr/share/mk -default system makefile directory -.It Pa /usr/share/doc/psd/12.make -PMake tutorial -.It Pa /usr/obj -default -.Ev MAKEOBJDIRPREFIX -directory. -.It Pa /etc/make.conf -default path to -.Xr make.conf 5 -.El -.Sh EXAMPLES -List all included makefiles in order visited: -.Pp -.Dl "make -V .MAKEFILE_LIST | tr \e\ \e\en" -.Sh COMPATIBILITY -Older versions of -.Nm -used -.Ev MAKE -instead of -.Ev MAKEFLAGS . -This was removed for -.Tn POSIX -compatibility. -The internal variable -.Va MAKE -is set to the same value as -.Va .MAKE ; -support for this may be removed in the future. -.Pp -The use of the -.Cm :L -and -.Cm :U -modifiers are deprecated -in -.Fx 10.0 -and the more portable (among Pmake decedents) -.Cm :tl -and -.Cm :tu -should be used instead. -.Pp -Most of the more esoteric features of -.Nm -should probably be avoided for greater compatibility. -.Sh SEE ALSO -.Xr mkdep 1 , -.Xr make.conf 5 -.Rs -.%T "PMake - A Tutorial" -.Re -in -.Pa /usr/share/doc/psd/12.make -.Sh HISTORY -A -.Nm -command appeared in PWB UNIX. -.Sh BUGS -The determination of -.Va .OBJDIR -is contorted to the point of absurdity. -.Pp -In the presence of several -.Ic .MAIN -special targets, -.Nm -silently ignores all but the first. -.Pp -.Va .TARGETS -is not set to the default target when -.Nm -is invoked without a target name and no -.Ic .MAIN -special target exists. -.Pp -The evaluation of -.Ar expression -in a test is very simple-minded. -Currently, the only form that works is -.Ql .if ${VAR} op something . -For instance, you should write tests as -.Ql .if ${VAR} == "string" -not the other way around, which would give you an error. -.Pp -For loops are expanded before tests, so a fragment such as: -.Bd -literal -offset indent -\&.for ARCH in ${SHARED_ARCHS} -\&.if ${ARCH} == ${MACHINE} - ... -\&.endif -\&.endfor -.Ed -.Pp -will not work, and should be rewritten as: -.Bd -literal -offset indent -\&.for ARCH in ${SHARED_ARCHS} -\&.if ${MACHINE} == ${ARCH} - ... -\&.endif -\&.endfor -.Ed -.Pp -The parsing code is broken with respect to handling a semicolon -after a colon, so a fragment like this will fail: -.Bd -literal -offset indent -HDRS= foo.h bar.h - -all: -\&.for h in ${HDRS:S;^;${.CURDIR}/;} - ... -\&.endfor -.Ed -.Pp -A trailing backslash in a variable value defined on the command line causes -the delimiting space in the -.Ev MAKEFLAGS -environment variable to be preceded by that backslash. -That causes a submake to not treat that space as a word delimiter. -Fixing this requires a larger rewrite of the code handling command line -macros and assignments to -.Va .MAKEFLAGS . |
