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