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