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