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

1.32    ! erh         1: .\"    $NetBSD: make.1,v 1.31 1999/03/09 03:21:21 ross 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.
                     14: .\" 3. All advertising materials mentioning features or use of this software
                     15: .\"    must display the following acknowledgement:
                     16: .\"    This product includes software developed by the University of
                     17: .\"    California, Berkeley and its contributors.
                     18: .\" 4. Neither the name of the University nor the names of its contributors
                     19: .\"    may be used to endorse or promote products derived from this software
                     20: .\"    without specific prior written permission.
                     21: .\"
                     22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     25: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     32: .\" SUCH DAMAGE.
                     33: .\"
1.16      christos   34: .\"    from: @(#)make.1        8.4 (Berkeley) 3/19/94
1.1       cgd        35: .\"
1.16      christos   36: .Dd March 19, 1994
1.1       cgd        37: .Dt MAKE 1
                     38: .Os
                     39: .Sh NAME
                     40: .Nm make
                     41: .Nd maintain program dependencies
                     42: .Sh SYNOPSIS
1.30      mycroft    43: .Nm ""
1.16      christos   44: .Op Fl Beiknqrst
1.30      mycroft    45: .Bk -words
1.1       cgd        46: .Op Fl D Ar variable
1.30      mycroft    47: .Ek
                     48: .Bk -words
1.1       cgd        49: .Op Fl d Ar flags
1.30      mycroft    50: .Ek
                     51: .Bk -words
1.1       cgd        52: .Op Fl f Ar makefile
1.30      mycroft    53: .Ek
                     54: .Bk -words
1.1       cgd        55: .Op Fl I Ar directory
1.30      mycroft    56: .Ek
1.1       cgd        57: .Bk -words
                     58: .Op Fl j Ar max_jobs
1.30      mycroft    59: .Ek
                     60: .Bk -words
1.13      christos   61: .Op Fl m Ar directory
1.1       cgd        62: .Ek
1.30      mycroft    63: .Bk -words
1.16      christos   64: .Op Fl V Ar variable
1.30      mycroft    65: .Ek
1.1       cgd        66: .Op Ar variable=value
1.30      mycroft    67: .Bk -words
1.1       cgd        68: .Op Ar target ...
1.30      mycroft    69: .Ek
1.1       cgd        70: .Sh DESCRIPTION
1.25      lukem      71: .Nm
1.1       cgd        72: is a program designed to simplify the maintenance of other programs.
                     73: Its input is a list of specifications as to the files upon which programs
                     74: and other files depend.
                     75: If the file
                     76: .Ql Pa makefile
                     77: exists, it is read for this list of specifications.
                     78: If it does not exist, the file
                     79: .Ql Pa Makefile
                     80: is read.
                     81: If the file
                     82: .Ql Pa .depend
                     83: exists, it is read (see
                     84: .Xr mkdep 1) .
                     85: .Pp
                     86: This manual page is intended as a reference document only.
                     87: For a more thorough description of
1.25      lukem      88: .Nm
1.1       cgd        89: and makefiles, please refer to
                     90: .%T "Make \- A Tutorial" .
                     91: .Pp
                     92: The options are as follows:
                     93: .Bl -tag -width Ds
1.16      christos   94: .It Fl B
1.10      christos   95: Try to be backwards compatible by executing a single shell per command and
                     96: by executing the commands to make the sources of a dependency line in sequence.
1.1       cgd        97: .It Fl D Ar variable
1.8       christos   98: Define
                     99: .Ar variable
1.1       cgd       100: to be 1, in the global context.
                    101: .It Fl d Ar flags
                    102: Turn on debugging, and specify which portions of
1.25      lukem     103: .Nm
1.1       cgd       104: are to print debugging information.
                    105: .Ar Flags
                    106: is one or more of the following:
                    107: .Bl -tag -width Ds
                    108: .It Ar A
                    109: Print all possible debugging information;
                    110: equivalent to specifying all of the debugging flags.
                    111: .It Ar a
                    112: Print debugging information about archive searching and caching.
                    113: .It Ar c
                    114: Print debugging information about conditional evaluation.
                    115: .It Ar d
                    116: Print debugging information about directory searching and caching.
                    117: .It Ar "g1"
                    118: Print the input graph before making anything.
                    119: .It Ar "g2"
                    120: Print the input graph after making everything, or before exiting
                    121: on error.
                    122: .It Ar j
                    123: Print debugging information about running multiple shells.
                    124: .It Ar m
                    125: Print debugging information about making targets, including modification
                    126: dates.
                    127: .It Ar s
                    128: Print debugging information about suffix-transformation rules.
                    129: .It Ar t
                    130: Print debugging information about target list maintenance.
                    131: .It Ar v
                    132: Print debugging information about variable assignment.
                    133: .El
                    134: .It Fl e
                    135: Specify that environmental variables override macro assignments within
                    136: makefiles.
                    137: .It Fl f Ar makefile
                    138: Specify a makefile to read instead of the default
                    139: .Ql Pa makefile
                    140: and
                    141: .Ql Pa Makefile .
                    142: If
                    143: .Ar makefile
                    144: is
                    145: .Ql Fl ,
                    146: standard input is read.
                    147: Multiple makefile's may be specified, and are read in the order specified.
                    148: .It Fl I Ar directory
                    149: Specify a directory in which to search for makefiles and included makefiles.
