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