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