1.13      christos  150: The system makefile directory (or directories, see the
                    151: .Fl m
                    152: option) is automatically included as part of this list.
1.1       cgd       153: .It Fl i
                    154: Ignore non-zero exit of shell commands in the makefile.
                    155: Equivalent to specifying
                    156: .Ql Fl
                    157: before each command line in the makefile.
                    158: .It Fl j Ar max_jobs
                    159: Specify the maximum number of jobs that
1.25      lukem     160: .Nm
1.16      christos  161: may have running at any one time. Turns compatibility mode off, unless the
1.11      christos  162: .Ar B
                    163: flag is also specified.
1.1       cgd       164: .It Fl k
                    165: Continue processing after errors are encountered, but only on those targets
                    166: that do not depend on the target whose creation caused the error.
1.13      christos  167: .It Fl m Ar directory
                    168: Specify a directory in which to search for sys.mk and makefiles included
                    169: via the <...> style.  Multiple directories can be added to form a search path.
                    170: This path will override the default system include path: /usr/share/mk.
                    171: Furthermore the system include path will be appended to the search path used
                    172: for "..."-style inclusions (see the
                    173: .Fl I
                    174: option).
1.1       cgd       175: .It Fl n
                    176: Display the commands that would have been executed, but do not actually
                    177: execute them.
                    178: .It Fl q
                    179: Do not execute any commands, but exit 0 if the specified targets are
                    180: up-to-date and 1, otherwise.
                    181: .It Fl r
                    182: Do not use the built-in rules specified in the system makefile.
                    183: .It Fl s
                    184: Do not echo any commands as they are executed.
                    185: Equivalent to specifying
                    186: .Ql Ic @
                    187: before each command line in the makefile.
                    188: .It Fl t
                    189: Rather than re-building a target as specified in the makefile, create it
                    190: or update its modification time to make it appear up-to-date.
1.16      christos  191: .It Fl V Ar variable
                    192: Print
1.25      lukem     193: .Nm "" Ns 's
1.16      christos  194: idea of the value of
                    195: .Ar variable ,
                    196: in the global context.
                    197: Do not build any targets.
                    198: Multiple instances of this option may be specified;
                    199: the variables will be printed one per line,
                    200: with a blank line for each null or undefined variable.
1.1       cgd       201: .It Ar variable=value
                    202: Set the value of the variable
                    203: .Ar variable
                    204: to
                    205: .Ar value .
                    206: .El
                    207: .Pp
1.6       cgd       208: There are seven different types of lines in a makefile: file dependency
1.1       cgd       209: specifications, shell commands, variable assignments, include statements,
1.6       cgd       210: conditional directives, for loops, and comments.
1.1       cgd       211: .Pp
                    212: In general, lines may be continued from one line to the next by ending
                    213: them with a backslash
                    214: .Pq Ql \e .
                    215: The trailing newline character and initial whitespace on the following
                    216: line are compressed into a single space.
                    217: .Sh FILE DEPENDENCY SPECIFICATIONS
                    218: Dependency lines consist of one or more targets, an operator, and zero
                    219: or more sources.
                    220: This creates a relationship where the targets ``depend'' on the sources
                    221: and are usually created from them.
                    222: The exact relationship between the target and the source is determined
                    223: by the operator that separates them.
                    224: The three operators are as follows:
                    225: .Bl -tag -width flag
                    226: .It Ic \&:
                    227: A target is considered out-of-date if its modification time is less than
                    228: those of any of its sources.
                    229: Sources for a target accumulate over dependency lines when this operator
                    230: is used.
                    231: The target is removed if
1.25      lukem     232: .Nm
1.1       cgd       233: is interrupted.
                    234: .It Ic \&!
                    235: Targets are always re-created, but not until all sources have been
                    236: examined and re-created as necessary.
                    237: Sources for a target accumulate over dependency lines when this operator
                    238: is used.
                    239: The target is removed if
1.25      lukem     240: .Nm
1.1       cgd       241: is interrupted.
                    242: .It Ic \&::
                    243: If no sources are specified, the target is always re-created.
                    244: Otherwise, a target is considered out-of-date if any of its sources has
                    245: been modified more recently than the target.
                    246: Sources for a target do not accumulate over dependency lines when this
                    247: operator is used.
                    248: The target will not be removed if
