[BACK]Return to make.1 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / usr.bin / make

Annotation of src/usr.bin/make/make.1, Revision 1.170

1.170   ! sjg         1: .\"    $NetBSD: make.1,v 1.169 2010/04/07 06:45:21 wiz Exp $
1.15      thorpej     2: .\"
1.16      christos    3: .\" Copyright (c) 1990, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd         5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
1.84      agc        14: .\" 3. Neither the name of the University nor the names of its contributors
1.1       cgd        15: .\"    may be used to endorse or promote products derived from this software
                     16: .\"    without specific prior written permission.
                     17: .\"
                     18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     21: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     28: .\" SUCH DAMAGE.
                     29: .\"
1.16      christos   30: .\"    from: @(#)make.1        8.4 (Berkeley) 3/19/94
1.1       cgd        31: .\"
1.170   ! sjg        32: .Dd April 14, 2010
1.1       cgd        33: .Dt MAKE 1
                     34: .Os
                     35: .Sh NAME
                     36: .Nm make
                     37: .Nd maintain program dependencies
                     38: .Sh SYNOPSIS
1.74      wiz        39: .Nm
1.75      thorpej    40: .Op Fl BeikNnqrstWX
1.30      mycroft    41: .Bk -words
1.159     sjg        42: .Op Fl C Ar directory
                     43: .Ek
                     44: .Bk -words
1.1       cgd        45: .Op Fl D Ar variable
1.30      mycroft    46: .Ek
                     47: .Bk -words
1.1       cgd        48: .Op Fl d Ar flags
1.30      mycroft    49: .Ek
                     50: .Bk -words
1.1       cgd        51: .Op Fl f Ar makefile
1.30      mycroft    52: .Ek
                     53: .Bk -words
1.1       cgd        54: .Op Fl I Ar directory
1.30      mycroft    55: .Ek
1.1       cgd        56: .Bk -words
1.104     wiz        57: .Op Fl J Ar private
1.30      mycroft    58: .Ek
                     59: .Bk -words
1.104     wiz        60: .Op Fl j Ar max_jobs
1.44      sommerfe   61: .Ek
                     62: .Bk -words
1.13      christos   63: .Op Fl m Ar directory
1.1       cgd        64: .Ek
1.30      mycroft    65: .Bk -words
1.44      sommerfe   66: .Op Fl T Ar file
                     67: .Ek
                     68: .Bk -words
1.16      christos   69: .Op Fl V Ar variable
1.30      mycroft    70: .Ek
1.1       cgd        71: .Op Ar variable=value
1.30      mycroft    72: .Bk -words
1.1       cgd        73: .Op Ar target ...
1.30      mycroft    74: .Ek
1.1       cgd        75: .Sh DESCRIPTION
1.25      lukem      76: .Nm
1.1       cgd        77: is a program designed to simplify the maintenance of other programs.
                     78: Its input is a list of specifications as to the files upon which programs
                     79: and other files depend.
1.128     dsl        80: If no
                     81: .Fl f Ar makefile
                     82: makefile option is given,
                     83: .Nm
                     84: will try to open
1.1       cgd        85: .Ql Pa makefile
1.128     dsl        86: then
1.1       cgd        87: .Ql Pa Makefile
1.128     dsl        88: in order to find the specifications.
1.1       cgd        89: If the file
                     90: .Ql Pa .depend
                     91: exists, it is read (see
1.66      wiz        92: .Xr mkdep 1 ) .
1.1       cgd        93: .Pp
                     94: This manual page is intended as a reference document only.
                     95: For a more thorough description of
1.25      lukem      96: .Nm
1.1       cgd        97: and makefiles, please refer to
                     98: .%T "Make \- A Tutorial" .
                     99: .Pp
1.128     dsl       100: .Nm
                    101: will prepend the contents of the
                    102: .Va MAKEFLAGS
                    103: environment variable to the command line arguments before parsing them.
                    104: .Pp
1.1       cgd       105: The options are as follows:
                    106: .Bl -tag -width Ds
1.16      christos  107: .It Fl B
1.10      christos  108: Try to be backwards compatible by executing a single shell per command and
                    109: by executing the commands to make the sources of a dependency line in sequence.
1.159     sjg       110: .It Fl C Ar directory
                    111: Change to
                    112: .Ar directory
                    113: before reading the makefiles or doing anything else.
                    114: If multiple
                    115: .Fl C
                    116: options are specified, each is interpreted relative to the previous one:
                    117: .Fl C Pa / Fl C Pa etc
                    118: is equivalent to
                    119: .Fl C Pa /etc .
1.1       cgd       120: .It Fl D Ar variable
1.8       christos  121: Define
                    122: .Ar variable
1.1       cgd       123: to be 1, in the global context.
1.128     dsl       124: .It Fl d Ar [-]flags
1.1       cgd       125: Turn on debugging, and specify which portions of
1.25      lukem     126: .Nm
1.1       cgd       127: are to print debugging information.
1.128     dsl       128: Unless the flags are preceded by
                    129: .Ql -
                    130: they are added to the
                    131: .Va MAKEFLAGS
                    132: environment variable and will be processed by any child make processes.
1.141     apb       133: By default, debugging information is printed to standard error,
1.138     apb       134: but this can be changed using the
1.140     wiz       135: .Ar F
1.138     apb       136: debugging flag.
1.139     apb       137: The debugging output is always unbuffered; in addition, if debugging
                    138: is enabled but debugging output is not directed to standard output,
                    139: then the standard output is line buffered.
1.1       cgd       140: .Ar Flags
                    141: is one or more of the following:
                    142: .Bl -tag -width Ds
                    143: .It Ar A
                    144: Print all possible debugging information;
                    145: equivalent to specifying all of the debugging flags.
                    146: .It Ar a
                    147: Print debugging information about archive searching and caching.
1.147     christos  148: .It Ar C
                    149: Print debugging information about current working directory.
1.1       cgd       150: .It Ar c
                    151: Print debugging information about conditional evaluation.
                    152: .It Ar d
                    153: Print debugging information about directory searching and caching.
1.88      jmmv      154: .It Ar e
                    155: Print debugging information about failed commands and targets.
1.138     apb       156: .It Ar F Ns Oo Sy \&+ Oc Ns Ar filename
                    157: Specify where debugging output is written.
                    158: This must be the last flag, because it consumes the remainder of
                    159: the argument.
                    160: If the character immediately after the
                    161: .Ql F
                    162: flag is
                    163: .Ql \&+ ,
                    164: then the file will be opened in append mode;
                    165: otherwise the file will be overwritten.
                    166: If the file name is
                    167: .Ql stdout
                    168: or
                    169: .Ql stderr
                    170: then debugging output will be written to the
                    171: standard output or standard error output file descriptors respectively
                    172: (and the
                    173: .Ql \&+
                    174: option has no effect).
                    175: Otherwise, the output will be written to the named file.
                    176: If the file name ends
1.128     dsl       177: .Ql .%d
                    178: then the
                    179: .Ql %d
                    180: is replaced by the pid.
1.87      jmmv      181: .It Ar f
                    182: Print debugging information about loop evaluation.
1.1       cgd       183: .It Ar "g1"
                    184: Print the input graph before making anything.
                    185: .It Ar "g2"
                    186: Print the input graph after making everything, or before exiting
1.93      dsl       187: on error.
1.92      dsl       188: .It Ar "g3"
                    189: Print the input graph before exiting on error.
1.1       cgd       190: .It Ar j
                    191: Print debugging information about running multiple shells.
1.135     sjg       192: .It Ar l
                    193: Print commands in Makefiles regardless of whether or not they are prefixed by
1.137     wiz       194: .Ql @
1.135     sjg       195: or other "quiet" flags.
                    196: Also known as "loud" behavior.
1.1       cgd       197: .It Ar m
                    198: Print debugging information about making targets, including modification
                    199: dates.
1.111     jmc       200: .It Ar n
1.154     apb       201: Don't delete the temporary command scripts created when running commands.
                    202: These temporary scripts are created in the directory
                    203: referred to by the
                    204: .Ev TMPDIR
                    205: environment variable, or in
1.112     wiz       206: .Pa /tmp
1.154     apb       207: if
                    208: .Ev TMPDIR
                    209: is unset or set to the empty string.
                    210: The temporary scripts are created by
                    211: .Xr mkstemp 3 ,
1.112     wiz       212: and have names of the form
1.154     apb       213: .Pa makeXXXXXX .
1.123     wiz       214: .Em NOTE :
1.156     snj       215: This can create many files in
1.154     apb       216: .Ev TMPDIR
                    217: or
                    218: .Pa /tmp ,
1.123     wiz       219: so use with care.
1.119     dsl       220: .It Ar p
                    221: Print debugging information about makefile parsing.
1.1       cgd       222: .It Ar s
                    223: Print debugging information about suffix-transformation rules.
                    224: .It Ar t
                    225: Print debugging information about target list maintenance.
                    226: .It Ar v
                    227: Print debugging information about variable assignment.
1.49      sjg       228: .It Ar x
1.57      wiz       229: Run shell commands with
                    230: .Fl x
                    231: so the actual commands are printed as they are executed.
1.1       cgd       232: .El
                    233: .It Fl e
1.68      perry     234: Specify that environment variables override macro assignments within
1.1       cgd       235: makefiles.
                    236: .It Fl f Ar makefile
                    237: Specify a makefile to read instead of the default
1.103     wiz       238: .Ql Pa makefile .
1.1       cgd       239: If
                    240: .Ar makefile
                    241: is
                    242: .Ql Fl ,
                    243: standard input is read.
1.103     wiz       244: Multiple makefiles may be specified, and are read in the order specified.
1.1       cgd       245: .It Fl I Ar directory
                    246: Specify a directory in which to search for makefiles and included makefiles.
1.13      christos  247: The system makefile directory (or directories, see the
                    248: .Fl m
                    249: option) is automatically included as part of this list.
1.1       cgd       250: .It Fl i
                    251: Ignore non-zero exit of shell commands in the makefile.
                    252: Equivalent to specifying
                    253: .Ql Fl
                    254: before each command line in the makefile.
