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