1.25      lukem     249: .Nm
1.1       cgd       250: is interrupted.
                    251: .El
                    252: .Pp
                    253: Targets and sources may contain the shell wildcard values
                    254: .Ql ? ,
                    255: .Ql * ,
                    256: .Ql []
                    257: and
                    258: .Ql {} .
                    259: The values
                    260: .Ql ? ,
                    261: .Ql *
                    262: and
                    263: .Ql []
                    264: may only be used as part of the final
                    265: component of the target or source, and must be used to describe existing
                    266: files.
                    267: The value
                    268: .Ql {}
                    269: need not necessarily be used to describe existing files.
                    270: Expansion is in directory order, not alphabetically as done in the shell.
                    271: .Sh SHELL COMMANDS
                    272: Each target may have associated with it a series of shell commands, normally
                    273: used to create the target.
                    274: Each of the commands in this script
                    275: .Em must
                    276: be preceded by a tab.
                    277: While any target may appear on a dependency line, only one of these
                    278: dependencies may be followed by a creation script, unless the
                    279: .Ql Ic ::
                    280: operator is used.
                    281: .Pp
                    282: If the first or first two characters of the command line are
                    283: .Ql Ic @
                    284: and/or
                    285: .Ql Ic \- ,
                    286: the command is treated specially.
                    287: A
                    288: .Ql Ic @
                    289: causes the command not to be echoed before it is executed.
                    290: A
                    291: .Ql Ic \-
                    292: causes any non-zero exit status of the command line to be ignored.
                    293: .Sh VARIABLE ASSIGNMENTS
                    294: Variables in make are much like variables in the shell, and, by tradition,
                    295: consist of all upper-case letters.
                    296: The five operators that can be used to assign values to variables are as
                    297: follows:
                    298: .Bl -tag -width Ds
                    299: .It Ic \&=
                    300: Assign the value to the variable.
                    301: Any previous value is overridden.
                    302: .It Ic \&+=
                    303: Append the value to the current value of the variable.
                    304: .It Ic \&?=
                    305: Assign the value to the variable if it is not already defined.
                    306: .It Ic \&:=
                    307: Assign with expansion, i.e. expand the value before assigning it
                    308: to the variable.
                    309: Normally, expansion is not done until the variable is referenced.
                    310: .It Ic \&!=
                    311: Expand the value and pass it to the shell for execution and assign
                    312: the result to the variable.
                    313: Any newlines in the result are replaced with spaces.
                    314: .El
                    315: .Pp
                    316: Any white-space before the assigned
                    317: .Ar value
                    318: is removed; if the value is being appended, a single space is inserted
                    319: between the previous contents of the variable and the appended value.
                    320: .Pp
                    321: Variables are expanded by surrounding the variable name with either
                    322: curly braces
                    323: .Pq Ql {}
1.7       mycroft   324: or parentheses
1.1       cgd       325: .Pq Ql ()
                    326: and preceding it with
                    327: a dollar sign
                    328: .Pq Ql \&$ .
                    329: If the variable name contains only a single letter, the surrounding
1.7       mycroft   330: braces or parentheses are not required.
1.1       cgd       331: This shorter form is not recommended.
                    332: .Pp
                    333: Variable substitution occurs at two distinct times, depending on where
                    334: the variable is being used.
                    335: Variables in dependency lines are expanded as the line is read.
                    336: Variables in shell commands are expanded when the shell command is
                    337: executed.
                    338: .Pp
                    339: The four different classes of variables (in order of increasing precedence)
                    340: are:
                    341: .Bl -tag -width Ds
                    342: .It Environment variables
                    343: Variables defined as part of
1.25      lukem     344: .Nm "" Ns 's
1.1       cgd       345: environment.
                    346: .It Global variables
                    347: Variables defined in the makefile or in included makefiles.
                    348: .It Command line variables
                    349: Variables defined as part of the command line.
                    350: .It Local variables
                    351: Variables that are defined specific to a certain target.
                    352: The seven local variables are as follows:
                    353: .Bl -tag -width ".ARCHIVE"
                    354: .It Va .ALLSRC
                    355: The list of all sources for this target; also known as
                    356: .Ql Va \&> .
                    357: .It Va .ARCHIVE
                    358: The name of the archive file.
                    359: .It Va .IMPSRC
                    360: The name/path of the source from which the target is to be transformed
                    361: (the ``implied'' source); also known as
                    362: .Ql Va \&< .
                    363: .It Va .MEMBER
                    364: The name of the archive member.
                    365: .It Va .OODATE
                    366: The list of sources for this target that were deemed out-of-date; also
                    367: known as
                    368: .Ql Va \&? .
                    369: .It Va .PREFIX
                    370: The file prefix of the file, containing only the file portion, no suffix
                    371: or preceding directory components; also known as
                    372: .Ql Va * .
                    373: .It Va .TARGET
                    374: The name of the target; also known as
                    375: .Ql Va @ .
                    376: .El
                    377: .Pp
                    378: The shorter forms
                    379: .Ql Va @ ,
                    380: .Ql Va ? ,
                    381: .Ql Va \&>
                    382: and
                    383: .Ql Va *
                    384: are permitted for backward
                    385: compatibility with historical makefiles and are not recommended.
                    386: The six variables
                    387: .Ql Va "@F" ,
                    388: .Ql Va "@D" ,
                    389: .Ql Va "<F" ,
                    390: .Ql Va "<D" ,
                    391: .Ql Va "*F"
                    392: and
                    393: .Ql Va "*D"
                    394: are
                    395: permitted for compatibility with
                    396: .At V
                    397: makefiles and are not recommended.
                    398: .Pp
                    399: Four of the local variables may be used in sources on dependency lines
                    400: because they expand to the proper value for each target on the line.
                    401: These variables are
                    402: .Ql Va .TARGET ,
                    403: .Ql Va .PREFIX ,
                    404: .Ql Va .ARCHIVE ,
                    405: and
                    406: .Ql Va .MEMBER .
                    407: .Pp
                    408: In addition,
