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