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