1.25      lukem     409: .Nm
1.1       cgd       410: sets or knows about the following variables:
                    411: .Bl -tag -width MAKEFLAGS
                    412: .It Va \&$
                    413: A single dollar sign
                    414: .Ql \&$ ,
                    415: i.e.
                    416: .Ql \&$$
                    417: expands to a single dollar
                    418: sign.
                    419: .It Va .MAKE
                    420: The name that
1.25      lukem     421: .Nm
1.1       cgd       422: was executed with
1.22      pk        423: .Pq Va argv[0]
1.1       cgd       424: .It Va .CURDIR
                    425: A path to the directory where
1.25      lukem     426: .Nm
1.1       cgd       427: was executed.
1.4       pk        428: .It Va .OBJDIR
                    429: A path to the directory where the targets are built.
1.1       cgd       430: .It Ev MAKEFLAGS
                    431: The environment variable
                    432: .Ql Ev MAKEFLAGS
                    433: may contain anything that
                    434: may be specified on
1.25      lukem     435: .Nm "" Ns 's
1.1       cgd       436: command line.
                    437: Anything specified on
1.25      lukem     438: .Nm "" Ns 's
1.1       cgd       439: command line is appended to the
                    440: .Ql Ev MAKEFLAGS
                    441: variable which is then
                    442: entered into the environment for all programs which
1.25      lukem     443: .Nm
1.1       cgd       444: executes.
1.16      christos  445: .It Ev PWD
                    446: Alternate path to the current directory.
1.25      lukem     447: .Nm
1.16      christos  448: normally sets
                    449: .Ql Va .CURDIR
                    450: to the canonical path given by
                    451: .Xr getcwd 2 .
                    452: However, if the environment variable
                    453: .Ql Ev PWD
                    454: is set and gives a path to the current directory, then
1.25      lukem     455: .Nm
1.16      christos  456: sets
                    457: .Ql Va .CURDIR
                    458: to the value of
                    459: .Ql Ev PWD
                    460: instead.
                    461: .Ql Ev PWD
                    462: is set to the value of
                    463: .Ql Va .OBJDIR
                    464: for all programs which
1.25      lukem     465: .Nm
1.16      christos  466: executes.
1.1       cgd       467: .El
                    468: .Pp
                    469: Variable expansion may be modified to select or modify each word of the
                    470: variable (where a ``word'' is white-space delimited sequence of characters).
                    471: The general format of a variable expansion is as follows:
                    472: .Pp
                    473: .Dl {variable[:modifier[:...]]}
                    474: .Pp
                    475: Each modifier begins with a colon and one of the following
                    476: special characters.
                    477: The colon may be escaped with a backslash
                    478: .Pq Ql \e .
                    479: .Bl -tag -width Cm E\&
                    480: .It Cm E
                    481: Replaces each word in the variable with its suffix.
                    482: .It Cm H
                    483: Replaces each word in the variable with everything but the last component.
                    484: .It Cm M Ns Ar pattern
                    485: Select only those words that match the rest of the modifier.
                    486: The standard shell wildcard characters
                    487: .Pf ( Ql * ,
                    488: .Ql ? ,
                    489: and
                    490: .Ql Op )
                    491: may
                    492: be used.
                    493: The wildcard characters may be escaped with a backslash
                    494: .Pq Ql \e .
                    495: .It Cm N Ns Ar pattern
                    496: This is identical to
                    497: .Ql Cm M ,
                    498: but selects all words which do not match
                    499: the rest of the modifier.
1.17      christos  500: .It Cm Q
                    501: Quotes every shell meta-character in the variable, so that it can be passed
                    502: safely through recursive invocations of
1.25      lukem     503: .Nm "" .
1.1       cgd       504: .It Cm R
                    505: Replaces each word in the variable with everything but its suffix.
                    506: .Sm off
1.17      christos  507: .It Cm S No \&/ Ar old_string Xo
                    508: .No \&/ Ar new_string
                    509: .No \&/ Op Cm 1g
1.1       cgd       510: .Xc
                    511: .Sm on
                    512: Modify the first occurrence of
1.17      christos  513: .Ar old_string
                    514: in the variable's value, replacing it with
                    515: .Ar new_string .
1.1       cgd       516: If a
                    517: .Ql g
                    518: is appended to the last slash of the pattern, all occurrences
                    519: in each word are replaced.
1.17      christos  520: If a
                    521: .Ql 1
                    522: is appended to the last slash of the pattern, only the first word
                    523: is affected.
1.1       cgd       524: If
1.17      christos  525: .Ar old_string
                    526: begins with a caret
1.1       cgd       527: .Pq Ql ^ ,
1.17      christos  528: .Ar old_string
1.1       cgd       529: is anchored at the beginning of each word.
                    530: If
