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