1.44      sommerfe  255: .It Fl J Ar private
                    256: This option should
                    257: .Em not
                    258: be specified by the user.
                    259: .Pp
                    260: When the
                    261: .Ar j
                    262: option is in use in a recursive build, this option is passed by a make
                    263: to child makes to allow all the make processes in the build to
                    264: cooperate to avoid overloading the system.
1.1       cgd       265: .It Fl j Ar max_jobs
                    266: Specify the maximum number of jobs that
1.25      lukem     267: .Nm
1.67      grant     268: may have running at any one time.
                    269: Turns compatibility mode off, unless the
1.11      christos  270: .Ar B
                    271: flag is also specified.
1.148     christos  272: When compatibility mode is off, all commands associated with a
                    273: target are executed in a single shell invocation as opposed to the
                    274: traditional one shell invocation per line.
                    275: This can break traditional scripts which change directories on each
                    276: command invocation and then expect to start with a fresh environment
                    277: on the next line.
                    278: It is more efficient to correct the scripts rather than turn backwards
                    279: compatibility on.
1.1       cgd       280: .It Fl k
                    281: Continue processing after errors are encountered, but only on those targets
                    282: that do not depend on the target whose creation caused the error.
1.13      christos  283: .It Fl m Ar directory
                    284: Specify a directory in which to search for sys.mk and makefiles included
1.99      wiz       285: via the
                    286: .Ao Ar file Ac Ns -style
                    287: include statement.
1.98      chuck     288: The
                    289: .Fl m
                    290: option can be used multiple times to form a search path.
1.13      christos  291: This path will override the default system include path: /usr/share/mk.
                    292: Furthermore the system include path will be appended to the search path used
1.99      wiz       293: for
                    294: .Qo Ar file Qc Ns -style
                    295: include statements (see the
1.13      christos  296: .Fl I
                    297: option).
1.98      chuck     298: .Pp
                    299: If a file or directory name in the
                    300: .Fl m
1.99      wiz       301: argument (or the
                    302: .Ev MAKESYSPATH
                    303: environment variable) starts with the string
                    304: .Qq \&.../
                    305: then
                    306: .Nm
                    307: will search for the specified file or directory named in the remaining part
                    308: of the argument string.
                    309: The search starts with the current directory of
1.98      chuck     310: the Makefile and then works upward towards the root of the filesystem.
1.99      wiz       311: If the search is successful, then the resulting directory replaces the
                    312: .Qq \&.../
                    313: specification in the
1.98      chuck     314: .Fl m
1.99      wiz       315: argument.
                    316: If used, this feature allows
1.98      chuck     317: .Nm
                    318: to easily search in the current source tree for customized sys.mk files
1.99      wiz       319: (e.g., by using
                    320: .Qq \&.../mk/sys.mk
                    321: as an argument).
1.1       cgd       322: .It Fl n
1.45      sommerfe  323: Display the commands that would have been executed, but do not
                    324: actually execute them unless the target depends on the .MAKE special
1.64      wiz       325: source (see below).
1.45      sommerfe  326: .It Fl N
                    327: Display the commands which would have been executed, but do not
                    328: actually execute any of them; useful for debugging top-level makefiles
                    329: without descending into subdirectories.
1.1       cgd       330: .It Fl q
                    331: Do not execute any commands, but exit 0 if the specified targets are
                    332: up-to-date and 1, otherwise.
                    333: .It Fl r
                    334: Do not use the built-in rules specified in the system makefile.
                    335: .It Fl s
                    336: Do not echo any commands as they are executed.
                    337: Equivalent to specifying
                    338: .Ql Ic @
                    339: before each command line in the makefile.
1.44      sommerfe  340: .It Fl T Ar tracefile
                    341: When used with the
1.48      wiz       342: .Fl j
1.44      sommerfe  343: flag,
                    344: append a trace record to
                    345: .Ar tracefile
                    346: for each job started and completed.
1.1       cgd       347: .It Fl t
                    348: Rather than re-building a target as specified in the makefile, create it
                    349: or update its modification time to make it appear up-to-date.
1.16      christos  350: .It Fl V Ar variable
                    351: Print
1.74      wiz       352: .Nm Ns 's
1.16      christos  353: idea of the value of
                    354: .Ar variable ,
                    355: in the global context.
                    356: Do not build any targets.
                    357: Multiple instances of this option may be specified;
                    358: the variables will be printed one per line,
                    359: with a blank line for each null or undefined variable.
1.85      sjg       360: If
                    361: .Ar variable
                    362: contains a
                    363: .Ql \&$
                    364: then the value will be expanded before printing.
1.46      christos  365: .It Fl W
                    366: Treat any warnings during makefile parsing as errors.
1.75      thorpej   367: .It Fl X
                    368: Don't export variables passed on the command line to the environment
                    369: individually.
                    370: Variables passed on the command line are still exported
                    371: via the
                    372: .Va MAKEFLAGS
                    373: environment variable.
                    374: This option may be useful on systems which have a small limit on the
                    375: size of command arguments.
1.1       cgd       376: .It Ar variable=value
                    377: Set the value of the variable
                    378: .Ar variable
                    379: to
                    380: .Ar value .
1.75      thorpej   381: Normally, all values passed on the command line are also exported to
                    382: sub-makes in the environment.
                    383: The
                    384: .Fl X
                    385: flag disables this behavior.
1.101     wiz       386: Variable assignments should follow options for POSIX compatibility
1.100     ross      387: but no ordering is enforced.
1.1       cgd       388: .El
                    389: .Pp
1.6       cgd       390: There are seven different types of lines in a makefile: file dependency
1.1       cgd       391: specifications, shell commands, variable assignments, include statements,
1.6       cgd       392: conditional directives, for loops, and comments.
1.1       cgd       393: .Pp
                    394: In general, lines may be continued from one line to the next by ending
                    395: them with a backslash
                    396: .Pq Ql \e .
                    397: The trailing newline character and initial whitespace on the following
                    398: line are compressed into a single space.
                    399: .Sh FILE DEPENDENCY SPECIFICATIONS
                    400: Dependency lines consist of one or more targets, an operator, and zero
                    401: or more sources.
1.137     wiz       402: This creates a relationship where the targets
                    403: .Dq depend
                    404: on the sources
1.1       cgd       405: and are usually created from them.
                    406: The exact relationship between the target and the source is determined
                    407: by the operator that separates them.
                    408: The three operators are as follows:
                    409: .Bl -tag -width flag
                    410: .It Ic \&:
                    411: A target is considered out-of-date if its modification time is less than
                    412: those of any of its sources.
                    413: Sources for a target accumulate over dependency lines when this operator
                    414: is used.
                    415: The target is removed if
1.25      lukem     416: .Nm
1.1       cgd       417: is interrupted.
                    418: .It Ic \&!
                    419: Targets are always re-created, but not until all sources have been
                    420: examined and re-created as necessary.
                    421: Sources for a target accumulate over dependency lines when this operator
                    422: is used.
                    423: The target is removed if
1.25      lukem     424: .Nm
1.1       cgd       425: is interrupted.
                    426: .It Ic \&::
                    427: If no sources are specified, the target is always re-created.
                    428: Otherwise, a target is considered out-of-date if any of its sources has
                    429: been modified more recently than the target.
                    430: Sources for a target do not accumulate over dependency lines when this
                    431: operator is used.
                    432: The target will not be removed if
1.25      lukem     433: .Nm
1.1       cgd       434: is interrupted.
                    435: .El
                    436: .Pp
                    437: Targets and sources may contain the shell wildcard values
1.80      wiz       438: .Ql \&? ,
1.1       cgd       439: .Ql * ,
1.103     wiz       440: .Ql [] ,
1.1       cgd       441: and
                    442: .Ql {} .
                    443: The values
1.80      wiz       444: .Ql \&? ,
1.103     wiz       445: .Ql * ,
1.1       cgd       446: and
                    447: .Ql []
                    448: may only be used as part of the final
                    449: component of the target or source, and must be used to describe existing
                    450: files.
                    451: The value
                    452: .Ql {}
                    453: need not necessarily be used to describe existing files.
                    454: Expansion is in directory order, not alphabetically as done in the shell.
                    455: .Sh SHELL COMMANDS
                    456: Each target may have associated with it a series of shell commands, normally
                    457: used to create the target.
                    458: Each of the commands in this script
                    459: .Em must
                    460: be preceded by a tab.
                    461: While any target may appear on a dependency line, only one of these
                    462: dependencies may be followed by a creation script, unless the
1.91      lukem     463: .Ql Ic \&::
1.1       cgd       464: operator is used.
                    465: .Pp
1.102     sjg       466: If the first characters of the command line are any combination of
                    467: .Ql Ic @ ,
1.103     wiz       468: .Ql Ic + ,
1.102     sjg       469: or
1.1       cgd       470: .Ql Ic \- ,
                    471: the command is treated specially.
                    472: A
                    473: .Ql Ic @
                    474: causes the command not to be echoed before it is executed.
                    475: A
1.102     sjg       476: .Ql Ic +
                    477: causes the command to be executed even when
                    478: .Fl n
                    479: is given.
                    480: This is similar to the effect of the .MAKE special source,
                    481: except that the effect can be limited to a single line of a script.
                    482: A
1.1       cgd       483: .Ql Ic \-
                    484: causes any non-zero exit status of the command line to be ignored.
                    485: .Sh VARIABLE ASSIGNMENTS
                    486: Variables in make are much like variables in the shell, and, by tradition,
                    487: consist of all upper-case letters.
1.91      lukem     488: .Ss Variable assignment modifiers
1.1       cgd       489: The five operators that can be used to assign values to variables are as
                    490: follows:
                    491: .Bl -tag -width Ds
                    492: .It Ic \&=
                    493: Assign the value to the variable.
                    494: Any previous value is overridden.
                    495: .It Ic \&+=
                    496: Append the value to the current value of the variable.
                    497: .It Ic \&?=
                    498: Assign the value to the variable if it is not already defined.
                    499: .It Ic \&:=
                    500: Assign with expansion, i.e. expand the value before assigning it
                    501: to the variable.
                    502: Normally, expansion is not done until the variable is referenced.
