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