1.17      christos  531: .Ar old_string
1.1       cgd       532: ends with a dollar sign
                    533: .Pq Ql \&$ ,
                    534: it is anchored at the end of each word.
                    535: Inside
                    536: .Ar new_string ,
                    537: an ampersand
                    538: .Pq Ql &
                    539: is replaced by
1.17      christos  540: .Ar old_string
                    541: (without any
                    542: .Ql ^
                    543: or
                    544: .Ql \&$ ) .
1.1       cgd       545: Any character may be used as a delimiter for the parts of the modifier
                    546: string.
                    547: The anchoring, ampersand and delimiter characters may be escaped with a
                    548: backslash
                    549: .Pq Ql \e .
                    550: .Pp
                    551: Variable expansion occurs in the normal fashion inside both
                    552: .Ar old_string
                    553: and
                    554: .Ar new_string
                    555: with the single exception that a backslash is used to prevent the expansion
                    556: of a dollar sign
1.17      christos  557: .Pq Ql \&$ ,
1.1       cgd       558: not a preceding dollar sign as is usual.
1.17      christos  559: .Sm off
                    560: .It Cm C No \&/ Ar pattern Xo
                    561: .No \&/ Ar replacement
                    562: .No \&/ Op Cm 1g
                    563: .Xc
                    564: .Sm on
                    565: The
                    566: .Cm C
                    567: modifier is just like the
                    568: .Cm S
                    569: modifier except that the the old and new strings, instead of being
                    570: simple strings, are a regular expression (see
                    571: .Xr regex 3 )
                    572: and an
                    573: .Xr ed 1 Ns \-style
                    574: replacement string.  Normally, the first occurrence of the pattern in
                    575: each word of the value is changed.  The
                    576: .Ql 1
                    577: modifier causes the substitution to apply to at most one word; the
                    578: .Ql g
                    579: modifier causes the substitution to apply to as many instances of the
                    580: search pattern as occur in the word or words it is found in.  Note that
                    581: .Ql 1
                    582: and
                    583: .Ql g
                    584: are orthogonal; the former specifies whether multiple words are
                    585: potentially affected, the latter whether multiple substitutions can
                    586: potentially occur within each affected word.
1.1       cgd       587: .It Cm T
                    588: Replaces each word in the variable with its last component.
1.27      christos  589: .It Cm ? Ar true_string Ar \: Ar false_string
                    590: If the variable evaluates to true, return as its value the
                    591: .Ar true_string,
                    592: otherwise return the
                    593: .Ar false_string.
1.1       cgd       594: .It Ar old_string=new_string
                    595: This is the
                    596: .At V
                    597: style variable substitution.
                    598: It must be the last modifier specified.
1.16      christos  599: If
1.6       cgd       600: .Ar old_string
                    601: or
                    602: .Ar new_string
                    603: do not contain the pattern matching character
                    604: .Ar %
1.16      christos  605: then it is assumed that they are
1.6       cgd       606: anchored at the end of each word, so only suffixes or entire
1.16      christos  607: words may be replaced. Otherwise
1.6       cgd       608: .Ar %
1.16      christos  609: is the substring of
                    610: .Ar old_string
1.6       cgd       611: to be replaced in
                    612: .Ar new_string
1.32    ! erh       613: .El
1.6       cgd       614: .El
                    615: .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1.16      christos  616: Makefile inclusion, conditional structures and for loops  reminiscent
1.6       cgd       617: of the C programming language are provided in
1.25      lukem     618: .Nm "" .
1.1       cgd       619: All such structures are identified by a line beginning with a single
                    620: dot
                    621: .Pq Ql \&.
                    622: character.
                    623: Files are included with either
1.29      ross      624: .Cm \&.include Aq Ar file
1.1       cgd       625: or
1.29      ross      626: .Cm \&.include Pf \*q Ar file Ns \*q .
1.1       cgd       627: Variables between the angle brackets or double quotes are expanded
                    628: to form the file name.
                    629: If angle brackets are used, the included makefile is expected to be in
                    630: the system makefile directory.
                    631: If double quotes are used, the including makefile's directory and any
                    632: directories specified using the
                    633: .Fl I
                    634: option are searched before the system
                    635: makefile directory.
1.28      christos  636: For compatibility with other versions of
                    637: .Nm
                    638: .Ql include file ...
1.29      ross      639: is also accepted. If the include statement is written as
                    640: .Cm .-include
                    641: or as
                    642: .Cm .sinclude
1.28      christos  643: then errors locating and/or opening include files are ignored.
1.1       cgd       644: .Pp
                    645: Conditional expressions are also preceded by a single dot as the first
1.5       jtc       646: character of a line.
1.1       cgd       647: The possible conditionals are as follows:
                    648: .Bl -tag -width Ds
                    649: .It Ic .undef Ar variable
                    650: Un-define the specified global variable.
                    651: Only global variables may be un-defined.
                    652: .It Xo
                    653: .Ic \&.if
                    654: .Oo \&! Oc Ns Ar expression
                    655: .Op Ar operator expression ...
                    656: .Xc
                    657: Test the value of an expression.
                    658: .It Xo
                    659: .Ic .ifdef
                    660: .Oo \&! Oc Ns Ar variable
                    661: .Op Ar operator variable ...
                    662: .Xc