1.124     sjg       503: .Em NOTE :
                    504: References to undefined variables are
                    505: .Em not
1.125     wiz       506: expanded.
                    507: This can cause problems when variable modifiers are used.
1.1       cgd       508: .It Ic \&!=
                    509: Expand the value and pass it to the shell for execution and assign
                    510: the result to the variable.
                    511: Any newlines in the result are replaced with spaces.
                    512: .El
                    513: .Pp
                    514: Any white-space before the assigned
                    515: .Ar value
                    516: is removed; if the value is being appended, a single space is inserted
                    517: between the previous contents of the variable and the appended value.
                    518: .Pp
                    519: Variables are expanded by surrounding the variable name with either
                    520: curly braces
                    521: .Pq Ql {}
1.7       mycroft   522: or parentheses
1.1       cgd       523: .Pq Ql ()
                    524: and preceding it with
                    525: a dollar sign
                    526: .Pq Ql \&$ .
                    527: If the variable name contains only a single letter, the surrounding
1.7       mycroft   528: braces or parentheses are not required.
1.1       cgd       529: This shorter form is not recommended.
                    530: .Pp
1.149     dsl       531: If the variable name contains a dollar, then the name itself is expanded first.
                    532: This allows almost arbitrary variable names, however names containing dollar,
                    533: braces, parenthesis, or whitespace are really best avoided!
                    534: .Pp
                    535: If the result of expanding a variable contains a dollar sign
                    536: .Pq Ql \&$
                    537: the string is expanded again.
                    538: .Pp
1.1       cgd       539: Variable substitution occurs at two distinct times, depending on where
                    540: the variable is being used.
                    541: Variables in dependency lines are expanded as the line is read.
                    542: Variables in shell commands are expanded when the shell command is
                    543: executed.
1.91      lukem     544: .Ss Variable classes
1.1       cgd       545: The four different classes of variables (in order of increasing precedence)
                    546: are:
                    547: .Bl -tag -width Ds
                    548: .It Environment variables
                    549: Variables defined as part of
1.74      wiz       550: .Nm Ns 's
1.1       cgd       551: environment.
                    552: .It Global variables
                    553: Variables defined in the makefile or in included makefiles.
                    554: .It Command line variables
                    555: Variables defined as part of the command line.
                    556: .It Local variables
                    557: Variables that are defined specific to a certain target.
                    558: The seven local variables are as follows:
                    559: .Bl -tag -width ".ARCHIVE"
                    560: .It Va .ALLSRC
                    561: The list of all sources for this target; also known as
1.62      ross      562: .Ql Va \&\*[Gt] .
1.1       cgd       563: .It Va .ARCHIVE
                    564: The name of the archive file.
                    565: .It Va .IMPSRC
1.136     cube      566: In suffix-transformation rules, the name/path of the source from which the
1.137     wiz       567: target is to be transformed (the
                    568: .Dq implied
                    569: source); also known as
1.62      ross      570: .Ql Va \&\*[Lt] .
1.136     cube      571: It is not defined in explicit rules.
1.1       cgd       572: .It Va .MEMBER
                    573: The name of the archive member.
                    574: .It Va .OODATE
                    575: The list of sources for this target that were deemed out-of-date; also
                    576: known as
                    577: .Ql Va \&? .
                    578: .It Va .PREFIX
                    579: The file prefix of the file, containing only the file portion, no suffix
                    580: or preceding directory components; also known as
                    581: .Ql Va * .
                    582: .It Va .TARGET
                    583: The name of the target; also known as
                    584: .Ql Va @ .
                    585: .El
                    586: .Pp
                    587: The shorter forms
                    588: .Ql Va @ ,
1.80      wiz       589: .Ql Va \&? ,
1.65      christos  590: .Ql Va \&\*[Lt] ,
                    591: .Ql Va \&\*[Gt] ,
1.1       cgd       592: and
                    593: .Ql Va *
                    594: are permitted for backward
                    595: compatibility with historical makefiles and are not recommended.
                    596: The six variables
                    597: .Ql Va "@F" ,
                    598: .Ql Va "@D" ,
1.62      ross      599: .Ql Va "\*[Lt]F" ,
                    600: .Ql Va "\*[Lt]D" ,
1.66      wiz       601: .Ql Va "*F" ,
1.1       cgd       602: and
                    603: .Ql Va "*D"
1.66      wiz       604: are permitted for compatibility with
1.1       cgd       605: .At V
                    606: makefiles and are not recommended.
                    607: .Pp
                    608: Four of the local variables may be used in sources on dependency lines
                    609: because they expand to the proper value for each target on the line.
                    610: These variables are
                    611: .Ql Va .TARGET ,
                    612: .Ql Va .PREFIX ,
                    613: .Ql Va .ARCHIVE ,
                    614: and
                    615: .Ql Va .MEMBER .
1.59      bgrayson  616: .El
1.145     christos  617: .Ss Additional built-in variables
1.1       cgd       618: In addition,
1.25      lukem     619: .Nm
1.1       cgd       620: sets or knows about the following variables:
1.50      sjg       621: .Bl -tag -width .MAKEOVERRIDES
1.1       cgd       622: .It Va \&$
                    623: A single dollar sign
                    624: .Ql \&$ ,
                    625: i.e.
                    626: .Ql \&$$
                    627: expands to a single dollar
                    628: sign.
1.56      tv        629: .It Va .ALLTARGETS
1.67      grant     630: The list of all targets encountered in the Makefile.
                    631: If evaluated during
1.56      tv        632: Makefile parsing, lists only those targets encountered thus far.
1.1       cgd       633: .It Va .CURDIR
                    634: A path to the directory where
1.25      lukem     635: .Nm
1.1       cgd       636: was executed.
1.117     lukem     637: Refer to the description of
                    638: .Ql Ev PWD
                    639: for more details.
1.78      christos  640: .It Ev MAKE
1.55      tv        641: The name that
                    642: .Nm
1.89      sjg       643: was executed with
                    644: .Pq Va argv[0] .
1.126     reed      645: For compatibility
1.78      christos  646: .Nm
                    647: also sets
                    648: .Va .MAKE
                    649: with the same value.
1.97      lukem     650: The preferred variable to use is the environment variable
1.78      christos  651: .Ev MAKE
                    652: because it is more compatible with other versions of
                    653: .Nm
                    654: and cannot be confused with the special target with the same name.
1.168     sjg       655: .It Va .MAKE.DEPENDFILE
1.169     wiz       656: Names the makefile (default
1.168     sjg       657: .Ql Pa .depend )
                    658: from which generated dependencies are read.
1.134     sjg       659: .It Va .MAKE.EXPORTED
                    660: The list of variables exported by
                    661: .Nm .
1.132     sjg       662: .It Va .MAKE.JOB.PREFIX
1.137     wiz       663: If
1.132     sjg       664: .Nm
                    665: is run with
                    666: .Ar j
1.137     wiz       667: then output for each target is prefixed with a token
1.132     sjg       668: .Ql --- target ---
                    669: the first part of which can be controlled via
                    670: .Va .MAKE.JOB.PREFIX .
                    671: .br
1.137     wiz       672: For example:
1.132     sjg       673: .Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}]
                    674: would produce tokens like
                    675: .Ql ---make[1234] target ---
                    676: making it easier to track the degree of parallelism being achieved.
1.1       cgd       677: .It Ev MAKEFLAGS
                    678: The environment variable
                    679: .Ql Ev MAKEFLAGS
                    680: may contain anything that
                    681: may be specified on
1.74      wiz       682: .Nm Ns 's
1.1       cgd       683: command line.
                    684: Anything specified on
1.74      wiz       685: .Nm Ns 's
1.1       cgd       686: command line is appended to the
                    687: .Ql Ev MAKEFLAGS
                    688: variable which is then
                    689: entered into the environment for all programs which
1.25      lukem     690: .Nm
1.1       cgd       691: executes.
1.169     wiz       692: .It Va .MAKE.LEVEL
                    693: The recursion depth of
                    694: .Nm .
                    695: The initial instance of
                    696: .Nm
                    697: will be 0, and an incremented value is put into the environment
                    698: to be seen by the next generation.
                    699: This allows tests like:
                    700: .Li .if ${.MAKE.LEVEL} == 0
                    701: to protect things which should only be evaluated in the initial instance of
                    702: .Nm .
                    703: .It Va .MAKE.MAKEFILE_PREFERENCE
                    704: The ordered list of makefile names
                    705: (default
                    706: .Ql Pa makefile ,
                    707: .Ql Pa Makefile )
                    708: that
                    709: .Nm
                    710: will look for.
                    711: .It Va .MAKE.MAKEFILES
                    712: The list of makefiles read by
                    713: .Nm ,
                    714: which is useful for tracking dependencies.
                    715: Each makefile is recorded only once, regardless of the number of times read.
                    716: .It Va .MAKE.MODE
                    717: Processed after reading all makefiles.
                    718: Can affect the mode that
                    719: .Nm
                    720: runs in.
                    721: Currently just
                    722: .Ql Pa compat
                    723: mode.
1.50      sjg       724: .It Va .MAKEOVERRIDES
1.57      wiz       725: This variable is used to record the names of variables assigned to
                    726: on the command line, so that they may be exported as part of
1.50      sjg       727: .Ql Ev MAKEFLAGS .
1.57      wiz       728: This behaviour can be disabled by assigning an empty value to
1.50      sjg       729: .Ql Va .MAKEOVERRIDES
1.67      grant     730: within a makefile.
                    731: Extra variables can be exported from a makefile
1.57      wiz       732: by appending their names to
1.51      sjg       733: .Ql Va .MAKEOVERRIDES .
                    734: .Ql Ev MAKEFLAGS
1.57      wiz       735: is re-exported whenever
1.51      sjg       736: .Ql Va .MAKEOVERRIDES
                    737: is modified.
1.169     wiz       738: .It Va .MAKE.PID
                    739: The process-id of
                    740: .Nm .
                    741: .It Va .MAKE.PPID
                    742: The parent process-id of
                    743: .Nm .
1.55      tv        744: .It Va MAKE_PRINT_VAR_ON_ERROR
1.57      wiz       745: When
1.55      tv        746: .Nm
                    747: stops due to an error, it prints its name and the value of
                    748: .Ql Va .CURDIR
