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