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