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