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