1.7       mycroft   663: Test the value of a variable.
1.1       cgd       664: .It Xo
                    665: .Ic .ifndef
                    666: .Oo \&! Oc Ns Ar variable
                    667: .Op Ar operator variable ...
                    668: .Xc
1.7       mycroft   669: Test the value of a variable.
1.1       cgd       670: .It Xo
                    671: .Ic .ifmake
                    672: .Oo \&! Oc Ns Ar target
                    673: .Op Ar operator target ...
                    674: .Xc
1.7       mycroft   675: Test the target being built.
1.1       cgd       676: .It Xo
                    677: .Ic .ifnmake
                    678: .Oo \&! Oc Ar target
                    679: .Op Ar operator target ...
                    680: .Xc
                    681: Test the target being built.
                    682: .It Ic .else
                    683: Reverse the sense of the last conditional.
                    684: .It Xo
                    685: .Ic .elif
                    686: .Oo \&! Oc Ar expression
                    687: .Op Ar operator expression ...
                    688: .Xc
                    689: A combination of
                    690: .Ql Ic .else
                    691: followed by
                    692: .Ql Ic .if .
                    693: .It Xo
                    694: .Ic .elifdef
                    695: .Oo \&! Oc Ns Ar variable
                    696: .Op Ar operator variable ...
                    697: .Xc
                    698: A combination of
                    699: .Ql Ic .else
                    700: followed by
                    701: .Ql Ic .ifdef .
                    702: .It Xo
                    703: .Ic .elifndef
                    704: .Oo \&! Oc Ns Ar variable
                    705: .Op Ar operator variable ...
                    706: .Xc
                    707: A combination of
                    708: .Ql Ic .else
                    709: followed by
                    710: .Ql Ic .ifndef .
                    711: .It Xo
                    712: .Ic .elifmake
                    713: .Oo \&! Oc Ns Ar target
                    714: .Op Ar operator target ...
                    715: .Xc
                    716: A combination of
                    717: .Ql Ic .else
                    718: followed by
                    719: .Ql Ic .ifmake .
                    720: .It Xo
                    721: .Ic .elifnmake
                    722: .Oo \&! Oc Ns Ar target
                    723: .Op Ar operator target ...
                    724: .Xc
                    725: A combination of
                    726: .Ql Ic .else
                    727: followed by
                    728: .Ql Ic .ifnmake .
                    729: .It Ic .endif
                    730: End the body of the conditional.
                    731: .El
                    732: .Pp
                    733: The
                    734: .Ar operator
                    735: may be any one of the following:
                    736: .Bl -tag -width "Cm XX"
                    737: .It Cm \&|\&|
                    738: logical OR
                    739: .It Cm \&&&
                    740: Logical
                    741: .Tn AND ;
                    742: of higher precedence than
1.26      hubertf   743: .Dq \&|\&| .
1.1       cgd       744: .El
                    745: .Pp
                    746: As in C,
1.25      lukem     747: .Nm
1.1       cgd       748: will only evaluate a conditional as far as is necessary to determine
                    749: its value.
1.16      christos  750: Parentheses may be used to change the order of evaluation.
1.1       cgd       751: The boolean operator
                    752: .Ql Ic \&!
                    753: may be used to logically negate an entire
                    754: conditional.
1.5       jtc       755: It is of higher precedence than
1.1       cgd       756: .Ql Ic \&&& .
                    757: .Pp
                    758: The value of
                    759: .Ar expression
                    760: may be any of the following:
                    761: .Bl -tag -width Ic defined
                    762: .It Ic defined
                    763: Takes a variable name as an argument and evaluates to true if the variable
                    764: has been defined.
                    765: .It Ic make
                    766: Takes a target name as an argument and evaluates to true if the target
                    767: was specified as part of
1.25      lukem     768: .Nm "" Ns 's
1.1       cgd       769: command line or was declared the default target (either implicitly or
                    770: explicitly, see
                    771: .Va .MAIN )
                    772: before the line containing the conditional.
                    773: .It Ic empty
1.5       jtc       774: Takes a variable, with possible modifiers, and evaluates to true if
1.1       cgd       775: the expansion of the variable would result in an empty string.
                    776: .It Ic exists
                    777: Takes a file name as an argument and evaluates to true if the file exists.
                    778: The file is searched for on the system search path (see
                    779: .Va .PATH ) .
                    780: .It Ic target
                    781: Takes a target name as an argument and evaluates to true if the target
                    782: has been defined.
                    783: .El
                    784: .Pp
                    785: .Ar Expression
1.6       cgd       786: may also be an arithmetic or string comparison.  Variable expansion is
                    787: performed on both sides of the comparison, after which the integral
                    788: values are compared.  A value is interpreted as hexadecimal if it is
                    789: preceded by 0x, otherwise it is decimal; octal numbers are not supported.
                    790: The standard C relational operators are all supported.  If after
                    791: variable expansion, either the left or right hand side of a
