[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.122

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

CVSweb <webmaster@jp.NetBSD.org>