1.57      wiz       749: as well as the value of any variables named in
1.55      tv        750: .Ql Va MAKE_PRINT_VAR_ON_ERROR .
                    751: .It Va .newline
                    752: This variable is simply assigned a newline character as its value.
1.91      lukem     753: This allows expansions using the
                    754: .Cm \&:@
                    755: modifier to put a newline between
1.67      grant     756: iterations of the loop rather than a space.
                    757: For example, the printing of
1.55      tv        758: .Ql Va MAKE_PRINT_VAR_ON_ERROR
                    759: could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}.
                    760: .It Va .OBJDIR
                    761: A path to the directory where the targets are built.
1.117     lukem     762: Its value is determined by trying to
                    763: .Xr chdir 2
                    764: to the following directories in order and using the first match:
                    765: .Bl -enum
                    766: .It
1.118     wiz       767: .Ev ${MAKEOBJDIRPREFIX}${.CURDIR}
                    768: .Pp
1.117     lukem     769: (Only if
                    770: .Ql Ev MAKEOBJDIRPREFIX
                    771: is set in the environment or on the command line.)
                    772: .It
1.118     wiz       773: .Ev ${MAKEOBJDIR}
                    774: .Pp
1.117     lukem     775: (Only if
                    776: .Ql Ev MAKEOBJDIR
                    777: is set in the environment or on the command line.)
                    778: .It
                    779: .Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE}
                    780: .It
                    781: .Ev ${.CURDIR} Ns Pa /obj
                    782: .It
                    783: .Pa /usr/obj/ Ns Ev ${.CURDIR}
                    784: .It
                    785: .Ev ${.CURDIR}
                    786: .El
                    787: .Pp
                    788: Variable expansion is performed on the value before it's used,
                    789: so expressions such as
                    790: .Dl ${.CURDIR:C,^/usr/src,/var/obj,}
                    791: may be used.
                    792: .Pp
                    793: .Ql Va .OBJDIR
                    794: may be modified in the makefile as a global variable.
1.137     wiz       795: In all cases,
1.117     lukem     796: .Nm
                    797: will
                    798: .Xr chdir 2
                    799: to
                    800: .Ql Va .OBJDIR
                    801: and set
                    802: .Ql Ev PWD
                    803: to that directory before executing any targets.
                    804: .
1.55      tv        805: .It Va .PARSEDIR
                    806: A path to the directory of the current
                    807: .Ql Pa Makefile
                    808: being parsed.
                    809: .It Va .PARSEFILE
                    810: The basename of the current
                    811: .Ql Pa Makefile
                    812: being parsed.
                    813: This variable and
                    814: .Ql Va .PARSEDIR
                    815: are both set only while the
                    816: .Ql Pa Makefiles
                    817: are being parsed.
1.69      sjg       818: .It Va .PATH
1.82      wiz       819: A variable that represents the list of directories that
1.69      sjg       820: .Nm
1.70      wiz       821: will search for files.
                    822: The search list should be updated using the target
1.69      sjg       823: .Ql Va .PATH
                    824: rather than the variable.
1.16      christos  825: .It Ev PWD
                    826: Alternate path to the current directory.
1.25      lukem     827: .Nm
1.16      christos  828: normally sets
                    829: .Ql Va .CURDIR
                    830: to the canonical path given by
1.48      wiz       831: .Xr getcwd 3 .
1.16      christos  832: However, if the environment variable
                    833: .Ql Ev PWD
                    834: is set and gives a path to the current directory, then
1.25      lukem     835: .Nm
1.16      christos  836: sets
                    837: .Ql Va .CURDIR
                    838: to the value of
                    839: .Ql Ev PWD
1.67      grant     840: instead.
                    841: This behaviour is disabled if
1.40      sjg       842: .Ql Ev MAKEOBJDIRPREFIX
1.117     lukem     843: is set or
                    844: .Ql Ev MAKEOBJDIR
                    845: contains a variable transform.
1.16      christos  846: .Ql Ev PWD
                    847: is set to the value of
                    848: .Ql Va .OBJDIR
                    849: for all programs which
1.25      lukem     850: .Nm
1.16      christos  851: executes.
1.145     christos  852: .It Ev VPATH
1.146     wiz       853: Colon-separated
                    854: .Pq Dq \&:
                    855: lists of directories that
                    856: .Nm
                    857: will search for files.
1.145     christos  858: The variable is supported for compatibility with old make programs only,
                    859: use
                    860: .Ql Va .PATH
                    861: instead.
1.1       cgd       862: .El
1.91      lukem     863: .Ss Variable modifiers
1.1       cgd       864: Variable expansion may be modified to select or modify each word of the
1.137     wiz       865: variable (where a
                    866: .Dq word
                    867: is white-space delimited sequence of characters).
1.1       cgd       868: The general format of a variable expansion is as follows:
                    869: .Pp
1.120     sjg       870: .Dl ${variable[:modifier[:...]]}
1.1       cgd       871: .Pp
1.97      lukem     872: Each modifier begins with a colon,
                    873: which may be escaped with a backslash
1.1       cgd       874: .Pq Ql \e .
1.120     sjg       875: .Pp
                    876: A set of modifiers can be specified via a variable, as follows:
                    877: .Pp
                    878: .Dl modifier_variable=modifier[:...]
                    879: .Dl ${variable:${modifier_variable}[:...]}
                    880: .Pp
                    881: In this case the first modifier in the modifier_variable does not
                    882: start with a colon, since that must appear in the referencing
                    883: variable.
                    884: If any of the modifiers in the modifier_variable contain a dollar sign
                    885: .Pq Ql $ ,
                    886: these must be doubled to avoid early expansion.
                    887: .Pp
1.97      lukem     888: The supported modifiers are:
1.61      ross      889: .Bl -tag -width EEE
1.91      lukem     890: .It Cm \&:E
1.1       cgd       891: Replaces each word in the variable with its suffix.
1.91      lukem     892: .It Cm \&:H
1.1       cgd       893: Replaces each word in the variable with everything but the last component.
1.91      lukem     894: .It Cm \&:M Ns Ar pattern
1.72      uebayasi  895: Select only those words that match
                    896: .Ar pattern .
1.1       cgd       897: The standard shell wildcard characters
                    898: .Pf ( Ql * ,
1.80      wiz       899: .Ql \&? ,
1.1       cgd       900: and
                    901: .Ql Op )
                    902: may
                    903: be used.
                    904: The wildcard characters may be escaped with a backslash
                    905: .Pq Ql \e .
1.91      lukem     906: .It Cm \&:N Ns Ar pattern
1.1       cgd       907: This is identical to
1.91      lukem     908: .Ql Cm \&:M ,
1.1       cgd       909: but selects all words which do not match
1.72      uebayasi  910: .Ar pattern .
1.91      lukem     911: .It Cm \&:O
1.109     wiz       912: Order every word in variable alphabetically.
                    913: To sort words in
                    914: reverse order use the
1.108     sjg       915: .Ql Cm \&:O:[-1..1]
                    916: combination of modifiers.
                    917: .It Cm \&:Ox
1.109     wiz       918: Randomize words in variable.
                    919: The results will be different each time you are referring to the
                    920: modified variable; use the assignment with expansion
1.108     sjg       921: .Pq Ql Cm \&:=
1.109     wiz       922: to prevent such behaviour.
                    923: For example,
1.108     sjg       924: .Bd -literal -offset indent
                    925: LIST=                  uno due tre quattro
                    926: RANDOM_LIST=           ${LIST:Ox}
                    927: STATIC_RANDOM_LIST:=   ${LIST:Ox}
                    928:
                    929: all:
                    930:        @echo "${RANDOM_LIST}"
                    931:        @echo "${RANDOM_LIST}"
                    932:        @echo "${STATIC_RANDOM_LIST}"
                    933:        @echo "${STATIC_RANDOM_LIST}"
                    934: .Ed
1.109     wiz       935: may produce output similar to:
1.108     sjg       936: .Bd -literal -offset indent
                    937: quattro due tre uno
                    938: tre due quattro uno
                    939: due uno quattro tre
                    940: due uno quattro tre
                    941: .Ed
1.91      lukem     942: .It Cm \&:Q
1.17      christos  943: Quotes every shell meta-character in the variable, so that it can be passed
                    944: safely through recursive invocations of
1.74      wiz       945: .Nm .
1.91      lukem     946: .It Cm \&:R
1.1       cgd       947: Replaces each word in the variable with everything but its suffix.
1.170   ! sjg       948: .It Cm \&:tA
        !           949: Attempt to convert variable to an absolute path using
        !           950: .Xr realpath 3 ,
        !           951: if that fails, the value is unchanged.
1.91      lukem     952: .It Cm \&:tl
1.60      pk        953: Converts variable to lower-case letters.
1.91      lukem     954: .It Cm \&:ts Ns Ar c
1.81      sjg       955: Words in the variable are normally separated by a space on expansion.
                    956: This modifier sets the separator to the character
                    957: .Ar c .
                    958: If
                    959: .Ar c
                    960: is omitted, then no separator is used.
1.170   ! sjg       961: The common escapes (including octal numeric codes), work as expected.
1.91      lukem     962: .It Cm \&:tu
1.82      wiz       963: Converts variable to upper-case letters.
1.91      lukem     964: .It Cm \&:tW
1.89      sjg       965: Causes the value to be treated as a single word
                    966: (possibly containing embedded white space).
                    967: See also
1.91      lukem     968: .Ql Cm \&:[*] .
                    969: .It Cm \&:tw
1.89      sjg       970: Causes the value to be treated as a sequence of
                    971: words delimited by white space.
                    972: See also
1.91      lukem     973: .Ql Cm \&:[@] .
1.1       cgd       974: .Sm off
1.164     joerg     975: .It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW
1.1       cgd       976: .Sm on
                    977: Modify the first occurrence of
1.17      christos  978: .Ar old_string
                    979: in the variable's value, replacing it with
                    980: .Ar new_string .
1.1       cgd       981: If a
                    982: .Ql g
                    983: is appended to the last slash of the pattern, all occurrences
                    984: in each word are replaced.
