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