1.1       cgd       792: .Ql Ic ==
                    793: or
                    794: .Ql Ic "!="
1.6       cgd       795: operator is not an integral value, then
                    796: string comparison is performed between the expanded
                    797: variables.
1.1       cgd       798: If no relational operator is given, it is assumed that the expanded
                    799: variable is being compared against 0.
                    800: .Pp
                    801: When
1.25      lukem     802: .Nm
1.1       cgd       803: is evaluating one of these conditional expression, and it encounters
                    804: a word it doesn't recognize, either the ``make'' or ``defined''
                    805: expression is applied to it, depending on the form of the conditional.
                    806: If the form is
                    807: .Ql Ic .ifdef
                    808: or
                    809: .Ql Ic .ifndef ,
                    810: the ``defined'' expression
                    811: is applied.
                    812: Similarly, if the form is
                    813: .Ql Ic .ifmake
                    814: or
                    815: .Ql Ic .ifnmake , the ``make''
                    816: expression is applied.
                    817: .Pp
                    818: If the conditional evaluates to true the parsing of the makefile continues
                    819: as before.
                    820: If it evaluates to false, the following lines are skipped.
                    821: In both cases this continues until a
                    822: .Ql Ic .else
                    823: or
                    824: .Ql Ic .endif
                    825: is found.
1.16      christos  826: .Pp
1.6       cgd       827: For loops are typically used to apply a set of rules to a list of files.
                    828: The syntax of a for loop is:
                    829: .Bl -tag -width Ds
                    830: .It Xo
                    831: .Ic \&.for
1.16      christos  832: .Ar variable
                    833: .Ic in
1.6       cgd       834: .Ar expression
                    835: .Xc
                    836: .It Xo
                    837: <make-rules>
                    838: .Xc
                    839: .It Xo
                    840: .Ic \&.endfor
                    841: .Xc
                    842: .El
                    843: After the for
1.16      christos  844: .Ic expression
                    845: is evaluated, it is split into words. The
1.6       cgd       846: iteration
                    847: .Ic variable
1.16      christos  848: is successively set to each word, and substituted in the
                    849: .Ic make-rules
1.6       cgd       850: inside the body of the for loop.
1.1       cgd       851: .Sh COMMENTS
                    852: Comments begin with a hash
                    853: .Pq Ql \&#
                    854: character, anywhere but in a shell
                    855: command line, and continue to the end of the line.
                    856: .Sh SPECIAL SOURCES
                    857: .Bl -tag -width Ic .IGNORE
                    858: .It Ic .IGNORE
                    859: Ignore any errors from the commands associated with this target, exactly
                    860: as if they all were preceded by a dash
                    861: .Pq Ql \- .
1.18      christos  862: .It Ic .MADE
                    863: Mark all sources of this target as being up-to-date.
1.1       cgd       864: .It Ic .MAKE
                    865: Execute the commands associated with this target even if the
                    866: .Fl n
                    867: or
                    868: .Fl t
                    869: options were specified.
                    870: Normally used to mark recursive
1.25      lukem     871: .Nm "" Ns 's .
1.1       cgd       872: .It Ic .NOTMAIN
                    873: Normally
1.25      lukem     874: .Nm
1.1       cgd       875: selects the first target it encounters as the default target to be built
                    876: if no target was specified.
                    877: This source prevents this target from being selected.
                    878: .It Ic .OPTIONAL
                    879: If a target is marked with this attribute and
1.25      lukem     880: .Nm
1.1       cgd       881: can't figure out how to create it, it will ignore this fact and assume
                    882: the file isn't needed or already exists.
                    883: .It Ic .PRECIOUS
                    884: When
1.25      lukem     885: .Nm
1.1       cgd       886: is interrupted, it removes any partially made targets.
                    887: This source prevents the target from being removed.
                    888: .It Ic .SILENT
                    889: Do not echo any of the commands associated with this target, exactly
                    890: as if they all were preceded by an at sign
                    891: .Pq Ql @ .
                    892: .It Ic .USE
                    893: Turn the target into
1.25      lukem     894: .Nm "" Ns 's
1.1       cgd       895: version of a macro.
                    896: When the target is used as a source for another target, the other target
                    897: acquires the commands, sources, and attributes (except for
                    898: .Ic .USE )
                    899: of the
                    900: source.
                    901: If the target already has commands, the
                    902: .Ic .USE
                    903: target's commands are appended
                    904: to them.
1.12      christos  905: .It Ic .WAIT
                    906: If special
                    907: .Ic .WAIT
                    908: source is appears in a dependency line, the sources that precede it are
                    909: made before the sources that succeed it in the line. Loops are not being
                    910: detected and targets that form loops will be silently ignored.
1.1       cgd       911: .El
                    912: .Sh "SPECIAL TARGETS"
                    913: Special targets may not be included with other targets, i.e. they must be
                    914: the only target specified.
                    915: .Bl -tag -width Ic .BEGIN
                    916: .It Ic .BEGIN
                    917: Any command lines attached to this target are executed before anything
                    918: else is done.
                    919: .It Ic .DEFAULT
                    920: This is sort of a
                    921: .Ic .USE
                    922: rule for any target (that was used only as a
                    923: source) that
