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