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

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

CVSweb <webmaster@jp.NetBSD.org>