1.17      christos  985: If a
                    986: .Ql 1
                    987: is appended to the last slash of the pattern, only the first word
                    988: is affected.
1.89      sjg       989: If a
                    990: .Ql W
                    991: is appended to the last slash of the pattern,
                    992: then the value is treated as a single word
                    993: (possibly containing embedded white space).
1.1       cgd       994: If
1.17      christos  995: .Ar old_string
                    996: begins with a caret
1.1       cgd       997: .Pq Ql ^ ,
1.17      christos  998: .Ar old_string
1.1       cgd       999: is anchored at the beginning of each word.
                   1000: If
1.17      christos 1001: .Ar old_string
1.1       cgd      1002: ends with a dollar sign
                   1003: .Pq Ql \&$ ,
                   1004: it is anchored at the end of each word.
                   1005: Inside
                   1006: .Ar new_string ,
                   1007: an ampersand
1.62      ross     1008: .Pq Ql \*[Am]
1.1       cgd      1009: is replaced by
1.17      christos 1010: .Ar old_string
                   1011: (without any
                   1012: .Ql ^
                   1013: or
                   1014: .Ql \&$ ) .
1.1       cgd      1015: Any character may be used as a delimiter for the parts of the modifier
                   1016: string.
                   1017: The anchoring, ampersand and delimiter characters may be escaped with a
                   1018: backslash
                   1019: .Pq Ql \e .
                   1020: .Pp
                   1021: Variable expansion occurs in the normal fashion inside both
                   1022: .Ar old_string
                   1023: and
                   1024: .Ar new_string
                   1025: with the single exception that a backslash is used to prevent the expansion
                   1026: of a dollar sign
1.17      christos 1027: .Pq Ql \&$ ,
1.1       cgd      1028: not a preceding dollar sign as is usual.
1.17      christos 1029: .Sm off
1.164     joerg    1030: .It Cm \&:C No \&/ Ar pattern No \&/ Ar replacement No \&/ Op Cm 1gW
1.17      christos 1031: .Sm on
                   1032: The
1.91      lukem    1033: .Cm \&:C
1.17      christos 1034: modifier is just like the
1.91      lukem    1035: .Cm \&:S
1.37      msaitoh  1036: modifier except that the old and new strings, instead of being
1.17      christos 1037: simple strings, are a regular expression (see
                   1038: .Xr regex 3 )
1.72      uebayasi 1039: string
                   1040: .Ar pattern
1.17      christos 1041: and an
                   1042: .Xr ed 1 Ns \-style
1.72      uebayasi 1043: string
                   1044: .Ar replacement .
                   1045: Normally, the first occurrence of the pattern
                   1046: .Ar pattern
                   1047: in each word of the value is substituted with
                   1048: .Ar replacement .
1.67      grant    1049: The
1.17      christos 1050: .Ql 1
                   1051: modifier causes the substitution to apply to at most one word; the
                   1052: .Ql g
                   1053: modifier causes the substitution to apply to as many instances of the
1.72      uebayasi 1054: search pattern
                   1055: .Ar pattern
1.89      sjg      1056: as occur in the word or words it is found in; the
                   1057: .Ql W
                   1058: modifier causes the value to be treated as a single word
                   1059: (possibly containing embedded white space).
1.67      grant    1060: Note that
1.17      christos 1061: .Ql 1
                   1062: and
                   1063: .Ql g
                   1064: are orthogonal; the former specifies whether multiple words are
                   1065: potentially affected, the latter whether multiple substitutions can
                   1066: potentially occur within each affected word.
1.91      lukem    1067: .It Cm \&:T
1.1       cgd      1068: Replaces each word in the variable with its last component.
1.91      lukem    1069: .It Cm \&:u
1.43      christos 1070: Remove adjacent duplicate words (like
1.57      wiz      1071: .Xr uniq 1 ) .
1.91      lukem    1072: .Sm off
                   1073: .It Cm \&:\&? Ar true_string Cm \&: Ar false_string
                   1074: .Sm on
1.152     dsl      1075: If the variable name (not its value), when parsed as a .if conditional
                   1076: expression, evaluates to true, return as its value the
1.57      wiz      1077: .Ar true_string ,
1.27      christos 1078: otherwise return the
1.57      wiz      1079: .Ar false_string .
1.152     dsl      1080: Since the variable name is used as the expression, \&:\&? must be the
                   1081: first modifier after the variable name itself - which will, of course,
                   1082: usually contain variable expansions.
1.162     dsl      1083: A common error is trying to use expressions like
                   1084: .Dl ${NUMBERS:M42:?match:no}
                   1085: which actually tests defined(NUMBERS),
                   1086: to determine is any words match "42" you need to use something like:
                   1087: .Dl ${${NUMBERS:M42} != "":?match:no} .
1.91      lukem    1088: .It Ar :old_string=new_string
1.1       cgd      1089: This is the
                   1090: .At V
                   1091: style variable substitution.
                   1092: It must be the last modifier specified.
1.16      christos 1093: If
1.6       cgd      1094: .Ar old_string
                   1095: or
                   1096: .Ar new_string
                   1097: do not contain the pattern matching character
                   1098: .Ar %
1.16      christos 1099: then it is assumed that they are
1.6       cgd      1100: anchored at the end of each word, so only suffixes or entire
1.67      grant    1101: words may be replaced.
                   1102: Otherwise
1.6       cgd      1103: .Ar %
1.16      christos 1104: is the substring of
                   1105: .Ar old_string
1.6       cgd      1106: to be replaced in
1.64      wiz      1107: .Ar new_string .
1.95      jmc      1108: .Pp
                   1109: Variable expansion occurs in the normal fashion inside both
                   1110: .Ar old_string
                   1111: and
                   1112: .Ar new_string
1.96      wiz      1113: with the single exception that a backslash is used to prevent the
                   1114: expansion of a dollar sign
                   1115: .Pq Ql \&$ ,
                   1116: not a preceding dollar sign as is usual.
1.91      lukem    1117: .Sm off
1.164     joerg    1118: .It Cm \&:@ Ar temp Cm @ Ar string Cm @
1.91      lukem    1119: .Sm on
1.40      sjg      1120: This is the loop expansion mechanism from the OSF Development
1.67      grant    1121: Environment (ODE) make.
                   1122: Unlike
1.48      wiz      1123: .Cm \&.for
1.40      sjg      1124: loops expansion occurs at the time of
1.67      grant    1125: reference.
                   1126: Assign
1.40      sjg      1127: .Ar temp
                   1128: to each word in the variable and evaluate
                   1129: .Ar string .
1.48      wiz      1130: The ODE convention is that
1.40      sjg      1131: .Ar temp
1.67      grant    1132: should start and end with a period.
                   1133: For example.
1.40      sjg      1134: .Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
1.91      lukem    1135: .It Cm \&:U Ns Ar newval
1.40      sjg      1136: If the variable is undefined
                   1137: .Ar newval
1.63      lukem    1138: is the value.
                   1139: If the variable is defined, the existing value is returned.
1.67      grant    1140: This is another ODE make feature.
                   1141: It is handy for setting per-target CFLAGS for instance:
1.40      sjg      1142: .Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
1.63      lukem    1143: If a value is only required if the variable is undefined, use:
                   1144: .Dl ${VAR:D:Unewval}
1.91      lukem    1145: .It Cm \&:D Ns Ar newval
1.40      sjg      1146: If the variable is defined
                   1147: .Ar newval
                   1148: is the value.
1.91      lukem    1149: .It Cm \&:L
1.40      sjg      1150: The name of the variable is the value.
1.91      lukem    1151: .It Cm \&:P
1.40      sjg      1152: The path of the node which has the same name as the variable
1.67      grant    1153: is the value.
                   1154: If no such node exists or its path is null, then the
1.40      sjg      1155: name of the variable is used.
1.91      lukem    1156: .Sm off
                   1157: .It Cm \&:\&! Ar cmd Cm \&!
                   1158: .Sm on
1.40      sjg      1159: The output of running
                   1160: .Ar cmd
                   1161: is the value.
1.91      lukem    1162: .It Cm \&:sh
1.40      sjg      1163: If the variable is non-empty it is run as a command and the output
                   1164: becomes the new value.
1.91      lukem    1165: .It Cm \&::= Ns Ar str
1.48      wiz      1166: The variable is assigned the value
1.41      sjg      1167: .Ar str
1.67      grant    1168: after substitution.
                   1169: This modifier and its variations are useful in
1.149     dsl      1170: obscure situations such as wanting to set a variable when shell commands
                   1171: are being parsed.
1.67      grant    1172: These assignment modifiers always expand to
1.41      sjg      1173: nothing, so if appearing in a rule line by themselves should be
1.48      wiz      1174: preceded with something to keep
1.41      sjg      1175: .Nm
1.67      grant    1176: happy.
1.149     dsl      1177: .Pp
1.91      lukem    1178: The
                   1179: .Ql Cm \&::
1.42      sjg      1180: helps avoid false matches with the
                   1181: .At V
1.48      wiz      1182: style
1.91      lukem    1183: .Cm \&:=
1.48      wiz      1184: modifier and since substitution always occurs the
1.91      lukem    1185: .Cm \&::=
1.42      sjg      1186: form is vaguely appropriate.
1.91      lukem    1187: .It Cm \&::?= Ns Ar str
1.41      sjg      1188: As for
1.91      lukem    1189: .Cm \&::=
1.41      sjg      1190: but only if the variable does not already have a value.
1.91      lukem    1191: .It Cm \&::+= Ns Ar str
1.48      wiz      1192: Append
1.41      sjg      1193: .Ar str
                   1194: to the variable.
1.91      lukem    1195: .It Cm \&::!= Ns Ar cmd
1.48      wiz      1196: Assign the output of
1.41      sjg      1197: .Ar cmd
                   1198: to the variable.
1.91      lukem    1199: .It Cm \&:\&[ Ns Ar range Ns Cm \&]
1.89      sjg      1200: Selects one or more words from the value,
                   1201: or performs other operations related to the way in which the
                   1202: value is divided into words.
                   1203: .Pp
                   1204: Ordinarily, a value is treated as a sequence of words
                   1205: delimited by white space.
                   1206: Some modifiers suppress this behaviour,
                   1207: causing a value to be treated as a single word
                   1208: (possibly containing embedded white space).
                   1209: An empty value, or a value that consists entirely of white-space,
                   1210: is treated as a single word.
                   1211: For the purposes of the
