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