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