1.91      lukem    1212: .Ql Cm \&:[]
1.89      sjg      1213: modifier, the words are indexed both forwards using positive integers
                   1214: (where index 1 represents the first word),
                   1215: and backwards using negative integers
                   1216: (where index -1 represents the last word).
                   1217: .Pp
                   1218: The
                   1219: .Ar range
                   1220: is subjected to variable expansion, and the expanded result is
                   1221: then interpreted as follows:
                   1222: .Bl -tag -width index
1.90      jdolecek 1223: .\" :[n]
1.89      sjg      1224: .It Ar index
                   1225: Selects a single word from the value.
1.90      jdolecek 1226: .\" :[start..end]
1.89      sjg      1227: .It Ar start Ns Cm \&.. Ns Ar end
                   1228: Selects all words from
                   1229: .Ar start
                   1230: to
                   1231: .Ar end ,
                   1232: inclusive.
                   1233: For example,
1.91      lukem    1234: .Ql Cm \&:[2..-1]
1.89      sjg      1235: selects all words from the second word to the last word.
                   1236: If
                   1237: .Ar start
                   1238: is greater than
                   1239: .Ar end ,
1.91      lukem    1240: then the words are output in reverse order.
                   1241: For example,
                   1242: .Ql Cm \&:[-1..1]
1.89      sjg      1243: selects all the words from last to first.
1.90      jdolecek 1244: .\" :[*]
1.89      sjg      1245: .It Cm \&*
                   1246: Causes subsequent modifiers to treat the value as a single word
1.109     wiz      1247: (possibly containing embedded white space).
                   1248: Analogous to the effect of
1.94      wiz      1249: \&"$*\&"
1.89      sjg      1250: in Bourne shell.
1.90      jdolecek 1251: .\" :[0]
1.89      sjg      1252: .It 0
                   1253: Means the same as
1.91      lukem    1254: .Ql Cm \&:[*] .
1.90      jdolecek 1255: .\" :[*]
1.89      sjg      1256: .It Cm \&@
                   1257: Causes subsequent modifiers to treat the value as a sequence of words
1.109     wiz      1258: delimited by white space.
                   1259: Analogous to the effect of
1.94      wiz      1260: \&"$@\&"
1.89      sjg      1261: in Bourne shell.
1.90      jdolecek 1262: .\" :[#]
1.89      sjg      1263: .It Cm \&#
                   1264: Returns the number of words in the value.
                   1265: .El \" :[range]
1.6       cgd      1266: .El
                   1267: .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1.16      christos 1268: Makefile inclusion, conditional structures and for loops  reminiscent
1.6       cgd      1269: of the C programming language are provided in
1.74      wiz      1270: .Nm .
1.1       cgd      1271: All such structures are identified by a line beginning with a single
                   1272: dot
                   1273: .Pq Ql \&.
                   1274: character.
                   1275: Files are included with either
1.29      ross     1276: .Cm \&.include Aq Ar file
1.1       cgd      1277: or
1.29      ross     1278: .Cm \&.include Pf \*q Ar file Ns \*q .
1.1       cgd      1279: Variables between the angle brackets or double quotes are expanded
                   1280: to form the file name.
                   1281: If angle brackets are used, the included makefile is expected to be in
                   1282: the system makefile directory.
                   1283: If double quotes are used, the including makefile's directory and any
                   1284: directories specified using the
                   1285: .Fl I
                   1286: option are searched before the system
                   1287: makefile directory.
1.28      christos 1288: For compatibility with other versions of
                   1289: .Nm
                   1290: .Ql include file ...
1.67      grant    1291: is also accepted.
                   1292: If the include statement is written as
1.29      ross     1293: .Cm .-include
                   1294: or as
                   1295: .Cm .sinclude
1.28      christos 1296: then errors locating and/or opening include files are ignored.
1.1       cgd      1297: .Pp
                   1298: Conditional expressions are also preceded by a single dot as the first
1.5       jtc      1299: character of a line.
1.1       cgd      1300: The possible conditionals are as follows:
                   1301: .Bl -tag -width Ds
1.168     sjg      1302: .It Ic .error Ar message
                   1303: The message is printed along with the name of the makefile and line number,
                   1304: then
                   1305: .Nm
                   1306: will exit.
1.165     sjg      1307: .It Ic .export Ar variable ...
1.133     sjg      1308: Export the specified global variable.
1.165     sjg      1309: If no variable list is provided, all globals are exported
1.133     sjg      1310: except for internal variables (those that start with
1.157     wiz      1311: .Ql \&. ) .
1.133     sjg      1312: This is not affected by the
                   1313: .Fl X
                   1314: flag, so should be used with caution.
1.165     sjg      1315: .Pp
1.133     sjg      1316: Appending a variable name to
                   1317: .Va .MAKE.EXPORTED
                   1318: is equivalent to exporting a variable.
1.168     sjg      1319: .It Ic .info Ar message
                   1320: The message is printed along with the name of the makefile and line number.
1.169     wiz      1321: .It Ic .undef Ar variable
                   1322: Un-define the specified global variable.
                   1323: Only global variables may be un-defined.
1.165     sjg      1324: .It Ic .unexport Ar variable ...
                   1325: The opposite of
                   1326: .Ql .export .
                   1327: The specified global
1.166     wiz      1328: .Va variable
                   1329: will be removed from
1.165     sjg      1330: .Va .MAKE.EXPORTED .
                   1331: If no variable list is provided, all globals are unexported,
                   1332: and
1.166     wiz      1333: .Va .MAKE.EXPORTED
1.165     sjg      1334: deleted.
                   1335: .It Ic .unexport-env
                   1336: Unexport all globals previously exported and
                   1337: clear the environment inherited from the parent.
1.166     wiz      1338: This operation will cause a memory leak of the original environment,
                   1339: so should be used sparingly.
                   1340: Testing for
1.165     sjg      1341: .Va .MAKE.LEVEL
                   1342: being 0, would make sense.
1.166     wiz      1343: Also note that any variables which originated in the parent environment
1.165     sjg      1344: should be explicitly preserved if desired.
                   1345: For example:
                   1346: .Bd -literal -offset indent
                   1347: .Li .if ${.MAKE.LEVEL} == 0
                   1348: PATH := ${PATH}
                   1349: .Li .unexport-env
                   1350: .Li .export PATH
                   1351: .Li .endif
                   1352: .Pp
                   1353: .Ed
1.166     wiz      1354: Would result in an environment containing only
1.165     sjg      1355: .Ql Ev PATH ,
                   1356: which is the minimal useful environment.
                   1357: Actually
1.166     wiz      1358: .Ql Ev .MAKE.LEVEL
1.165     sjg      1359: will also be pushed into the new environment.
1.168     sjg      1360: .It Ic .warning Ar message
                   1361: The message prefixed by
                   1362: .Ql Pa warning:
                   1363: is printed along with the name of the makefile and line number.
1.164     joerg    1364: .It Ic \&.if Oo \&! Oc Ns Ar expression Op Ar operator expression ...
1.1       cgd      1365: Test the value of an expression.
1.164     joerg    1366: .It Ic .ifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.7       mycroft  1367: Test the value of a variable.
1.164     joerg    1368: .It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.7       mycroft  1369: Test the value of a variable.
1.164     joerg    1370: .It Ic .ifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.7       mycroft  1371: Test the target being built.
1.164     joerg    1372: .It Ic .ifnmake Oo \&! Ns Oc Ar target Op Ar operator target ...
1.1       cgd      1373: Test the target being built.
                   1374: .It Ic .else
                   1375: Reverse the sense of the last conditional.
1.164     joerg    1376: .It Ic .elif Oo \&! Ns Oc Ar expression Op Ar operator expression ...
1.1       cgd      1377: A combination of
                   1378: .Ql Ic .else
                   1379: followed by
                   1380: .Ql Ic .if .
1.164     joerg    1381: .It Ic .elifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.1       cgd      1382: A combination of
                   1383: .Ql Ic .else
                   1384: followed by
                   1385: .Ql Ic .ifdef .
1.164     joerg    1386: .It Ic .elifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.1       cgd      1387: A combination of
                   1388: .Ql Ic .else
                   1389: followed by
                   1390: .Ql Ic .ifndef .
1.164     joerg    1391: .It Ic .elifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.1       cgd      1392: A combination of
                   1393: .Ql Ic .else
                   1394: followed by
                   1395: .Ql Ic .ifmake .
1.164     joerg    1396: .It Ic .elifnmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.1       cgd      1397: A combination of
                   1398: .Ql Ic .else
                   1399: followed by
                   1400: .Ql Ic .ifnmake .
                   1401: .It Ic .endif
                   1402: End the body of the conditional.
                   1403: .El
                   1404: .Pp
                   1405: The
                   1406: .Ar operator
                   1407: may be any one of the following:
                   1408: .Bl -tag -width "Cm XX"
                   1409: .It Cm \&|\&|
1.64      wiz      1410: Logical OR.
1.62      ross     1411: .It Cm \&\*[Am]\*[Am]
1.1       cgd      1412: Logical
                   1413: .Tn AND ;
                   1414: of higher precedence than
1.26      hubertf  1415: .Dq \&|\&| .
1.1       cgd      1416: .El
                   1417: .Pp
                   1418: As in C,
1.25      lukem    1419: .Nm
1.1       cgd      1420: will only evaluate a conditional as far as is necessary to determine
                   1421: its value.
1.16      christos 1422: Parentheses may be used to change the order of evaluation.
1.1       cgd      1423: The boolean operator
                   1424: .Ql Ic \&!
                   1425: may be used to logically negate an entire
                   1426: conditional.
1.5       jtc      1427: It is of higher precedence than
1.62      ross     1428: .Ql Ic \&\*[Am]\*[Am] .
1.1       cgd      1429: .Pp
                   1430: The value of
                   1431: .Ar expression
                   1432: may be any of the following:
