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