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