1.61      ross     1433: .Bl -tag -width defined
1.1       cgd      1434: .It Ic defined
                   1435: Takes a variable name as an argument and evaluates to true if the variable
                   1436: has been defined.
                   1437: .It Ic make
                   1438: Takes a target name as an argument and evaluates to true if the target
                   1439: was specified as part of
1.74      wiz      1440: .Nm Ns 's
1.1       cgd      1441: command line or was declared the default target (either implicitly or
                   1442: explicitly, see
                   1443: .Va .MAIN )
                   1444: before the line containing the conditional.
                   1445: .It Ic empty
1.5       jtc      1446: Takes a variable, with possible modifiers, and evaluates to true if
1.1       cgd      1447: the expansion of the variable would result in an empty string.
                   1448: .It Ic exists
                   1449: Takes a file name as an argument and evaluates to true if the file exists.
                   1450: The file is searched for on the system search path (see
                   1451: .Va .PATH ) .
                   1452: .It Ic target
                   1453: Takes a target name as an argument and evaluates to true if the target
                   1454: has been defined.
1.47      christos 1455: .It Ic commands
                   1456: Takes a target name as an argument and evaluates to true if the target
                   1457: has been defined and has commands associated with it.
1.1       cgd      1458: .El
                   1459: .Pp
                   1460: .Ar Expression
1.67      grant    1461: may also be an arithmetic or string comparison.
                   1462: Variable expansion is
1.6       cgd      1463: performed on both sides of the comparison, after which the integral
1.67      grant    1464: values are compared.
                   1465: A value is interpreted as hexadecimal if it is
1.6       cgd      1466: preceded by 0x, otherwise it is decimal; octal numbers are not supported.
1.67      grant    1467: The standard C relational operators are all supported.
                   1468: If after
1.6       cgd      1469: variable expansion, either the left or right hand side of a
1.1       cgd      1470: .Ql Ic ==
                   1471: or
                   1472: .Ql Ic "!="
1.6       cgd      1473: operator is not an integral value, then
                   1474: string comparison is performed between the expanded
                   1475: variables.
1.1       cgd      1476: If no relational operator is given, it is assumed that the expanded
1.102     sjg      1477: variable is being compared against 0 or an empty string in the case
                   1478: of a string comparison.
1.1       cgd      1479: .Pp
                   1480: When
1.25      lukem    1481: .Nm
1.150     dsl      1482: is evaluating one of these conditional expressions, and it encounters
                   1483: a (white-space separated) word it doesn't recognize, either the
1.137     wiz      1484: .Dq make
                   1485: or
                   1486: .Dq defined
1.1       cgd      1487: expression is applied to it, depending on the form of the conditional.
                   1488: If the form is
1.150     dsl      1489: .Ql Ic .ifdef ,
                   1490: .Ql Ic .ifndef ,
1.1       cgd      1491: or
1.150     dsl      1492: .Ql Ic .if
1.137     wiz      1493: the
                   1494: .Dq defined
                   1495: expression is applied.
1.1       cgd      1496: Similarly, if the form is
                   1497: .Ql Ic .ifmake
                   1498: or
1.137     wiz      1499: .Ql Ic .ifnmake , the
                   1500: .Dq make
1.1       cgd      1501: expression is applied.
                   1502: .Pp
                   1503: If the conditional evaluates to true the parsing of the makefile continues
                   1504: as before.
                   1505: If it evaluates to false, the following lines are skipped.
                   1506: In both cases this continues until a
                   1507: .Ql Ic .else
                   1508: or
                   1509: .Ql Ic .endif
                   1510: is found.
1.16      christos 1511: .Pp
1.6       cgd      1512: For loops are typically used to apply a set of rules to a list of files.
                   1513: The syntax of a for loop is:
1.59      bgrayson 1514: .Pp
                   1515: .Bl -tag -compact -width Ds
1.164     joerg    1516: .It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression
1.80      wiz      1517: .It Aq make-rules
                   1518: .It Ic \&.endfor
1.6       cgd      1519: .El
1.59      bgrayson 1520: .Pp
1.6       cgd      1521: After the for
1.16      christos 1522: .Ic expression
1.67      grant    1523: is evaluated, it is split into words.
                   1524: On each iteration of the loop, one word is taken and assigned to each
1.39      christos 1525: .Ic variable ,
                   1526: in order, and these
                   1527: .Ic variables
                   1528: are substituted into the
1.16      christos 1529: .Ic make-rules
1.6       cgd      1530: inside the body of the for loop.
1.39      christos 1531: The number of words must come out even; that is, if there are three
                   1532: iteration variables, the number of words provided must be a multiple
                   1533: of three.
1.1       cgd      1534: .Sh COMMENTS
                   1535: Comments begin with a hash
                   1536: .Pq Ql \&#
                   1537: character, anywhere but in a shell
1.114     wiz      1538: command line, and continue to the end of an unescaped new line.
1.97      lukem    1539: .Sh SPECIAL SOURCES (ATTRIBUTES)
1.61      ross     1540: .Bl -tag -width .IGNOREx
1.97      lukem    1541: .It Ic .EXEC
                   1542: Target is never out of date, but always execute commands anyway.
1.1       cgd      1543: .It Ic .IGNORE
                   1544: Ignore any errors from the commands associated with this target, exactly
                   1545: as if they all were preceded by a dash
                   1546: .Pq Ql \- .
1.97      lukem    1547: .\" .It Ic .INVISIBLE
                   1548: .\" XXX
                   1549: .\" .It Ic .JOIN
                   1550: .\" XXX
1.18      christos 1551: .It Ic .MADE
1.48      wiz      1552: Mark all sources of this target as being up-to-date.
1.1       cgd      1553: .It Ic .MAKE
                   1554: Execute the commands associated with this target even if the
                   1555: .Fl n
                   1556: or
                   1557: .Fl t
                   1558: options were specified.
                   1559: Normally used to mark recursive
1.74      wiz      1560: .Nm Ns 's .
1.97      lukem    1561: .It Ic .NOPATH
                   1562: Do not search for the target in the directories specified by
                   1563: .Ic .PATH .
1.1       cgd      1564: .It Ic .NOTMAIN
                   1565: Normally
1.25      lukem    1566: .Nm
1.1       cgd      1567: selects the first target it encounters as the default target to be built
                   1568: if no target was specified.
                   1569: This source prevents this target from being selected.
                   1570: .It Ic .OPTIONAL
                   1571: If a target is marked with this attribute and
1.25      lukem    1572: .Nm
1.1       cgd      1573: can't figure out how to create it, it will ignore this fact and assume
                   1574: the file isn't needed or already exists.
1.97      lukem    1575: .It Ic .PHONY
                   1576: The target does not
                   1577: correspond to an actual file; it is always considered to be out of date,
                   1578: and will not be created with the
                   1579: .Fl t
                   1580: option.
1.1       cgd      1581: .It Ic .PRECIOUS
                   1582: When
1.25      lukem    1583: .Nm
1.131     rillig   1584: is interrupted, it normally removes any partially made targets.
1.1       cgd      1585: This source prevents the target from being removed.
1.97      lukem    1586: .It Ic .RECURSIVE
                   1587: Synonym for
                   1588: .Ic .MAKE .
1.1       cgd      1589: .It Ic .SILENT
                   1590: Do not echo any of the commands associated with this target, exactly
                   1591: as if they all were preceded by an at sign
                   1592: .Pq Ql @ .
                   1593: .It Ic .USE
                   1594: Turn the target into
1.74      wiz      1595: .Nm Ns 's
1.1       cgd      1596: version of a macro.
                   1597: When the target is used as a source for another target, the other target
                   1598: acquires the commands, sources, and attributes (except for
                   1599: .Ic .USE )
                   1600: of the
                   1601: source.
                   1602: If the target already has commands, the
                   1603: .Ic .USE
                   1604: target's commands are appended
                   1605: to them.
1.52      christos 1606: .It Ic .USEBEFORE
                   1607: Exactly like
                   1608: .Ic .USE ,
1.57      wiz      1609: but prepend the
1.52      christos 1610: .Ic .USEBEFORE
                   1611: target commands to the target.
1.12      christos 1612: .It Ic .WAIT
1.71      mjl      1613: If
1.12      christos 1614: .Ic .WAIT
1.71      mjl      1615: appears in a dependency line, the sources that precede it are
1.67      grant    1616: made before the sources that succeed it in the line.
1.128     dsl      1617: Since the dependents of files are not made until the file itself
                   1618: could be made, this also stops the dependents being built unless they
                   1619: are needed for another branch of the dependency tree.
                   1620: So given:
                   1621: .Bd -literal
                   1622: x: a .WAIT b
                   1623:        echo x
                   1624: a:
                   1625:        echo a
                   1626: b: b1
                   1627:        echo b
                   1628: b1:
                   1629:        echo b1
                   1630:
                   1631: .Ed
                   1632: the output is always
1.151     dholland 1633: .Ql a ,
1.128     dsl      1634: .Ql b1 ,
                   1635: .Ql b ,
                   1636: .Ql x .
                   1637: .br
1.122     apb      1638: The ordering imposed by
                   1639: .Ic .WAIT
1.128     dsl      1640: is only relevant for parallel makes.
1.1       cgd      1641: .El
1.57      wiz      1642: .Sh SPECIAL TARGETS
1.1       cgd      1643: Special targets may not be included with other targets, i.e. they must be
                   1644: the only target specified.
1.61      ross     1645: .Bl -tag -width .BEGINx
1.1       cgd      1646: .It Ic .BEGIN
                   1647: Any command lines attached to this target are executed before anything
                   1648: else is done.
                   1649: .It Ic .DEFAULT
                   1650: This is sort of a
                   1651: .Ic .USE
                   1652: rule for any target (that was used only as a
                   1653: source) that
1.25      lukem    1654: .Nm
1.1       cgd      1655: can't figure out any other way to create.
                   1656: Only the shell script is used.
                   1657: The
                   1658: .Ic .IMPSRC
                   1659: variable of a target that inherits
                   1660: .Ic .DEFAULT Ns 's
                   1661: commands is set
                   1662: to the target's own name.
                   1663: .It Ic .END
                   1664: Any command lines attached to this target are executed after everything
                   1665: else is done.