1.25      lukem     924: .Nm
1.1       cgd       925: can't figure out any other way to create.
                    926: Only the shell script is used.
                    927: The
                    928: .Ic .IMPSRC
                    929: variable of a target that inherits
                    930: .Ic .DEFAULT Ns 's
                    931: commands is set
                    932: to the target's own name.
                    933: .It Ic .END
                    934: Any command lines attached to this target are executed after everything
                    935: else is done.
                    936: .It Ic .IGNORE
                    937: Mark each of the sources with the
                    938: .Ic .IGNORE
                    939: attribute.
                    940: If no sources are specified, this is the equivalent of specifying the
                    941: .Fl i
                    942: option.
                    943: .It Ic .INTERRUPT
                    944: If
1.25      lukem     945: .Nm
1.1       cgd       946: is interrupted, the commands for this target will be executed.
                    947: .It Ic .MAIN
                    948: If no target is specified when
1.25      lukem     949: .Nm
1.1       cgd       950: is invoked, this target will be built.
                    951: .It Ic .MAKEFLAGS
                    952: This target provides a way to specify flags for
1.25      lukem     953: .Nm
1.1       cgd       954: when the makefile is used.
                    955: The flags are as if typed to the shell, though the
                    956: .Fl f
                    957: option will have
                    958: no effect.
1.12      christos  959: .\" XXX: NOT YET!!!!
                    960: .\" .It Ic .NOTPARALLEL
                    961: .\" The named targets are executed in non parallel mode. If no targets are
                    962: .\" specified, then all targets are executed in non parallel mode.
1.20      gwr       963: .It Ic .NOPATH
                    964: Apply the
                    965: .Ic .NOPATH
1.21      mycroft   966: attribute to any specified sources. Targets with this attribute are not
                    967: searched for in the directories specified by
                    968: .Ic .PATH .
1.12      christos  969: .It Ic .NOTPARALLEL
                    970: Disable parallel mode.
                    971: .It Ic .NO_PARALLEL
                    972: Same as above, for compatibility with other pmake variants.
                    973: .It Ic .ORDER
                    974: The named targets are made in sequence.
                    975: .\" XXX: NOT YET!!!!
                    976: .\" .It Ic .PARALLEL
                    977: .\" The named targets are executed in parallel mode. If no targets are
                    978: .\" specified, then all targets are executed in parallel mode.
1.1       cgd       979: .It Ic .PATH
                    980: The sources are directories which are to be searched for files not
                    981: found in the current directory.
                    982: If no sources are specified, any previously specified directories are
                    983: deleted.
1.14      christos  984: .It Ic .PHONY
                    985: Apply the
                    986: .Ic .PHONY
1.19      mycroft   987: attribute to any specified sources. Targets with this attribute do not
                    988: correspond to actual files; they are always considered to be out of date,
                    989: and will not be created with the
                    990: .Fl t
                    991: option.
1.1       cgd       992: .It Ic .PRECIOUS
                    993: Apply the
                    994: .Ic .PRECIOUS
                    995: attribute to any specified sources.
                    996: If no sources are specified, the
                    997: .Ic .PRECIOUS
                    998: attribute is applied to every
                    999: target in the file.
                   1000: .It Ic .SILENT
                   1001: Apply the
                   1002: .Ic .SILENT
                   1003: attribute to any specified sources.
                   1004: If no sources are specified, the
                   1005: .Ic .SILENT
                   1006: attribute is applied to every
                   1007: command in the file.
                   1008: .It Ic .SUFFIXES
                   1009: Each source specifies a suffix to
1.25      lukem    1010: .Nm "" .
1.4       pk       1011: If no sources are specified, any previous specified suffices are deleted.
1.31      ross     1012: .El
1.1       cgd      1013: .Sh ENVIRONMENT
1.25      lukem    1014: .Nm
1.1       cgd      1015: utilizes the following environment variables, if they exist:
1.16      christos 1016: .Ev MACHINE ,
1.26      hubertf  1017: .Ev MACHINE_ARCH ,
1.1       cgd      1018: .Ev MAKE ,
1.16      christos 1019: .Ev MAKEFLAGS ,
                   1020: .Ev MAKEOBJDIR ,
1.1       cgd      1021: and
1.16      christos 1022: .Ev PWD .
1.1       cgd      1023: .Sh FILES
                   1024: .Bl -tag -width /usr/share/mk -compact
                   1025: .It .depend
                   1026: list of dependencies
                   1027: .It Makefile
                   1028: list of dependencies
                   1029: .It makefile
                   1030: list of dependencies
                   1031: .It sys.mk
                   1032: system makefile
                   1033: .It /usr/share/mk
                   1034: system makefile directory
                   1035: .El
                   1036: .Sh SEE ALSO
                   1037: .Xr mkdep 1
                   1038: .Sh HISTORY
                   1039: A
1.25      lukem    1040: .Nm
1.1       cgd      1041: command appeared in
                   1042: .At v7 .

CVSweb <webmaster@jp.NetBSD.org>