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