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