1.168     sjg      1666: .It Ic .ERROR
                   1667: Any command lines attached to this target are executed when another target fails.
                   1668: The
                   1669: .Ic .ERROR_TARGET
                   1670: variable is set to the target that failed.
1.169     wiz      1671: See also
1.168     sjg      1672: .Ic MAKE_PRINT_VAR_ON_ERROR .
1.1       cgd      1673: .It Ic .IGNORE
                   1674: Mark each of the sources with the
                   1675: .Ic .IGNORE
                   1676: attribute.
                   1677: If no sources are specified, this is the equivalent of specifying the
                   1678: .Fl i
                   1679: option.
                   1680: .It Ic .INTERRUPT
                   1681: If
1.25      lukem    1682: .Nm
1.1       cgd      1683: is interrupted, the commands for this target will be executed.
                   1684: .It Ic .MAIN
                   1685: If no target is specified when
1.25      lukem    1686: .Nm
1.1       cgd      1687: is invoked, this target will be built.
                   1688: .It Ic .MAKEFLAGS
                   1689: This target provides a way to specify flags for
1.25      lukem    1690: .Nm
1.1       cgd      1691: when the makefile is used.
                   1692: The flags are as if typed to the shell, though the
                   1693: .Fl f
                   1694: option will have
                   1695: no effect.
1.12      christos 1696: .\" XXX: NOT YET!!!!
                   1697: .\" .It Ic .NOTPARALLEL
1.70      wiz      1698: .\" The named targets are executed in non parallel mode.
                   1699: .\" If no targets are
1.12      christos 1700: .\" specified, then all targets are executed in non parallel mode.
1.20      gwr      1701: .It Ic .NOPATH
                   1702: Apply the
                   1703: .Ic .NOPATH
1.67      grant    1704: attribute to any specified sources.
1.12      christos 1705: .It Ic .NOTPARALLEL
                   1706: Disable parallel mode.
                   1707: .It Ic .NO_PARALLEL
1.97      lukem    1708: Synonym for
                   1709: .Ic .NOTPARALLEL ,
                   1710: for compatibility with other pmake variants.
1.12      christos 1711: .It Ic .ORDER
                   1712: The named targets are made in sequence.
1.128     dsl      1713: This ordering does not add targets to the list of targets to be made.
                   1714: Since the dependents of a target do not get built until the target itself
                   1715: could be built, unless
                   1716: .Ql a
1.129     wiz      1717: is built by another part of the dependency graph,
1.128     dsl      1718: the following is a dependency loop:
                   1719: .Bd -literal
1.158     sjg      1720: \&.ORDER: a b
1.128     dsl      1721: b: a
                   1722: .Ed
1.129     wiz      1723: .Pp
1.122     apb      1724: The ordering imposed by
                   1725: .Ic .ORDER
1.128     dsl      1726: is only relevant for parallel makes.
1.12      christos 1727: .\" XXX: NOT YET!!!!
                   1728: .\" .It Ic .PARALLEL
1.70      wiz      1729: .\" The named targets are executed in parallel mode.
                   1730: .\" If no targets are
1.12      christos 1731: .\" specified, then all targets are executed in parallel mode.
1.1       cgd      1732: .It Ic .PATH
                   1733: The sources are directories which are to be searched for files not
                   1734: found in the current directory.
                   1735: If no sources are specified, any previously specified directories are
                   1736: deleted.
1.34      thorpej  1737: If the source is the special
                   1738: .Ic .DOTLAST
                   1739: target, then the current working
1.33      thorpej  1740: directory is searched last.
1.14      christos 1741: .It Ic .PHONY
                   1742: Apply the
                   1743: .Ic .PHONY
1.67      grant    1744: attribute to any specified sources.
1.1       cgd      1745: .It Ic .PRECIOUS
                   1746: Apply the
                   1747: .Ic .PRECIOUS
                   1748: attribute to any specified sources.
                   1749: If no sources are specified, the
                   1750: .Ic .PRECIOUS
                   1751: attribute is applied to every
                   1752: target in the file.
1.83      sjg      1753: .It Ic .SHELL
1.86      wiz      1754: Sets the shell that
1.83      sjg      1755: .Nm
1.86      wiz      1756: will use to execute commands.
                   1757: The sources are a set of
1.83      sjg      1758: .Ar field=value
1.86      wiz      1759: pairs.
1.83      sjg      1760: .Bl -tag -width hasErrCtls
                   1761: .It Ar name
                   1762: This is the minimal specification, used to select one of the builtin
                   1763: shell specs;
                   1764: .Ar sh ,
                   1765: .Ar ksh ,
                   1766: and
                   1767: .Ar csh .
                   1768: .It Ar path
                   1769: Specifies the path to the shell.
                   1770: .It Ar hasErrCtl
                   1771: Indicates whether the shell supports exit on error.
                   1772: .It Ar check
                   1773: The command to turn on error checking.
                   1774: .It Ar ignore
                   1775: The command to disable error checking.
                   1776: .It Ar echo
                   1777: The command to turn on echoing of commands executed.
                   1778: .It Ar quiet
                   1779: The command to turn off echoing of commands executed.
                   1780: .It Ar filter
                   1781: The output to filter after issuing the
                   1782: .Ar quiet
1.86      wiz      1783: command.
                   1784: It is typically identical to
1.83      sjg      1785: .Ar quiet .
                   1786: .It Ar errFlag
                   1787: The flag to pass the shell to enable error checking.
                   1788: .It Ar echoFlag
                   1789: The flag to pass the shell to enable command echoing.
1.127     rillig   1790: .It Ar newline
                   1791: The string literal to pass the shell that results in a single newline
                   1792: character when used outside of any quoting characters.
1.83      sjg      1793: .El
                   1794: Example:
                   1795: .Bd -literal
1.167     joerg    1796: \&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e
                   1797:        check="set -e" ignore="set +e" \e
                   1798:        echo="set -v" quiet="set +v" filter="set +v" \e
                   1799:        echoFlag=v errFlag=e newline="'\en'"
1.83      sjg      1800: .Ed
1.1       cgd      1801: .It Ic .SILENT
                   1802: Apply the
                   1803: .Ic .SILENT
                   1804: attribute to any specified sources.
                   1805: If no sources are specified, the
                   1806: .Ic .SILENT
                   1807: attribute is applied to every
                   1808: command in the file.
                   1809: .It Ic .SUFFIXES
                   1810: Each source specifies a suffix to
1.74      wiz      1811: .Nm .
1.71      mjl      1812: If no sources are specified, any previously specified suffixes are deleted.
1.136     cube     1813: It allows the creation of suffix-transformation rules.
                   1814: .Pp
                   1815: Example:
                   1816: .Bd -literal
                   1817: \&.SUFFIXES: .o
                   1818: \&.c.o:
                   1819:        cc -o ${.TARGET} -c ${.IMPSRC}
                   1820: .Ed
1.31      ross     1821: .El
1.1       cgd      1822: .Sh ENVIRONMENT
1.25      lukem    1823: .Nm
1.73      perry    1824: uses the following environment variables, if they exist:
1.16      christos 1825: .Ev MACHINE ,
1.26      hubertf  1826: .Ev MACHINE_ARCH ,
1.1       cgd      1827: .Ev MAKE ,
1.16      christos 1828: .Ev MAKEFLAGS ,
                   1829: .Ev MAKEOBJDIR ,
1.38      sjg      1830: .Ev MAKEOBJDIRPREFIX ,
1.76      jrf      1831: .Ev MAKESYSPATH ,
1.154     apb      1832: .Ev PWD ,
1.1       cgd      1833: and
1.154     apb      1834: .Ev TMPDIR .
1.57      wiz      1835: .Pp
1.38      sjg      1836: .Ev MAKEOBJDIRPREFIX
1.117     lukem    1837: and
1.38      sjg      1838: .Ev MAKEOBJDIR
1.117     lukem    1839: may only be set in the environment or on the command line to
1.38      sjg      1840: .Nm
1.117     lukem    1841: and not as makefile variables;
                   1842: see the description of
                   1843: .Ql Va .OBJDIR
                   1844: for more details.
1.1       cgd      1845: .Sh FILES
                   1846: .Bl -tag -width /usr/share/mk -compact
                   1847: .It .depend
                   1848: list of dependencies
                   1849: .It Makefile
                   1850: list of dependencies
                   1851: .It makefile
                   1852: list of dependencies
                   1853: .It sys.mk
                   1854: system makefile
                   1855: .It /usr/share/mk
                   1856: system makefile directory
                   1857: .El
1.128     dsl      1858: .Sh COMPATIBILITY
                   1859: The basic make syntax is compatible between different versions of make,
                   1860: however the special variables, variable modifiers and conditionals are not.
                   1861: .Pp
1.129     wiz      1862: The way that parallel makes are scheduled changed in
1.130     wiz      1863: .Nx 4.0
1.129     wiz      1864: so that .ORDER and .WAIT apply recursively to the dependant nodes.
1.128     dsl      1865: The algorithms used may change again in the future.
1.152     dsl      1866: .Pp
                   1867: The way that .for loop variables are substituted changed after
                   1868: .Nx 5.0
                   1869: so that they still appear to be variable expansions.
                   1870: In particular this stops them being treated as syntax, and removes some
                   1871: obscure problems using them in .if statements.
1.153     wiz      1872: .Sh SEE ALSO
                   1873: .Xr mkdep 1
                   1874: .Sh HISTORY
                   1875: A
                   1876: .Nm
                   1877: command appeared in
                   1878: .At v7 .
1.152     dsl      1879: .Sh BUGS
                   1880: The
                   1881: .Nm
                   1882: syntax is difficult to parse without actually acting of the data.
                   1883: For instance finding the end of a variable use should involve scanning each
                   1884: the modifiers using the correct terminator for each field.
                   1885: In many places
                   1886: .Nm
                   1887: just counts {} and () in order to find the end of a variable expansion.
                   1888: .Pp
1.153     wiz      1889: There is no way of escaping a space character in a filename.

CVSweb <webmaster@jp.NetBSD.org>