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