Annotation of src/usr.bin/make/make.1, Revision 1.140
1.140 ! espie 1: .\" $OpenBSD: make.1,v 1.139 2023/01/17 13:03:22 kn Exp $
1.10 millert 2: .\" $NetBSD: make.1,v 1.18 1997/03/10 21:19:53 christos Exp $
1.7 briggs 3: .\"
1.9 millert 4: .\" Copyright (c) 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
1.1 deraadt 6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.51 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
1.9 millert 31: .\" from: @(#)make.1 8.4 (Berkeley) 3/19/94
1.1 deraadt 32: .\"
1.140 ! espie 33: .Dd $Mdocdate: January 17 2023 $
1.1 deraadt 34: .Dt MAKE 1
35: .Os
36: .Sh NAME
37: .Nm make
38: .Nd maintain program dependencies
39: .Sh SYNOPSIS
1.19 aaron 40: .Nm make
1.95 espie 41: .Op Fl BeiknpqrSst
1.118 espie 42: .Op Fl C Ar directory
1.1 deraadt 43: .Op Fl D Ar variable
44: .Op Fl d Ar flags
1.104 espie 45: .Op Fl f Ar mk
1.1 deraadt 46: .Op Fl I Ar directory
1.140 ! espie 47: .Op Fl j Ar max_jobs
1.5 niklas 48: .Op Fl m Ar directory
1.9 millert 49: .Op Fl V Ar variable
1.139 kn 50: .Op Ar NAME Ns = Ns Ar value ...
1.50 jmc 51: .Bk -words
1.1 deraadt 52: .Op Ar target ...
1.50 jmc 53: .Ek
1.1 deraadt 54: .Sh DESCRIPTION
1.19 aaron 55: .Nm
1.1 deraadt 56: is a program designed to simplify the maintenance of other programs.
1.95 espie 57: Its input is a
1.115 jmc 58: .Em makefile :
1.98 espie 59: a list of specifications (target rules) describing build
1.95 espie 60: relationships between programs and other files.
1.115 jmc 61: By default, the file
62: .Pa makefile
63: is used;
64: if no such file is found, it tries
65: .Pa Makefile .
66: If neither of these exist,
1.95 espie 67: .Nm
68: can still rely on a set of built-in system rules.
69: .Pp
1.111 jmc 70: If the file
1.54 jmc 71: .Sq Pa .depend
1.112 espie 72: exists, it will also be read after the main
1.95 espie 73: .Ar makefile
74: (see
1.42 mpech 75: .Xr mkdep 1 ) .
1.1 deraadt 76: .Pp
1.43 espie 77: The handling of
1.54 jmc 78: .Sq Pa .depend
1.114 deraadt 79: is a
1.106 jmc 80: .Bx
1.115 jmc 81: extension.
1.130 espie 82: .Pp
83: If a list of
84: .Ar target ...
85: is specified,
86: .Nm
87: will build those targets.
88: Otherwise a default target will be built:
89: either a target explicitly marked with
90: .Ic .MAIN
91: or the first target encountered in the
92: .Em makefile .
1.43 espie 93: .Pp
94: Standard options are as follows:
95: .Bl -tag -width Ds
96: .It Fl e
1.104 espie 97: Environment variables override macro assignments within
1.43 espie 98: makefiles.
1.104 espie 99: .It Fl f Ar mk
100: Read file
101: .Ar mk
102: instead of the default makefile.
1.43 espie 103: If
1.104 espie 104: .Ar mk
1.43 espie 105: is
106: .Ql \- ,
1.104 espie 107: standard input is used.
1.43 espie 108: Multiple makefiles may be specified, and are read in the order specified.
109: .It Fl i
110: Ignore non-zero exit of shell commands in the makefile.
111: Equivalent to specifying
112: .Ql \-
113: before each command line in the makefile.
114: .It Fl k
115: Continue processing after errors are encountered, but only on those targets
116: that do not depend on the target whose creation caused the error.
117: .It Fl n
118: Display the commands that would have been executed, but do not actually
119: execute them.
1.95 espie 120: .It Fl p
121: Print a dump of the target rules and variables on stdout.
122: Do not build anything.
1.43 espie 123: .It Fl q
1.50 jmc 124: Do not execute any commands, but exit with status 0 if the specified targets
1.124 tb 125: are up to date, and 1 otherwise.
1.43 espie 126: .It Fl r
1.104 espie 127: Do not use the built-in rules specified in the system makefile,
128: .Pa <sys.mk> .
1.43 espie 129: .It Fl S
130: Stop processing when an error is encountered.
131: This is the default behavior.
132: This is needed to negate the
133: .Fl k
134: option during recursive builds.
135: .It Fl s
136: Do not echo commands as they are executed.
137: Equivalent to specifying
1.54 jmc 138: .Sq Ic @
1.43 espie 139: before each command line in the makefile.
140: .It Fl t
141: Rather than re-building a target as specified in the makefile, create it
1.124 tb 142: or update its modification time to make it appear up to date, a bit like
1.104 espie 143: .Xr touch 1 .
1.60 espie 144: .It Ar NAME Ns = Ns Ar value
1.43 espie 145: Set the value of the variable
1.60 espie 146: .Ar NAME
1.43 espie 147: to
148: .Ar value .
149: .El
1.1 deraadt 150: .Pp
1.43 espie 151: Extended options are as follows:
1.1 deraadt 152: .Bl -tag -width Ds
1.9 millert 153: .It Fl B
1.95 espie 154: Try to be backwards compatible by executing the commands to make
155: the prerequisites in a target rule in sequence.
156: This is the default, in the absence of
1.140 ! espie 157: .Fl j Ar max_jobs .
1.118 espie 158: .It Fl C Ar directory
159: Enter
160: .Ar directory
161: before doing anything.
1.1 deraadt 162: .It Fl D Ar variable
163: Define
164: .Ar variable
1.40 espie 165: to be 1.
1.1 deraadt 166: .It Fl d Ar flags
167: Turn on debugging, and specify which portions of
1.19 aaron 168: .Nm
1.1 deraadt 169: are to print debugging information.
1.14 aaron 170: .Ar flags
1.1 deraadt 171: is one or more of the following:
172: .Bl -tag -width Ds
173: .It Ar A
174: Print all possible debugging information;
175: equivalent to specifying all of the debugging flags.
176: .It Ar a
177: Print debugging information about archive searching and caching.
178: .It Ar c
179: Print debugging information about conditional evaluation.
180: .It Ar d
181: Print debugging information about directory searching and caching.
1.98 espie 182: .It Ar D
183: Print warning messages about multiply defined command lists.
1.94 espie 184: .It Ar e
1.95 espie 185: Print debugging information about expensive command heuristics.
1.15 espie 186: .It Ar f
1.40 espie 187: Print debugging information about the expansion of for loops.
1.1 deraadt 188: .It Ar "g1"
189: Print the input graph before making anything.
190: .It Ar "g2"
191: Print the input graph after making everything, or before exiting
192: on error.
1.98 espie 193: .It Ar h
194: Print information about jobs being held back because of sibling/target
195: groups races.
1.1 deraadt 196: .It Ar j
1.95 espie 197: Print debugging information about forking processes to run commands.
1.96 espie 198: .It Ar k
199: Print debugging information about manually killing processes.
1.40 espie 200: .It Ar l
201: Print commands in Makefile targets regardless of whether or not they are
202: prefixed by @.
203: Also known as loud behavior.
1.1 deraadt 204: .It Ar m
205: Print debugging information about making targets, including modification
206: dates.
1.82 espie 207: .It Ar n
208: Print debugging information about target names equivalence computations.
1.75 espie 209: .It Ar p
1.77 jmc 210: Help finding concurrency issues for parallel make by adding some
1.76 espie 211: randomization.
1.75 espie 212: If
213: .Va RANDOM_ORDER
214: is defined,
215: targets will be shuffled before being built.
216: If
217: .Va RANDOM_DELAY
1.76 espie 218: is defined,
1.75 espie 219: .Nm
1.95 espie 220: will wait between 0 and ${RANDOM_DELAY} seconds before starting a command.
1.75 espie 221: A given random seed can be forced by setting
222: .Va RANDOM_SEED ,
1.125 jmc 223: but this does not guarantee reproducibility.
1.94 espie 224: .It Ar q
225: .Sq quick death
226: option: after a fatal error, instead of waiting for other jobs to die,
227: kill them right away.
1.1 deraadt 228: .It Ar s
1.96 espie 229: Print debugging information about inference (suffix) transformation rules.
1.1 deraadt 230: .It Ar t
231: Print debugging information about target list maintenance.
1.98 espie 232: .It Ar T
233: Print debugging information about target group determination.
1.1 deraadt 234: .It Ar v
235: Print debugging information about variable assignment.
236: .El
237: .It Fl I Ar directory
1.104 espie 238: Specify a directory in which to search for makefiles and
239: for "..."-style inclusions.
240: Multiple directories can be added to form a search path.
241: Furthermore, the system include path (see the
1.5 niklas 242: .Fl m
1.104 espie 243: option) will be used after this search path.
1.140 ! espie 244: .It Fl j Ar max_jobs
! 245: Specify the maximum number of jobs that
1.19 aaron 246: .Nm
1.28 aaron 247: may have running at any one time.
1.140 ! espie 248: See the discussion about recursive invocations under
! 249: .Sx BUGS .
1.5 niklas 250: .It Fl m Ar directory
1.104 espie 251: Specify a directory in which to search for system include files:
1.50 jmc 252: .Pa sys.mk
1.104 espie 253: and <...>-style inclusions.
254: Multiple directories can be added to form the system search path.
255: Using
256: .Fl m
257: will override the default system include directory
1.14 aaron 258: .Pa /usr/share/mk .
1.9 millert 259: .It Fl V Ar variable
260: Print
261: .Nm make Ns 's
262: idea of the value of
1.40 espie 263: .Ar variable .
1.9 millert 264: Do not build any targets.
265: Multiple instances of this option may be specified;
266: the variables will be printed one per line,
267: with a blank line for each null or undefined variable.
1.1 deraadt 268: .El
269: .Pp
1.95 espie 270: There are seven different types of lines in a makefile: dependency
271: lines, shell commands, variable assignments, include statements,
1.1 deraadt 272: conditional directives, for loops, and comments.
1.43 espie 273: Of these, include statements, conditional directives and for loops are
274: extensions.
1.1 deraadt 275: .Pp
1.95 espie 276: A complete target rule is composed of a dependency line,
277: followed by a list of shell commands.
278: .Pp
1.1 deraadt 279: In general, lines may be continued from one line to the next by ending
280: them with a backslash
281: .Pq Ql \e .
282: The trailing newline character and initial whitespace on the following
283: line are compressed into a single space.
1.95 espie 284: .Sh DEPENDENCY LINES
1.1 deraadt 285: Dependency lines consist of one or more targets, an operator, and zero
1.104 espie 286: or more prerequisites:
1.105 jmc 287: .Bd -ragged -offset indent
288: .Ar target ... : Ns Op Ar prerequisite ...
1.104 espie 289: .Ed
290: .Pp
1.19 aaron 291: This creates a relationship where the targets
292: .Dq depend
1.98 espie 293: on the prerequisites and are usually built from them.
1.96 espie 294: The exact relationship between targets and prerequisites is determined
1.1 deraadt 295: by the operator that separates them.
1.57 jmc 296: .Pp
1.96 espie 297: It is an error to use different dependency operators for the same target.
1.43 espie 298: .Pp
1.40 espie 299: The operators are as follows:
1.1 deraadt 300: .Bl -tag -width flag
301: .It Ic \&:
1.124 tb 302: A target is considered out of date if any of its prerequisites has
1.96 espie 303: been modified more recently than the target (that is, its modification time
304: is less than that of any of its prerequisites).
1.124 tb 305: Thus, targets with no prerequisites are always out of date.
1.96 espie 306: .Pp
307: .Nm
308: will then execute the list of shell commands associated with that target.
309: .Pp
310: Additional prerequisites may be specified over additional dependency lines:
311: .Nm
312: will consider all prerequisites for determining out-of-date status.
1.1 deraadt 313: The target is removed if
1.19 aaron 314: .Nm
1.1 deraadt 315: is interrupted.
316: .It Ic \&!
1.96 espie 317: .Nm
318: first examines all prerequisites and re-creates them as necessary.
319: .Pp
320: It will then always execute the list of shell commands associated with
1.124 tb 321: that target (as if the target always was out of date).
1.96 espie 322: .Pp
323: Like
324: .Ic \&: ,
325: additional prerequisites may be specified over additional dependency lines,
326: and the target is still removed if
1.19 aaron 327: .Nm
1.1 deraadt 328: is interrupted.
329: .It Ic \&::
1.96 espie 330: Each dependency line for a target is considered independently.
1.124 tb 331: A target is considered out of date for this target rule if any of its
1.96 espie 332: prerequisites in this dependency has been modified more recently than
333: the target.
334: .Pp
335: .Nm
336: will then execute the list of shell commands associated with that target.
337: Target rules that specify no prerequisites are always executed.
338: .Pp
1.1 deraadt 339: The target will not be removed if
1.19 aaron 340: .Nm
1.1 deraadt 341: is interrupted.
342: .El
343: .Pp
1.43 espie 344: The
1.96 espie 345: .Ic \&:
346: operator is the only standard operator.
347: The
1.43 espie 348: .Ic \&::
1.96 espie 349: operator is a fairly standard extension,
350: popularized by
1.123 schwarze 351: .Sy imake .
1.43 espie 352: The
1.56 jmc 353: .Ic !\&
1.106 jmc 354: operator is a
355: .Bx
356: extension.
1.43 espie 357: .Pp
1.95 espie 358: As an extension, targets and prerequisites may contain the shell wildcard
1.43 espie 359: expressions
1.55 jmc 360: .Ql \&? ,
1.1 deraadt 361: .Ql * ,
362: .Ql []
363: and
364: .Ql {} .
1.15 espie 365: The expressions
1.55 jmc 366: .Ql \&? ,
1.1 deraadt 367: .Ql *
368: and
369: .Ql []
370: may only be used as part of the final
1.95 espie 371: component of the target or prerequisite, and must be used to describe existing
1.1 deraadt 372: files.
1.15 espie 373: The expression
1.1 deraadt 374: .Ql {}
375: need not necessarily be used to describe existing files.
376: Expansion is in directory order, not alphabetically as done in the shell.
1.43 espie 377: .Pp
378: For maximum portability, target names should only consist of periods,
379: underscores, digits and alphabetic characters.
1.96 espie 380: .Pp
1.98 espie 381: The use of several targets can be a shorthand for duplicate rules.
1.96 espie 382: Specifically,
383: .Bd -literal -offset indent
384: target1 target2: reqa reqa
385: cmd1
386: cmd2
387: .Ed
388: .Pp
1.98 espie 389: may be replaced with
1.96 espie 390: .Bd -literal -offset indent
391: target1: reqa reqa
392: cmd1
393: cmd2
394: target2: reqa reqa
395: cmd1
396: cmd2
397: .Ed
398: .Pp
1.98 espie 399: in general.
400: But
1.96 espie 401: .Nm
1.99 espie 402: is aware of parallel issues, and will not build those targets concurrently,
403: if not appropriate.
1.1 deraadt 404: .Sh SHELL COMMANDS
405: Each target may have associated with it a series of shell commands, normally
1.98 espie 406: used to build the target.
1.95 espie 407: While several dependency lines may name the same target, only one of
408: these dependency lines should be followed by shell commands, and thus
409: define a complete target rule (unless the
410: .Sq Ic ::
411: operator is used).
412: Each of the shell commands in the target rule
1.1 deraadt 413: .Em must
414: be preceded by a tab.
415: .Pp
1.34 espie 416: If a command line begins with a combination of the characters,
1.54 jmc 417: .Sq Ic @ ,
418: .Sq Ic \-
1.1 deraadt 419: and/or
1.54 jmc 420: .Sq Ic + ,
1.57 jmc 421: the command is treated specially:
1.33 espie 422: .Bl -tag -width `@'
1.54 jmc 423: .It Sq Ic @
1.1 deraadt 424: causes the command not to be echoed before it is executed.
1.54 jmc 425: .It Sq Ic \-
1.1 deraadt 426: causes any non-zero exit status of the command line to be ignored.
1.54 jmc 427: .It Sq Ic +
1.33 espie 428: causes the command to be executed even if
429: .Fl n
1.57 jmc 430: has been specified.
431: (This can be useful to debug recursive Makefiles.)
1.33 espie 432: .El
1.43 espie 433: .Pp
1.104 espie 434: Commands are executed using
1.43 espie 435: .Pa /bin/sh
436: in
437: .Qq set -e
1.104 espie 438: mode, unless
439: .Sq Ic \-
440: is specified.
1.95 espie 441: .Pp
442: As an optimization,
443: .Nm
444: may execute very simple commands without going through an extra shell
445: process, as long as this does not change observable behavior.
1.96 espie 446: .Sh INFERENCE RULES
447: .Nm
448: also maintains a list of valid suffixes through the use of the
449: .Ic .SUFFIXES
450: special target.
451: .Pp
452: These suffixes can be used to write generic transformation rules called
453: inference rules.
454: .Pp
455: If a target has the form
456: .Sq \&.s1.s2 ,
457: where .s1 and .s2 are currently valid suffixes, then it defines a
1.98 espie 458: transformation from *.s1 to *.s2 (double suffix inference).
1.96 espie 459: If a target has the form
460: .Sq \&.s1 ,
461: where .s1 is a currently valid suffix, then it defines a
1.98 espie 462: transformation from *.s1 to * (single suffix inference).
1.96 espie 463: .Pp
464: A complete inference rule is a dependency line with such a target, the
465: normal dependency operator, no prerequisites and a list of shell commands.
466: .Pp
467: When
468: .Nm
469: requires a target for which it has no complete target rule, it will try
470: to apply a single active inference rule to create the target.
471: .Pp
472: For instance, with the following Makefile, describing a C program compiled
473: from sources a.c and b.c, with header file a.h:
474: .Bd -literal -offset indent
475: \&.SUFFIXES: .c .o
476: \&.c.o:
477: ${CC} ${CFLAGS} -c $<
478:
479: prog: a.o b.o
1.128 espie 480: ${CC} ${CFLAGS} -o $@ a.o b.o
1.96 espie 481:
482: a.o b.o: a.h
483:
484: b.o: b.c
485: ${CC} -DFOO ${CFLAGS} -o $@ $<
486: .Ed
487: .Pp
488: Consider b.o:
489: there is a complete target rule re-creating it from b.c, so
490: it will be compiled using ${CC} -DFOO.
491: .Pp
492: Consider a.o:
493: there is no explicit target rule, so
494: .Nm
495: will consider valid transforms.
496: Fortunately, there is an inference rule that can create a.o from a.c,
497: so it will be compiled using ${CC}.
498: .Pp
499: Note that extra prerequisites are still taken into account, so both a.o
500: and b.o depend on a.h for re-creation.
501: .Pp
502: Valid suffixes accumulate over
503: .Ic .SUFFIXES
504: lines.
505: An empty
506: .Ic .SUFFIXES
507: can be used to reset the currently valid list of suffixes,
508: but inference rules already read are still known by
509: .Nm ,
510: and they are marked as inactive.
1.107 jmc 511: Redefining the corresponding suffix (or suffixes) will reactivate the rule.
1.100 espie 512: .Pp
513: In case of duplicate inference rules with the same suffix combination,
514: the new rule overrides the old one.
1.96 espie 515: .Pp
516: For maximal portability, suffixes should start with a dot.
1.1 deraadt 517: .Sh VARIABLE ASSIGNMENTS
1.14 aaron 518: Variables in
1.19 aaron 519: .Nm
1.120 jmc 520: are much like variables in the shell and, by tradition,
1.1 deraadt 521: consist of all upper-case letters.
1.60 espie 522: They are also called
523: .Sq macros
524: in various texts.
1.43 espie 525: For portability, only periods, underscores, digits and letters should be
526: used for variable names.
1.126 anton 527: The following operators can be used to assign values to variables:
1.1 deraadt 528: .Bl -tag -width Ds
529: .It Ic \&=
530: Assign the value to the variable.
531: Any previous value is overridden.
1.43 espie 532: .It Ic \&:=
533: Assign with expansion, i.e., expand the value before assigning it
1.57 jmc 534: to the variable (extension).
1.1 deraadt 535: .It Ic \&+=
1.43 espie 536: Append the value to the current value of the variable (extension).
1.1 deraadt 537: .It Ic \&?=
1.106 jmc 538: Assign the value to the variable if it is not already defined
539: .Po
540: .Bx
541: extension
542: .Pc .
1.1 deraadt 543: Normally, expansion is not done until the variable is referenced.
544: .It Ic \&!=
1.122 jmc 545: Perform variable expansion and pass the result to the shell for
1.121 espie 546: execution on the spot, assigning the result to the variable.
547: Any newlines in the result are also replaced with spaces
1.106 jmc 548: .Po
549: .Bx
550: extension
551: .Pc .
1.121 espie 552: .It Ic \&!!=
1.122 jmc 553: Perform variable expansion on the spot and pass the result to the shell
554: for execution only when the value is needed, assigning the result to
1.121 espie 555: the variable.
556: .Pp
557: This is almost identical to
558: .Ic \&!=
559: except that a shell is only run when the variable value is needed.
560: Any newlines in the result are also replaced with spaces
561: .Po
562: .Ox
563: extension
564: .Pc .
1.1 deraadt 565: .El
566: .Pp
1.14 aaron 567: Any whitespace before the assigned
1.1 deraadt 568: .Ar value
569: is removed; if the value is being appended, a single space is inserted
570: between the previous contents of the variable and the appended value.
571: .Pp
1.101 espie 572: Several extended assignment operators may be combined together.
573: For instance,
574: .Bd -literal -offset indent
575: A ?!= cmd
576: .Ed
577: .Pp
578: will only run
579: .Qq cmd
580: and put its output into
581: .Va A
582: if
583: .Va A
584: is not yet defined.
1.121 espie 585: .Pp
586: Combinations that do not make sense, such as
587: .Bd -literal -offset indent
588: A +!!= cmd
589: .Ed
1.126 anton 590: .Pp
1.121 espie 591: will not work.
1.101 espie 592: .Pp
1.1 deraadt 593: Variables are expanded by surrounding the variable name with either
594: curly braces
595: .Pq Ql {}
596: or parentheses
597: .Pq Ql ()
598: and preceding it with
599: a dollar sign
600: .Pq Ql \&$ .
601: If the variable name contains only a single letter, the surrounding
602: braces or parentheses are not required.
603: This shorter form is not recommended.
604: .Pp
1.137 kn 605: Variable substitution occurs at distinct times, depending on the type of line.
606: Variables in dependency lines, conditional directives and include statements
607: are expanded as the line is read.
1.1 deraadt 608: Variables in shell commands are expanded when the shell command is
609: executed.
610: .Pp
611: The four different classes of variables (in order of increasing precedence)
612: are:
613: .Bl -tag -width Ds
614: .It Environment variables
615: Variables defined as part of
616: .Nm make Ns 's
617: environment.
618: .It Global variables
619: Variables defined in the makefile or in included makefiles.
620: .It Command line variables
621: Variables defined as part of the command line.
622: .It Local variables
623: Variables that are defined specific to a certain target.
1.43 espie 624: Standard local variables are as follows:
1.1 deraadt 625: .Bl -tag -width ".ARCHIVE"
1.43 espie 626: .It Va @
627: The name of the target.
628: .It Va \&%
629: The name of the archive member (only valid for library rules).
630: .It Va \&!
631: The name of the archive file (only valid for library rules).
632: .It Va \&?
1.124 tb 633: The list of prerequisites for this target that were deemed out of date.
1.43 espie 634: .It Va \&<
1.95 espie 635: The name of the prerequisite from which this target is to be built, if a valid
1.96 espie 636: inference rule (suffix rule) is in scope.
1.43 espie 637: .It Va *
638: The file prefix of the file, containing only the file portion,
639: no suffix or preceding directory components.
640: .El
641: .Pp
642: The six variables
1.54 jmc 643: .Sq Va "@F" ,
644: .Sq Va "@D" ,
645: .Sq Va "<F" ,
646: .Sq Va "<D" ,
647: .Sq Va "*F" ,
1.43 espie 648: and
1.54 jmc 649: .Sq Va "*D"
1.43 espie 650: yield the
651: .Qq filename
652: and
653: .Qq directory
654: parts of the corresponding macros.
655: .Pp
656: For maximum compatibility,
1.54 jmc 657: .Sq Va \&<
1.96 espie 658: should only be used for actual inference rules.
659: It is also set for normal target rules when there is an inference rule
660: that matches the current target and prerequisite in scope.
1.54 jmc 661: That is, in
1.57 jmc 662: .Bd -literal -offset indent
1.65 jmc 663: \&.SUFFIXES: .c .o
1.43 espie 664: file.o: file.c
665: cmd1 $<
666:
667: \&.c.o:
668: cmd2
669: .Ed
1.57 jmc 670: .Pp
1.43 espie 671: building
672: .Pa file.o
673: will execute
674: .Qq cmd1 file.c .
675: .Pp
676: As an extension,
677: .Nm
1.47 jsyn 678: supports the following local variables:
1.43 espie 679: .Bl -tag -width ".ARCHIVE"
680: .It Va \&>
1.95 espie 681: The list of all prerequisites for this target.
1.1 deraadt 682: .It Va .ALLSRC
1.43 espie 683: Synonym for
1.54 jmc 684: .Sq Va \&> .
1.1 deraadt 685: .It Va .ARCHIVE
1.43 espie 686: Synonym for
1.54 jmc 687: .Sq Va \&! .
1.1 deraadt 688: .It Va .IMPSRC
1.43 espie 689: Synonym for
1.54 jmc 690: .Sq Va \&< .
1.1 deraadt 691: .It Va .MEMBER
1.43 espie 692: Synonym for
1.54 jmc 693: .Sq Va \&% .
1.1 deraadt 694: .It Va .OODATE
1.43 espie 695: Synonym for
1.54 jmc 696: .Sq Va \&? .
1.1 deraadt 697: .It Va .PREFIX
1.43 espie 698: Synonym for
1.54 jmc 699: .Sq Va * .
1.1 deraadt 700: .It Va .TARGET
1.43 espie 701: Synonym for
1.54 jmc 702: .Sq Va @ .
1.1 deraadt 703: .El
704: .Pp
1.43 espie 705: These variables may be used on the dependency half of dependency
706: lines, when they make sense.
1.15 espie 707: .El
1.1 deraadt 708: .Pp
709: In addition,
1.19 aaron 710: .Nm
711: sets or knows about the following internal variables, or environment
1.15 espie 712: variables:
1.1 deraadt 713: .Bl -tag -width MAKEFLAGS
714: .It Va \&$
715: A single dollar sign
716: .Ql \&$ ,
1.29 aaron 717: i.e.,
1.1 deraadt 718: .Ql \&$$
719: expands to a single dollar
720: sign.
721: .It Va .MAKE
722: The name that
1.19 aaron 723: .Nm
1.1 deraadt 724: was executed with
1.14 aaron 725: .Pq Va argv Ns Op 0 .
1.1 deraadt 726: .It Va .CURDIR
727: A path to the directory where
1.19 aaron 728: .Nm
1.1 deraadt 729: was executed.
730: .It Va .OBJDIR
1.109 espie 731: Path to the directory where targets are built.
1.8 deraadt 732: At startup,
1.19 aaron 733: .Nm
1.109 espie 734: searches for an alternate directory to place target files.
1.19 aaron 735: .Nm
1.109 espie 736: tries to
737: .Xr chdir 2
738: into
739: .Ev MAKEOBJDIR
740: (or
741: .Pa obj
742: if
1.19 aaron 743: .Ev MAKEOBJDIR
1.109 espie 744: is not defined),
745: and sets
746: .Va .OBJDIR
747: accordingly.
1.28 aaron 748: Should that fail,
1.109 espie 749: .Va .OBJDIR
750: is set to
751: .Va .CURDIR .
1.117 espie 752: .It Va MAKEFILE_LIST
753: The list of files read by
754: .Nm .
1.15 espie 755: .It Va .MAKEFLAGS
1.1 deraadt 756: The environment variable
1.14 aaron 757: .Ev MAKEFLAGS
1.1 deraadt 758: may contain anything that
759: may be specified on
760: .Nm make Ns 's
1.28 aaron 761: command line.
762: Its contents are stored in
1.15 espie 763: .Nm make Ns 's
1.19 aaron 764: .Va .MAKEFLAGS
1.15 espie 765: variable.
1.40 espie 766: Anything specified on
1.1 deraadt 767: .Nm make Ns 's
768: command line is appended to the
1.15 espie 769: .Va .MAKEFLAGS
770: variable which is then
1.19 aaron 771: entered into the environment as
1.14 aaron 772: .Ev MAKEFLAGS
1.15 espie 773: for all programs which
1.19 aaron 774: .Nm
1.1 deraadt 775: executes.
1.15 espie 776: .It Va MFLAGS
1.19 aaron 777: A shorter synonym for
1.15 espie 778: .Va .MAKEFLAGS .
1.9 millert 779: .It Ev PWD
780: Alternate path to the current directory.
1.19 aaron 781: .Nm
1.9 millert 782: normally sets
1.54 jmc 783: .Sq Va .CURDIR
1.9 millert 784: to the canonical path given by
1.49 jmc 785: .Xr getcwd 3 .
1.9 millert 786: However, if the environment variable
1.14 aaron 787: .Ev PWD
1.9 millert 788: is set and gives a path to the current directory, then
1.19 aaron 789: .Nm
1.9 millert 790: sets
1.54 jmc 791: .Sq Va .CURDIR
1.9 millert 792: to the value of
1.14 aaron 793: .Ev PWD
1.9 millert 794: instead.
1.14 aaron 795: .Ev PWD
1.15 espie 796: is always set to the value of
1.54 jmc 797: .Sq Va .OBJDIR
1.9 millert 798: for all programs which
1.19 aaron 799: .Nm
1.9 millert 800: executes.
1.15 espie 801: .It Va .TARGETS
1.19 aaron 802: List of targets
803: .Nm
1.18 espie 804: is currently building.
1.15 espie 805: .It Va MACHINE
1.19 aaron 806: Name of the machine architecture
807: .Nm
1.18 espie 808: is running on, obtained from the
809: .Ev MACHINE
1.19 aaron 810: environment variable, or through
1.44 deraadt 811: .Xr uname 3
1.18 espie 812: if not defined.
1.15 espie 813: .It Va MACHINE_ARCH
1.18 espie 814: Name of the machine architecture
1.19 aaron 815: .Nm
1.18 espie 816: was compiled for, obtained from the
1.19 aaron 817: .Ev MACHINE_ARCH
1.18 espie 818: environment variable, or defined at compilation time.
1.85 miod 819: .It Va MACHINE_CPU
820: Name of the machine processor
821: .Nm
822: was compiled for, obtained from the
823: .Ev MACHINE_CPU
824: environment variable, or defined at compilation time.
825: On processors where only one endianness is possible, the value of this
826: variable is always the same as
827: .Ev MACHINE_ARCH .
1.80 bluhm 828: .It Va MAKEFILE
829: Possibly the file name of the last makefile that has been read.
830: It should not be used; see the
831: .Sx BUGS
832: section below.
1.1 deraadt 833: .El
834: .Pp
835: Variable expansion may be modified to select or modify each word of the
1.48 pvalchev 836: variable (where
1.19 aaron 837: .Dq word
1.48 pvalchev 838: is a whitespace delimited sequence of characters).
1.1 deraadt 839: The general format of a variable expansion is as follows:
840: .Pp
841: .Dl {variable[:modifier[:...]]}
842: .Pp
843: Each modifier begins with a colon and one of the following
844: special characters.
845: The colon may be escaped with a backslash
846: .Pq Ql \e .
1.54 jmc 847: .Bl -tag -width Ds
1.58 espie 848: .It Cm :E
1.1 deraadt 849: Replaces each word in the variable with its suffix.
1.58 espie 850: .It Cm :H
1.1 deraadt 851: Replaces each word in the variable with everything but the last component.
1.58 espie 852: .It Cm :L
1.20 espie 853: Replaces each word in the variable with its lower case equivalent.
1.58 espie 854: .It Cm :U
1.20 espie 855: Replaces each word in the variable with its upper case equivalent.
1.58 espie 856: .It Cm :M Ns Ar pattern
1.1 deraadt 857: Select only those words that match the rest of the modifier.
858: The standard shell wildcard characters
859: .Pf ( Ql * ,
1.55 jmc 860: .Ql \&? ,
1.1 deraadt 861: and
1.54 jmc 862: .Ql [] )
1.1 deraadt 863: may
864: be used.
865: The wildcard characters may be escaped with a backslash
866: .Pq Ql \e .
1.58 espie 867: .It Cm :N Ns Ar pattern
1.1 deraadt 868: This is identical to
1.58 espie 869: .Cm :M ,
1.1 deraadt 870: but selects all words which do not match
871: the rest of the modifier.
1.58 espie 872: .It Cm :Q
1.10 millert 873: Quotes every shell meta-character in the variable, so that it can be passed
874: safely through recursive invocations of
1.14 aaron 875: .Nm make .
1.88 espie 876: .It Cm :QL
877: Quote list: quotes every shell meta-character in the variable, except
878: whitespace, so that it can be passed to a shell's
879: .Sq for
880: loops.
1.58 espie 881: .It Cm :R
1.1 deraadt 882: Replaces each word in the variable with everything but its suffix.
883: .Sm off
1.58 espie 884: .It Cm :S No \&/ Ar old_string Xo
1.10 millert 885: .No \&/ Ar new_string
886: .No \&/ Op Cm 1g
1.1 deraadt 887: .Xc
888: .Sm on
889: Modify the first occurrence of
1.10 millert 890: .Ar old_string
891: in the variable's value, replacing it with
892: .Ar new_string .
1.1 deraadt 893: If a
894: .Ql g
895: is appended to the last slash of the pattern, all occurrences
896: in each word are replaced.
1.10 millert 897: If a
898: .Ql 1
899: is appended to the last slash of the pattern, only the first word
900: is affected.
1.1 deraadt 901: If
1.10 millert 902: .Ar old_string
903: begins with a caret
1.1 deraadt 904: .Pq Ql ^ ,
1.10 millert 905: .Ar old_string
1.1 deraadt 906: is anchored at the beginning of each word.
907: If
1.10 millert 908: .Ar old_string
1.1 deraadt 909: ends with a dollar sign
910: .Pq Ql \&$ ,
911: it is anchored at the end of each word.
912: Inside
913: .Ar new_string ,
914: an ampersand
915: .Pq Ql &
916: is replaced by
1.10 millert 917: .Ar old_string
918: (without any
919: .Ql ^
920: or
921: .Ql \&$ ) .
1.1 deraadt 922: Any character may be used as a delimiter for the parts of the modifier
923: string.
924: The anchoring, ampersand and delimiter characters may be escaped with a
925: backslash
926: .Pq Ql \e .
927: .Pp
928: Variable expansion occurs in the normal fashion inside both
929: .Ar old_string
930: and
931: .Ar new_string
932: with the single exception that a backslash is used to prevent the expansion
933: of a dollar sign
1.10 millert 934: .Pq Ql \&$ ,
1.1 deraadt 935: not a preceding dollar sign as is usual.
1.10 millert 936: .Sm off
1.58 espie 937: .It Cm :C No \&/ Ar pattern Xo
1.10 millert 938: .No \&/ Ar replacement
939: .No \&/ Op Cm 1g
940: .Xc
941: .Sm on
942: The
1.58 espie 943: .Cm :C
1.10 millert 944: modifier is just like the
1.58 espie 945: .Cm :S
1.13 deraadt 946: modifier except that the old and new strings, instead of being
1.103 naddy 947: simple strings, are an extended regular expression (see
948: .Xr re_format 7 )
1.10 millert 949: and an
950: .Xr ed 1 Ns \-style
1.28 aaron 951: replacement string.
952: Normally, the first occurrence of the pattern in
953: each word of the value is changed.
954: The
1.10 millert 955: .Ql 1
956: modifier causes the substitution to apply to at most one word; the
957: .Ql g
958: modifier causes the substitution to apply to as many instances of the
1.28 aaron 959: search pattern as occur in the word or words it is found in.
960: Note that
1.10 millert 961: .Ql 1
962: and
963: .Ql g
964: are orthogonal; the former specifies whether multiple words are
965: potentially affected, the latter whether multiple substitutions can
966: potentially occur within each affected word.
1.58 espie 967: .It Cm :T
1.1 deraadt 968: Replaces each word in the variable with its last component.
1.59 jmc 969: .It Ar :old_string Ns = Ns Ar new_string
1.1 deraadt 970: This is the
971: .At V
972: style variable substitution.
973: It must be the last modifier specified.
1.9 millert 974: If
1.1 deraadt 975: .Ar old_string
976: or
977: .Ar new_string
978: do not contain the pattern matching character
1.108 schwarze 979: .Sq %
1.9 millert 980: then it is assumed that they are
1.1 deraadt 981: anchored at the end of each word, so only suffixes or entire
1.28 aaron 982: words may be replaced.
983: Otherwise
1.108 schwarze 984: .Sq %
1.9 millert 985: is the substring of
986: .Ar old_string
1.1 deraadt 987: to be replaced in
1.53 jmc 988: .Ar new_string .
1.88 espie 989: The right hand side
990: .Pq Ar new_string
991: may contain variable values, which will be expanded.
992: To put an actual single dollar, just double it.
1.1 deraadt 993: .El
1.53 jmc 994: .Pp
1.106 jmc 995: All modifiers are
996: .Bx
997: extensions, except for the standard
1.46 espie 998: .At V
999: style variable substitution.
1.88 espie 1000: .Pp
1001: The interpretation of
1.108 schwarze 1002: .Sq %
1.88 espie 1003: and
1.108 schwarze 1004: .Sq $
1.88 espie 1005: in
1006: .At V
1007: variable substitutions is not mandated by POSIX, though it is
1008: fairly common.
1.1 deraadt 1009: .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1.28 aaron 1010: Makefile inclusion, conditional structures and for loops reminiscent
1.1 deraadt 1011: of the C programming language are provided in
1012: .Nm make .
1013: All such structures are identified by a line beginning with a single
1014: dot
1015: .Pq Ql \&.
1016: character.
1.46 espie 1017: Whitespace characters may follow this dot, e.g.,
1.57 jmc 1018: .Bd -literal -offset indent
1019: \&.include <file>
1.46 espie 1020: .Ed
1021: and
1.57 jmc 1022: .Bd -literal -offset indent -compact
1023: \&. include <file>
1.46 espie 1024: .Ed
1.57 jmc 1025: .Pp
1.46 espie 1026: are identical constructs.
1.1 deraadt 1027: Files are included with either
1028: .Ql .include <file>
1029: or
1.119 bentley 1030: .Ql .include Qq file .
1.1 deraadt 1031: Variables between the angle brackets or double quotes are expanded
1032: to form the file name.
1033: If angle brackets are used, the included makefile is expected to be in
1034: the system makefile directory.
1035: If double quotes are used, the including makefile's directory and any
1036: directories specified using the
1037: .Fl I
1038: option are searched before the system
1039: makefile directory.
1040: .Pp
1041: Conditional expressions are also preceded by a single dot as the first
1042: character of a line.
1043: The possible conditionals are as follows:
1044: .Bl -tag -width Ds
1045: .It Ic .undef Ar variable
1046: Un-define the specified global variable.
1047: Only global variables may be un-defined.
1.69 espie 1048: .It Ic .poison Ar variable
1049: Poison the specified global variable.
1.70 jmc 1050: Any further reference to
1.69 espie 1051: .Ar variable
1052: will be flagged as an error.
1.70 jmc 1053: .It Ic .poison !defined Pq Ar variable
1.69 espie 1054: It is an error to try to use the value of
1055: .Ar variable
1.70 jmc 1056: in a context where it is not defined.
1057: .It Ic .poison empty Pq Ar variable
1.69 espie 1058: It is an error to try to use the value of
1059: .Ar variable
1.127 jmc 1060: in a context where it is not defined or is empty.
1.1 deraadt 1061: .It Xo
1062: .Ic \&.if
1063: .Oo \&! Oc Ns Ar expression
1064: .Op Ar operator expression ...
1065: .Xc
1066: Test the value of an expression.
1067: .It Xo
1068: .Ic .ifdef
1069: .Oo \&! Oc Ns Ar variable
1070: .Op Ar operator variable ...
1071: .Xc
1072: Test the value of a variable.
1073: .It Xo
1074: .Ic .ifndef
1075: .Oo \&! Oc Ns Ar variable
1076: .Op Ar operator variable ...
1077: .Xc
1078: Test the value of a variable.
1079: .It Xo
1080: .Ic .ifmake
1081: .Oo \&! Oc Ns Ar target
1082: .Op Ar operator target ...
1083: .Xc
1084: Test the target being built.
1085: .It Xo
1086: .Ic .ifnmake
1.134 jmc 1087: .Oo \&! Oc Ns Ar target
1.1 deraadt 1088: .Op Ar operator target ...
1089: .Xc
1090: Test the target being built.
1091: .It Ic .else
1092: Reverse the sense of the last conditional.
1093: .It Xo
1094: .Ic .elif
1.134 jmc 1095: .Oo \&! Oc Ns Ar expression
1.1 deraadt 1096: .Op Ar operator expression ...
1097: .Xc
1098: A combination of
1.54 jmc 1099: .Sq Ic .else
1.1 deraadt 1100: followed by
1.54 jmc 1101: .Sq Ic .if .
1.1 deraadt 1102: .It Xo
1103: .Ic .elifdef
1104: .Oo \&! Oc Ns Ar variable
1105: .Op Ar operator variable ...
1106: .Xc
1107: A combination of
1.54 jmc 1108: .Sq Ic .else
1.1 deraadt 1109: followed by
1.54 jmc 1110: .Sq Ic .ifdef .
1.1 deraadt 1111: .It Xo
1112: .Ic .elifndef
1113: .Oo \&! Oc Ns Ar variable
1114: .Op Ar operator variable ...
1115: .Xc
1116: A combination of
1.54 jmc 1117: .Sq Ic .else
1.1 deraadt 1118: followed by
1.54 jmc 1119: .Sq Ic .ifndef .
1.1 deraadt 1120: .It Xo
1121: .Ic .elifmake
1122: .Oo \&! Oc Ns Ar target
1123: .Op Ar operator target ...
1124: .Xc
1125: A combination of
1.54 jmc 1126: .Sq Ic .else
1.1 deraadt 1127: followed by
1.54 jmc 1128: .Sq Ic .ifmake .
1.1 deraadt 1129: .It Xo
1130: .Ic .elifnmake
1131: .Oo \&! Oc Ns Ar target
1132: .Op Ar operator target ...
1133: .Xc
1134: A combination of
1.54 jmc 1135: .Sq Ic .else
1.1 deraadt 1136: followed by
1.54 jmc 1137: .Sq Ic .ifnmake .
1.1 deraadt 1138: .It Ic .endif
1139: End the body of the conditional.
1140: .El
1141: .Pp
1142: The
1143: .Ar operator
1144: may be any one of the following:
1145: .Bl -tag -width "Cm XX"
1.92 jmc 1146: .It Cm ||
1.1 deraadt 1147: logical OR
1148: .It Cm \&&&
1.110 guenther 1149: Logical AND; of higher precedence than
1.92 jmc 1150: .Cm || .
1.1 deraadt 1151: .El
1152: .Pp
1153: As in C,
1.19 aaron 1154: .Nm
1.1 deraadt 1155: will only evaluate a conditional as far as is necessary to determine
1156: its value.
1.9 millert 1157: Parentheses may be used to change the order of evaluation.
1.1 deraadt 1158: The boolean operator
1.54 jmc 1159: .Sq Ic \&!
1.1 deraadt 1160: may be used to logically negate an entire
1161: conditional.
1162: It is of higher precedence than
1.54 jmc 1163: .Sq Ic \&&& .
1.1 deraadt 1164: .Pp
1165: The value of
1166: .Ar expression
1167: may be any of the following:
1.99 espie 1168: .Bl -tag -width commands
1.98 espie 1169: .It Ic commands
1170: Takes a target name as an argument and evaluates to true if the target
1171: has been defined and has shell commands associated with it.
1.1 deraadt 1172: .It Ic defined
1173: Takes a variable name as an argument and evaluates to true if the variable
1174: has been defined.
1175: .It Ic make
1176: Takes a target name as an argument and evaluates to true if the target
1177: was specified as part of
1178: .Nm make Ns 's
1179: command line or was declared the default target (either implicitly or
1180: explicitly, see
1181: .Va .MAIN )
1182: before the line containing the conditional.
1183: .It Ic empty
1184: Takes a variable, with possible modifiers, and evaluates to true if
1185: the expansion of the variable would result in an empty string.
1186: .It Ic exists
1187: Takes a file name as an argument and evaluates to true if the file exists.
1188: The file is searched for on the system search path (see
1189: .Va .PATH ) .
1190: .It Ic target
1191: Takes a target name as an argument and evaluates to true if the target
1192: has been defined.
1193: .El
1194: .Pp
1.14 aaron 1195: .Ar expression
1.28 aaron 1196: may also be an arithmetic or string comparison.
1197: Variable expansion is
1.1 deraadt 1198: performed on both sides of the comparison, after which the integral
1.28 aaron 1199: values are compared.
1200: A value is interpreted as hexadecimal if it is
1.1 deraadt 1201: preceded by 0x, otherwise it is decimal; octal numbers are not supported.
1.28 aaron 1202: The standard C relational operators are all supported.
1203: If after
1.1 deraadt 1204: variable expansion, either the left or right hand side of a
1.54 jmc 1205: .Sq Ic ==
1.1 deraadt 1206: or
1.54 jmc 1207: .Sq Ic "!="
1.1 deraadt 1208: operator is not an integral value, then
1209: string comparison is performed between the expanded
1210: variables.
1211: If no relational operator is given, it is assumed that the expanded
1212: variable is being compared against 0.
1213: .Pp
1214: When
1.19 aaron 1215: .Nm
1.14 aaron 1216: is evaluating one of these conditional expressions, and it encounters
1.19 aaron 1217: a word it doesn't recognize, either the
1218: .Dq make
1219: or
1220: .Dq defined
1.1 deraadt 1221: expression is applied to it, depending on the form of the conditional.
1222: If the form is
1.54 jmc 1223: .Sq Ic .ifdef
1.1 deraadt 1224: or
1.54 jmc 1225: .Sq Ic .ifndef ,
1.19 aaron 1226: the
1227: .Dq defined
1228: expression is applied.
1.1 deraadt 1229: Similarly, if the form is
1.54 jmc 1230: .Sq Ic .ifmake
1.1 deraadt 1231: or
1.54 jmc 1232: .Sq Ic .ifnmake ,
1.19 aaron 1233: the
1234: .Dq make
1.1 deraadt 1235: expression is applied.
1236: .Pp
1.135 naddy 1237: If the conditional evaluates to true, the parsing of the makefile continues
1.1 deraadt 1238: as before.
1239: If it evaluates to false, the following lines are skipped.
1240: In both cases this continues until a
1.54 jmc 1241: .Sq Ic .else
1.1 deraadt 1242: or
1.54 jmc 1243: .Sq Ic .endif
1.1 deraadt 1244: is found.
1.9 millert 1245: .Pp
1.1 deraadt 1246: For loops are typically used to apply a set of rules to a list of files.
1247: The syntax of a for loop is:
1.54 jmc 1248: .Bd -unfilled -offset indent
1.91 schwarze 1249: .Ic .for Ar variable Oo Ar variable ... Oc Ic in Ar expression
1.54 jmc 1250: <make-rules>
1.91 schwarze 1251: .Ic .endfor
1.54 jmc 1252: .Ed
1253: .Pp
1.1 deraadt 1254: After the for
1.14 aaron 1255: .Ar expression
1.28 aaron 1256: is evaluated, it is split into words.
1.50 jmc 1257: On each iteration of the loop, one word is assigned to each
1.41 espie 1258: .Ar variable ,
1259: in order,
1.50 jmc 1260: and these
1261: .Ar variables
1.41 espie 1262: are substituted in the
1.9 millert 1263: .Ic make-rules
1.1 deraadt 1264: inside the body of the for loop.
1.41 espie 1265: The number of words must match the number of iteration variables;
1266: that is, if there are three iteration variables, the number of words
1.48 pvalchev 1267: must be a multiple of three.
1.45 espie 1268: .Pp
1269: Loops and conditional expressions may nest arbitrarily, but
1270: they may not cross include file boundaries.
1.116 espie 1271: .Pp
1272: .Nm
1273: also supports
1274: .Ic sinclude
1275: and
1276: .Ic -include
1277: for compatibility with other implementations.
1278: Both use the same syntax:
1279: .Bd -unfilled -offset indent
1280: .Ic sinclude Pa file
1281: .Ic -include Pa file
1282: .Ed
1283: .Pp
1284: .Po
1285: note no quotes around
1286: .Pa file
1287: .Pc
1288: and will include
1289: .Pa file ,
1290: but without any error if it does not exist.
1.1 deraadt 1291: .Sh COMMENTS
1292: Comments begin with a hash
1293: .Pq Ql \&#
1294: character, anywhere but in a shell
1.98 espie 1295: command line, and continue to the end of the line
1296: (but a
1297: .Pq Ql \&#
1298: character in a shell command line will be interpreted as a comment by
1299: the shell).
1.97 espie 1300: .Sh TARGET ATTRIBUTES
1301: Some targets may be tagged with some specific attributes by one
1302: of the
1303: .Sx SPECIAL TARGETS
1304: or
1305: .Sx SPECIAL PREREQUISITES
1306: described below.
1307: .Bl -tag -width "Ignoring errors"
1308: .It Dq Always build
1309: Run the commands associated with this target even if the
1310: .Fl n
1311: or
1312: .Fl t
1313: options were specified.
1314: Can be used to mark recursive
1315: .Nm make Ns 's ,
1316: but prefer standard
1317: .Sq Ic + Ns Ar cmd .
1318: .It Dq Cheap
1319: In parallel mode, don't scan the commands for occurrences of
1320: .Nm ,
1321: thus letting normal recursive
1322: .Fl j
1323: behavior apply.
1324: .It Dq Expensive
1325: In parallel mode, assume commands will invoke recursive commands.
1326: Once
1327: .Nm
1328: starts building an expensive target, it won't start building anything else
1329: until that target has finished building.
1330: .It Dq Ignoring errors
1331: Ignore any errors generating by running shell commands, exactly
1332: as if they were all preceded by a dash
1.1 deraadt 1333: .Pq Ql \- .
1.97 espie 1334: .It Dq Phony
1335: A phony target is a target that does not correspond to any object in the
1336: file system (more like a placeholder for a list of commands).
1337: .Pp
1.124 tb 1338: Phony targets are always out of date at the start of a run, but
1.97 espie 1339: .Nm
1340: still keeps track of when they are built (that is, when the associated
1341: command list finishes running).
1342: .It Dq Precious
1343: Don't remove the target if
1344: .Nm
1345: is interrupted in the middle of building it.
1346: .It Dq Silent
1347: Do not display shell commands before running them, exactly as
1348: if they were all preceded by a
1349: .Sq @ .
1350: .El
1351: .Sh SPECIAL TARGETS
1.19 aaron 1352: .Nm
1.97 espie 1353: recognizes standard special targets:
1354: .Bl -tag -width ".NOTPARALLEL"
1355: .It Ic .DEFAULT
1356: If there is a
1357: .Ic .DEFAULT
1.125 jmc 1358: target rule, with commands but no prerequisites, and
1.97 espie 1359: .Nm
1360: can't figure out another way to build a target, it will use that
1361: list of commands, setting
1362: .Va \&<
1363: and
1364: .Va @
1365: appropriately.
1366: .It Ic .IGNORE
1367: Mark its prerequisites as
1368: .Dq Ignoring errors .
1369: .Pp
1370: If the list of prerequisites is empty, apply that to all targets, exactly
1371: like the
1372: .Fl i
1373: command-line option.
1.1 deraadt 1374: .It Ic .PRECIOUS
1.97 espie 1375: Mark its prerequisites as
1376: .Dq Precious .
1377: .Pp
1378: If the list of prerequisites is empty, apply that to all targets.
1.1 deraadt 1379: .It Ic .SILENT
1.97 espie 1380: Mark its prerequisites as
1381: .Dq Silent .
1382: .Pp
1383: If the list of prerequisites is empty, apply that to all targets, exactly
1384: like the
1385: .Fl s
1386: command-line option.
1387: .It Ic .SUFFIXES
1388: See
1389: .Sx INFERENCE RULES .
1.1 deraadt 1390: .El
1.97 espie 1391: .Pp
1392: and also some other special targets as an extension:
1.54 jmc 1393: .Bl -tag -width ".NOTPARALLEL"
1.1 deraadt 1394: .It Ic .BEGIN
1.97 espie 1395: Command lines attached to this target are executed before anything
1.1 deraadt 1396: else is done.
1.93 espie 1397: .It Ic .CHEAP
1.97 espie 1398: Mark its prerequisites as
1399: .Dq Cheap .
1.1 deraadt 1400: .It Ic .END
1.97 espie 1401: Command lines attached to this target are executed at the end of a successful
1402: run.
1.93 espie 1403: .It Ic .EXPENSIVE
1.97 espie 1404: Mark its prerequisites as
1405: .Dq Expensive .
1406: .It Ic .INTERRUPT
1407: Command lines attached to this target are executed if
1408: .Nm
1409: is interrupted by a SIGINT.
1.95 espie 1410: .It Ic .MAKE
1.97 espie 1411: Mark its prerequisites as
1412: .Dq Always build .
1413: Prefer standard
1.95 espie 1414: .Sq Ic + Ns Ar cmd .
1.1 deraadt 1415: .It Ic .MAIN
1416: If no target is specified when
1.19 aaron 1417: .Nm
1.28 aaron 1418: is invoked, this target will be built.
1419: This is always set, either
1.19 aaron 1420: explicitly, or implicitly when
1421: .Nm
1.16 espie 1422: selects the default target, to give the user a way to refer to the default
1423: target on the command line.
1.1 deraadt 1424: .It Ic .MAKEFLAGS
1425: This target provides a way to specify flags for
1.19 aaron 1426: .Nm
1.1 deraadt 1427: when the makefile is used.
1428: The flags are as if typed to the shell, though the
1429: .Fl f
1430: option will have
1431: no effect.
1.4 deraadt 1432: .It Ic .NOTPARALLEL
1.98 espie 1433: Disable parallel mode for the current makefile.
1434: The
1435: .Fl j
1436: option is still passed to submakes.
1.4 deraadt 1437: .It Ic .NO_PARALLEL
1438: Same as above, for compatibility with other pmake variants.
1439: .It Ic .ORDER
1.97 espie 1440: The list of prerequisites should be built in sequence.
1.1 deraadt 1441: .It Ic .PATH
1.97 espie 1442: The prerequisites define a search path: directories that will be searched
1443: for files not found in the current directory.
1.95 espie 1444: If no prerequisites are specified, any previously specified directories are
1.1 deraadt 1445: deleted.
1.97 espie 1446: .It Ic .PATH\fI.suffix\fR
1447: This target is only valid if .suffix is a currently valid suffix.
1448: The prerequisites defines a search path for files ending in that suffix.
1449: For files not found in the current directory,
1.19 aaron 1450: .Nm
1.97 espie 1451: will first look in that path, before reverting to the default search path.
1.6 niklas 1452: .It Ic .PHONY
1.97 espie 1453: Mark its prerequisites as
1454: .Dq Phony
1455: targets.
1456: .El
1.98 espie 1457: .Pp
1458: It is an error to use several special targets, or a special target and
1459: normal targets, in a single dependency line.
1.97 espie 1460: .Sh SPECIAL PREREQUISITES
1.98 espie 1461: Of the special targets described in the previous
1462: section, the ones that tag prerequisites can also be used as prerequisites,
1463: in which case the corresponding targets will be tagged accordingly.
1464: .Pp
1465: This is an extension, even for standard special targets.
1466: .Pp
1467: .Nm
1468: also recognizes some other prerequisites:
1.97 espie 1469: .Bl -tag -width ".PRECIOUS"
1470: .It Ic .NOTMAIN
1471: Normally
1472: .Nm
1473: selects the first target it encounters as the default target to be built
1474: if no target was specified.
1475: This prerequisite prevents this target from being selected.
1476: .It Ic .OPTIONAL
1477: If a target is marked with this attribute and
1478: .Nm
1479: can't figure out how to create it, it will ignore this fact and assume
1480: the file isn't needed or already exists.
1481: .It Ic .USE
1482: Turn the target into
1483: .Nm make Ns 's
1484: version of a macro.
1485: When the target is used as a prerequisite for another target, the other target
1486: acquires the commands, prerequisites, and attributes (except for
1487: .Ic .USE )
1488: of the
1489: prerequisite.
1490: If the target already has commands, the
1491: .Ic .USE
1492: target's commands are appended
1493: to them.
1494: .It Ic .WAIT
1495: If
1496: .Ic .WAIT
1497: appears in a dependency line, the prerequisites that precede it are
1498: made before the prerequisites that follow it in the line.
1499: Loops are not
1500: detected and targets that form loops will be silently ignored.
1.35 aaron 1501: .El
1.1 deraadt 1502: .Sh ENVIRONMENT
1.19 aaron 1503: .Nm
1.15 espie 1504: uses the following environment variables, if they exist:
1.9 millert 1505: .Ev MACHINE ,
1.15 espie 1506: .Ev MACHINE_ARCH ,
1.86 jmc 1507: .Ev MACHINE_CPU ,
1.9 millert 1508: .Ev MAKEFLAGS ,
1.129 espie 1509: .Ev MAKEOBJDIR
1.1 deraadt 1510: and
1.9 millert 1511: .Ev PWD .
1.30 espie 1512: .Nm
1.31 aaron 1513: also ignores and unsets
1.30 espie 1514: .Ev CDPATH .
1.1 deraadt 1515: .Sh FILES
1516: .Bl -tag -width /usr/share/mk -compact
1.14 aaron 1517: .It Pa .depend
1.1 deraadt 1518: list of dependencies
1.114 deraadt 1519: .It Pa makefile
1.66 jmc 1520: default makefile
1.14 aaron 1521: .It Pa Makefile
1.66 jmc 1522: default makefile if
1523: .Pa makefile
1524: does not exist
1.14 aaron 1525: .It Pa sys.mk
1.1 deraadt 1526: system makefile
1.14 aaron 1527: .It Pa /usr/share/mk
1.1 deraadt 1528: system makefile directory
1529: .El
1.89 jmc 1530: .Sh EXIT STATUS
1531: If
1532: .Fl q
1533: was specified, the
1534: .Nm
1535: utility exits with one of the following values:
1536: .Pp
1537: .Bl -tag -width Ds -offset indent -compact
1538: .It 0
1539: Normal behavior.
1540: .It 1
1.124 tb 1541: The target was not up to date.
1.119 bentley 1542: .It >1
1.89 jmc 1543: An error occurred.
1544: .El
1545: .Pp
1546: Otherwise, the
1547: .Nm
1.119 bentley 1548: utility exits with a value of 0 on success, and >0 if an error occurred.
1.37 aaron 1549: .Sh SEE ALSO
1.57 jmc 1550: .Xr ed 1 ,
1551: .Xr mkdep 1 ,
1552: .Xr sh 1 ,
1553: .Xr getcwd 3 ,
1.103 naddy 1554: .Xr uname 3 ,
1555: .Xr re_format 7
1.132 jsg 1556: .Rs
1557: .%A S. I. Feldman
1558: .%T Make \(em A Program for Maintaining Computer Programs
1.133 jsg 1559: .\".%R Computing Science Technical Report
1560: .\".%N 57
1561: .%J Software \(em Practice and Experience
1562: .%V 9:4
1563: .%P pp. 255-265
1.132 jsg 1564: .%D April 1979
1565: .Re
1566: .Rs
1567: .\" 4.4BSD PSD:12
1568: .%A Adam de Boor
1569: .%T PMake \(em A Tutorial
1570: .%B 4.4BSD Programmer's Supplementary Documents (PSD)
1571: .Re
1.52 jmc 1572: .Sh STANDARDS
1.67 jmc 1573: The
1.43 espie 1574: .Nm
1.95 espie 1575: utility is mostly compliant with the
1.83 jmc 1576: .St -p1003.1-2008
1.113 jmc 1577: specification,
1578: though its presence is optional.
1.67 jmc 1579: .Pp
1580: The flags
1.118 espie 1581: .Op Fl BCDdIjmV
1.67 jmc 1582: are extensions to that specification.
1.43 espie 1583: .Pp
1.37 aaron 1584: Older versions of
1585: .Nm
1586: used
1587: .Ev MAKE
1588: instead of
1589: .Ev MAKEFLAGS .
1590: This was removed for POSIX compatibility.
1591: The internal variable
1592: .Va MAKE
1593: is set to the same value as
1.48 pvalchev 1594: .Va .MAKE .
1595: Support for this may be removed in the future.
1.37 aaron 1596: .Pp
1597: Most of the more esoteric features of
1598: .Nm
1599: should probably be avoided for greater compatibility.
1600: .Sh HISTORY
1601: A
1602: .Nm
1.136 jsg 1603: command first appeared outside of Bell Labs in PWB/UNIX 1.0.
1604: It was replaced in
1605: .Bx 4.3 Reno .
1606: .Sh AUTHORS
1607: .An Stuart Feldman
1608: wrote the original implementation at the
1.138 jsg 1609: Bell Labs Computing Science Research Center.
1.95 espie 1610: .Pp
1611: This implementation is a distant derivative of
1612: .Nm pmake ,
1.136 jsg 1613: originally written by Adam de Boor for the Sprite operating system.
1.17 espie 1614: .Sh BUGS
1.98 espie 1615: If the same target is specified several times in complete target rules,
1.31 aaron 1616: .Nm
1.101 espie 1617: silently ignores all commands after the first non empty set of commands,
1.31 aaron 1618: e.g., in
1.57 jmc 1619: .Bd -literal -offset indent
1.27 espie 1620: a:
1621: @echo "Executed"
1622: a:
1623: @echo "Bad luck"
1624: .Ed
1625: .Pp
1.98 espie 1626: @echo "Bad luck" will be ignored.
1.18 espie 1627: .Pp
1628: .Va .TARGETS
1629: is not set to the default target when
1.19 aaron 1630: .Nm
1.18 espie 1631: is invoked without a target name and no
1.19 aaron 1632: .Ic MAIN
1.18 espie 1633: special target exists.
1634: .Pp
1.17 espie 1635: The evaluation of
1636: .Ar expression
1.98 espie 1637: in a test is somewhat simplistic.
1.99 espie 1638: Variables don't need to be quoted, but strings do:
1.98 espie 1639: Tests like
1.64 mbalmer 1640: .Ql .if ${VAR} == "string" ,
1.99 espie 1641: .Ql .if ${VAR} >= 5 ,
1642: .Ql .if 5 <= 10 ,
1.98 espie 1643: and
1644: .Ql .if "string" == ${VAR}
1645: do work, but
1646: .Ql .if string = ${VAR}
1.99 espie 1647: doesn't.
1.17 espie 1648: .Pp
1649: For loops are expanded before tests, so a fragment such as:
1.57 jmc 1650: .Bd -literal -offset indent
1.17 espie 1651: \&.for TMACHINE in ${SHARED_ARCHS}
1.98 espie 1652: \&.if "${TMACHINE}" == ${MACHINE}
1.17 espie 1653: ...
1654: \&.endif
1.32 ericj 1655: \&.endfor
1.17 espie 1656: .Ed
1.25 espie 1657: .Pp
1.98 espie 1658: requires the quotes.
1.21 espie 1659: .Pp
1.106 jmc 1660: When handling
1661: .Pf pre- Bx 4.4
1662: archives,
1.21 espie 1663: .Nm
1664: may erroneously mark archive members as out of date if the archive name
1665: was truncated.
1.26 espie 1666: .Pp
1.57 jmc 1667: The handling of
1668: .Sq ;\&
1669: and other special characters in tests may be utterly bogus.
1.28 aaron 1670: For instance, in
1.57 jmc 1671: .Bd -literal -offset indent
1.25 espie 1672: \&A=abcd;c.c
1673: \&.if ${A:R} == "abcd;c"
1674: .Ed
1675: .Pp
1676: the test will never match, even though the value is correct.
1677: .Pp
1.57 jmc 1678: In a .for loop, only the variable value is used; assignments will be
1.25 espie 1679: evaluated later, e.g., in
1.57 jmc 1680: .Bd -literal -offset indent
1.25 espie 1681: \&.for I in a b c d
1.102 william 1682: I:=${I:S/a/z/}
1.25 espie 1683: A+=$I
1684: \&.endfor
1685: .Ed
1.57 jmc 1686: .Pp
1687: .Sq A
1688: will evaluate to a b c d after the loop, not z b c d.
1.73 espie 1689: .Pp
1690: .Ic ORDER
1.95 espie 1691: is currently only used in parallel mode, so
1692: keep prerequisites ordered for sequential mode!
1.78 espie 1693: .Pp
1.79 jmc 1694: Distinct target names are treated separately, even though they might
1.78 espie 1695: correspond to the same file in the file system.
1696: This can cause excessive rebuilds of some targets, and bogus
1697: races in parallel mode.
1698: This can also prevent
1699: .Nm
1700: from finding a rule to solve a dependency if the target name is not
1701: exactly the same as the dependency.
1702: .Pp
1703: In parallel mode,
1704: .Fl j Ar n
1.95 espie 1705: only limits the number of direct children of
1706: .Nm .
1707: During recursive invocations, each level may multiply the total number
1.78 espie 1708: of processes by
1.79 jmc 1709: .Ar n .
1.95 espie 1710: However,
1711: .Nm
1712: includes some heuristics to try to prevent catastrophic behavior:
1713: if a command is marked as expensive, or preceded by
1714: .Sq + ,
1715: or seems to
1716: invoke a program that looks sufficiently like
1717: .Sq make ,
1718: .Nm
1719: will assume recursive invocation, and not start any new process until
1720: said command has finished running.
1721: Thus the number of processes run directly or indirectly by
1722: .Nm
1723: will increase linearly with each level of recursion instead of exponentially.
1.80 bluhm 1724: .Pp
1725: The
1726: .Va MAKEFILE
1727: variable cannot be used reliably.
1728: It is a compatibility feature and may get set to the last makefile
1729: specified, as it is set by System V make.
![[BACK]](/icons/back.gif){kind=icon}
Return to make.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / make