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