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