Annotation of src/usr.bin/make/make.1, Revision 1.214
1.214 ! christos 1: .\" $NetBSD: make.1,v 1.213 2013/03/31 05:49:51 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.214 ! christos 32: .Dd May 22, 2013
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.159 sjg 41: .Op Fl C Ar directory
1.1 cgd 42: .Op Fl D Ar variable
43: .Op Fl d Ar flags
44: .Op Fl f Ar makefile
45: .Op Fl I Ar directory
1.104 wiz 46: .Op Fl J Ar private
47: .Op Fl j Ar max_jobs
1.13 christos 48: .Op Fl m Ar directory
1.44 sommerfe 49: .Op Fl T Ar file
1.16 christos 50: .Op Fl V Ar variable
1.1 cgd 51: .Op Ar variable=value
52: .Op Ar target ...
53: .Sh DESCRIPTION
1.25 lukem 54: .Nm
1.1 cgd 55: is a program designed to simplify the maintenance of other programs.
56: Its input is a list of specifications as to the files upon which programs
57: and other files depend.
1.128 dsl 58: If no
59: .Fl f Ar makefile
60: makefile option is given,
61: .Nm
62: will try to open
1.1 cgd 63: .Ql Pa makefile
1.128 dsl 64: then
1.1 cgd 65: .Ql Pa Makefile
1.128 dsl 66: in order to find the specifications.
1.1 cgd 67: If the file
68: .Ql Pa .depend
69: exists, it is read (see
1.66 wiz 70: .Xr mkdep 1 ) .
1.1 cgd 71: .Pp
72: This manual page is intended as a reference document only.
73: For a more thorough description of
1.25 lukem 74: .Nm
1.1 cgd 75: and makefiles, please refer to
1.197 dholland 76: .%T "PMake \- A Tutorial" .
1.1 cgd 77: .Pp
1.128 dsl 78: .Nm
79: will prepend the contents of the
80: .Va MAKEFLAGS
81: environment variable to the command line arguments before parsing them.
82: .Pp
1.1 cgd 83: The options are as follows:
84: .Bl -tag -width Ds
1.16 christos 85: .It Fl B
1.10 christos 86: Try to be backwards compatible by executing a single shell per command and
87: by executing the commands to make the sources of a dependency line in sequence.
1.159 sjg 88: .It Fl C Ar directory
89: Change to
90: .Ar directory
91: before reading the makefiles or doing anything else.
92: If multiple
93: .Fl C
94: options are specified, each is interpreted relative to the previous one:
95: .Fl C Pa / Fl C Pa etc
96: is equivalent to
97: .Fl C Pa /etc .
1.1 cgd 98: .It Fl D Ar variable
1.8 christos 99: Define
100: .Ar variable
1.1 cgd 101: to be 1, in the global context.
1.128 dsl 102: .It Fl d Ar [-]flags
1.1 cgd 103: Turn on debugging, and specify which portions of
1.25 lukem 104: .Nm
1.1 cgd 105: are to print debugging information.
1.128 dsl 106: Unless the flags are preceded by
1.194 sjg 107: .Ql \-
1.128 dsl 108: they are added to the
109: .Va MAKEFLAGS
110: environment variable and will be processed by any child make processes.
1.141 apb 111: By default, debugging information is printed to standard error,
1.138 apb 112: but this can be changed using the
1.140 wiz 113: .Ar F
1.138 apb 114: debugging flag.
1.139 apb 115: The debugging output is always unbuffered; in addition, if debugging
116: is enabled but debugging output is not directed to standard output,
117: then the standard output is line buffered.
1.1 cgd 118: .Ar Flags
119: is one or more of the following:
120: .Bl -tag -width Ds
121: .It Ar A
122: Print all possible debugging information;
123: equivalent to specifying all of the debugging flags.
124: .It Ar a
125: Print debugging information about archive searching and caching.
1.147 christos 126: .It Ar C
127: Print debugging information about current working directory.
1.1 cgd 128: .It Ar c
129: Print debugging information about conditional evaluation.
130: .It Ar d
131: Print debugging information about directory searching and caching.
1.88 jmmv 132: .It Ar e
133: Print debugging information about failed commands and targets.
1.138 apb 134: .It Ar F Ns Oo Sy \&+ Oc Ns Ar filename
135: Specify where debugging output is written.
136: This must be the last flag, because it consumes the remainder of
137: the argument.
138: If the character immediately after the
139: .Ql F
140: flag is
141: .Ql \&+ ,
142: then the file will be opened in append mode;
143: otherwise the file will be overwritten.
144: If the file name is
145: .Ql stdout
146: or
147: .Ql stderr
148: then debugging output will be written to the
149: standard output or standard error output file descriptors respectively
150: (and the
151: .Ql \&+
152: option has no effect).
153: Otherwise, the output will be written to the named file.
154: If the file name ends
1.128 dsl 155: .Ql .%d
156: then the
157: .Ql %d
158: is replaced by the pid.
1.87 jmmv 159: .It Ar f
160: Print debugging information about loop evaluation.
1.1 cgd 161: .It Ar "g1"
162: Print the input graph before making anything.
163: .It Ar "g2"
164: Print the input graph after making everything, or before exiting
1.93 dsl 165: on error.
1.92 dsl 166: .It Ar "g3"
167: Print the input graph before exiting on error.
1.1 cgd 168: .It Ar j
169: Print debugging information about running multiple shells.
1.135 sjg 170: .It Ar l
171: Print commands in Makefiles regardless of whether or not they are prefixed by
1.137 wiz 172: .Ql @
1.135 sjg 173: or other "quiet" flags.
174: Also known as "loud" behavior.
1.180 sjg 175: .It Ar M
176: Print debugging information about "meta" mode decisions about targets.
1.1 cgd 177: .It Ar m
178: Print debugging information about making targets, including modification
179: dates.
1.111 jmc 180: .It Ar n
1.154 apb 181: Don't delete the temporary command scripts created when running commands.
182: These temporary scripts are created in the directory
183: referred to by the
184: .Ev TMPDIR
185: environment variable, or in
1.112 wiz 186: .Pa /tmp
1.154 apb 187: if
188: .Ev TMPDIR
189: is unset or set to the empty string.
190: The temporary scripts are created by
191: .Xr mkstemp 3 ,
1.112 wiz 192: and have names of the form
1.154 apb 193: .Pa makeXXXXXX .
1.123 wiz 194: .Em NOTE :
1.156 snj 195: This can create many files in
1.154 apb 196: .Ev TMPDIR
197: or
198: .Pa /tmp ,
1.123 wiz 199: so use with care.
1.119 dsl 200: .It Ar p
201: Print debugging information about makefile parsing.
1.1 cgd 202: .It Ar s
203: Print debugging information about suffix-transformation rules.
204: .It Ar t
205: Print debugging information about target list maintenance.
1.205 sjg 206: .It Ar V
207: Force the
208: .Fl V
1.206 wiz 209: option to print raw values of variables.
1.1 cgd 210: .It Ar v
211: Print debugging information about variable assignment.
1.49 sjg 212: .It Ar x
1.57 wiz 213: Run shell commands with
214: .Fl x
215: so the actual commands are printed as they are executed.
1.1 cgd 216: .El
217: .It Fl e
1.68 perry 218: Specify that environment variables override macro assignments within
1.1 cgd 219: makefiles.
220: .It Fl f Ar makefile
221: Specify a makefile to read instead of the default
1.103 wiz 222: .Ql Pa makefile .
1.1 cgd 223: If
224: .Ar makefile
225: is
226: .Ql Fl ,
227: standard input is read.
1.103 wiz 228: Multiple makefiles may be specified, and are read in the order specified.
1.1 cgd 229: .It Fl I Ar directory
230: Specify a directory in which to search for makefiles and included makefiles.
1.13 christos 231: The system makefile directory (or directories, see the
232: .Fl m
233: option) is automatically included as part of this list.
1.1 cgd 234: .It Fl i
235: Ignore non-zero exit of shell commands in the makefile.
236: Equivalent to specifying
237: .Ql Fl
238: before each command line in the makefile.
1.44 sommerfe 239: .It Fl J Ar private
240: This option should
241: .Em not
242: be specified by the user.
243: .Pp
244: When the
245: .Ar j
246: option is in use in a recursive build, this option is passed by a make
247: to child makes to allow all the make processes in the build to
248: cooperate to avoid overloading the system.
1.1 cgd 249: .It Fl j Ar max_jobs
250: Specify the maximum number of jobs that
1.25 lukem 251: .Nm
1.67 grant 252: may have running at any one time.
1.180 sjg 253: The value is saved in
254: .Va .MAKE.JOBS .
1.67 grant 255: Turns compatibility mode off, unless the
1.11 christos 256: .Ar B
257: flag is also specified.
1.148 christos 258: When compatibility mode is off, all commands associated with a
259: target are executed in a single shell invocation as opposed to the
260: traditional one shell invocation per line.
261: This can break traditional scripts which change directories on each
262: command invocation and then expect to start with a fresh environment
263: on the next line.
264: It is more efficient to correct the scripts rather than turn backwards
265: compatibility on.
1.1 cgd 266: .It Fl k
267: Continue processing after errors are encountered, but only on those targets
268: that do not depend on the target whose creation caused the error.
1.13 christos 269: .It Fl m Ar directory
270: Specify a directory in which to search for sys.mk and makefiles included
1.99 wiz 271: via the
272: .Ao Ar file Ac Ns -style
273: include statement.
1.98 chuck 274: The
275: .Fl m
276: option can be used multiple times to form a search path.
1.13 christos 277: This path will override the default system include path: /usr/share/mk.
278: Furthermore the system include path will be appended to the search path used
1.99 wiz 279: for
280: .Qo Ar file Qc Ns -style
281: include statements (see the
1.13 christos 282: .Fl I
283: option).
1.98 chuck 284: .Pp
285: If a file or directory name in the
286: .Fl m
1.99 wiz 287: argument (or the
288: .Ev MAKESYSPATH
289: environment variable) starts with the string
290: .Qq \&.../
291: then
292: .Nm
293: will search for the specified file or directory named in the remaining part
294: of the argument string.
295: The search starts with the current directory of
1.98 chuck 296: the Makefile and then works upward towards the root of the filesystem.
1.99 wiz 297: If the search is successful, then the resulting directory replaces the
298: .Qq \&.../
299: specification in the
1.98 chuck 300: .Fl m
1.99 wiz 301: argument.
302: If used, this feature allows
1.98 chuck 303: .Nm
304: to easily search in the current source tree for customized sys.mk files
1.99 wiz 305: (e.g., by using
306: .Qq \&.../mk/sys.mk
307: as an argument).
1.1 cgd 308: .It Fl n
1.45 sommerfe 309: Display the commands that would have been executed, but do not
310: actually execute them unless the target depends on the .MAKE special
1.64 wiz 311: source (see below).
1.45 sommerfe 312: .It Fl N
313: Display the commands which would have been executed, but do not
314: actually execute any of them; useful for debugging top-level makefiles
315: without descending into subdirectories.
1.1 cgd 316: .It Fl q
317: Do not execute any commands, but exit 0 if the specified targets are
318: up-to-date and 1, otherwise.
319: .It Fl r
320: Do not use the built-in rules specified in the system makefile.
321: .It Fl s
322: Do not echo any commands as they are executed.
323: Equivalent to specifying
324: .Ql Ic @
325: before each command line in the makefile.
1.44 sommerfe 326: .It Fl T Ar tracefile
327: When used with the
1.48 wiz 328: .Fl j
1.44 sommerfe 329: flag,
330: append a trace record to
331: .Ar tracefile
332: for each job started and completed.
1.1 cgd 333: .It Fl t
334: Rather than re-building a target as specified in the makefile, create it
335: or update its modification time to make it appear up-to-date.
1.16 christos 336: .It Fl V Ar variable
337: Print
1.74 wiz 338: .Nm Ns 's
1.16 christos 339: idea of the value of
340: .Ar variable ,
341: in the global context.
342: Do not build any targets.
343: Multiple instances of this option may be specified;
344: the variables will be printed one per line,
345: with a blank line for each null or undefined variable.
1.85 sjg 346: If
347: .Ar variable
348: contains a
349: .Ql \&$
350: then the value will be expanded before printing.
1.46 christos 351: .It Fl W
352: Treat any warnings during makefile parsing as errors.
1.75 thorpej 353: .It Fl X
354: Don't export variables passed on the command line to the environment
355: individually.
356: Variables passed on the command line are still exported
357: via the
358: .Va MAKEFLAGS
359: environment variable.
360: This option may be useful on systems which have a small limit on the
361: size of command arguments.
1.1 cgd 362: .It Ar variable=value
363: Set the value of the variable
364: .Ar variable
365: to
366: .Ar value .
1.75 thorpej 367: Normally, all values passed on the command line are also exported to
368: sub-makes in the environment.
369: The
370: .Fl X
371: flag disables this behavior.
1.101 wiz 372: Variable assignments should follow options for POSIX compatibility
1.100 ross 373: but no ordering is enforced.
1.1 cgd 374: .El
375: .Pp
1.6 cgd 376: There are seven different types of lines in a makefile: file dependency
1.1 cgd 377: specifications, shell commands, variable assignments, include statements,
1.6 cgd 378: conditional directives, for loops, and comments.
1.1 cgd 379: .Pp
380: In general, lines may be continued from one line to the next by ending
381: them with a backslash
382: .Pq Ql \e .
383: The trailing newline character and initial whitespace on the following
384: line are compressed into a single space.
385: .Sh FILE DEPENDENCY SPECIFICATIONS
386: Dependency lines consist of one or more targets, an operator, and zero
387: or more sources.
1.137 wiz 388: This creates a relationship where the targets
389: .Dq depend
390: on the sources
1.1 cgd 391: and are usually created from them.
392: The exact relationship between the target and the source is determined
393: by the operator that separates them.
394: The three operators are as follows:
395: .Bl -tag -width flag
396: .It Ic \&:
397: A target is considered out-of-date if its modification time is less than
398: those of any of its sources.
399: Sources for a target accumulate over dependency lines when this operator
400: is used.
401: The target is removed if
1.25 lukem 402: .Nm
1.1 cgd 403: is interrupted.
404: .It Ic \&!
405: Targets are always re-created, but not until all sources have been
406: examined and re-created as necessary.
407: Sources for a target accumulate over dependency lines when this operator
408: is used.
409: The target is removed if
1.25 lukem 410: .Nm
1.1 cgd 411: is interrupted.
412: .It Ic \&::
413: If no sources are specified, the target is always re-created.
414: Otherwise, a target is considered out-of-date if any of its sources has
415: been modified more recently than the target.
416: Sources for a target do not accumulate over dependency lines when this
417: operator is used.
418: The target will not be removed if
1.25 lukem 419: .Nm
1.1 cgd 420: is interrupted.
421: .El
422: .Pp
423: Targets and sources may contain the shell wildcard values
1.80 wiz 424: .Ql \&? ,
1.1 cgd 425: .Ql * ,
1.103 wiz 426: .Ql [] ,
1.1 cgd 427: and
428: .Ql {} .
429: The values
1.80 wiz 430: .Ql \&? ,
1.103 wiz 431: .Ql * ,
1.1 cgd 432: and
433: .Ql []
434: may only be used as part of the final
435: component of the target or source, and must be used to describe existing
436: files.
437: The value
438: .Ql {}
439: need not necessarily be used to describe existing files.
440: Expansion is in directory order, not alphabetically as done in the shell.
441: .Sh SHELL COMMANDS
442: Each target may have associated with it a series of shell commands, normally
443: used to create the target.
444: Each of the commands in this script
445: .Em must
446: be preceded by a tab.
447: While any target may appear on a dependency line, only one of these
448: dependencies may be followed by a creation script, unless the
1.91 lukem 449: .Ql Ic \&::
1.1 cgd 450: operator is used.
451: .Pp
1.102 sjg 452: If the first characters of the command line are any combination of
453: .Ql Ic @ ,
1.103 wiz 454: .Ql Ic + ,
1.102 sjg 455: or
1.1 cgd 456: .Ql Ic \- ,
457: the command is treated specially.
458: A
459: .Ql Ic @
460: causes the command not to be echoed before it is executed.
461: A
1.102 sjg 462: .Ql Ic +
463: causes the command to be executed even when
464: .Fl n
465: is given.
466: This is similar to the effect of the .MAKE special source,
467: except that the effect can be limited to a single line of a script.
468: A
1.1 cgd 469: .Ql Ic \-
470: causes any non-zero exit status of the command line to be ignored.
1.210 sjg 471: .Pp
472: When
473: .Nm
474: is run in jobs mode with
475: .Fl j Ar max_jobs ,
476: the entire script for the target is fed to a
477: single instance of the shell.
478: .Pp
479: In compatibility (non-jobs) mode, each command is run in a separate process.
480: If the command contains any shell meta characters
481: .Pq Ql #=|^(){};&<>*?[]:$`\e\en
482: it will be passed to the shell, otherwise
483: .Nm
484: will attempt direct execution.
485: .Pp
486: Since
487: .Nm
488: will
489: .Xr chdir 2
490: to
491: .Ql Va .OBJDIR
492: before executing any targets, each child process
493: starts with that as its current working directory.
494: .Pp
495: Makefiles should be written so that the mode of
496: .Nm
497: operation does not change their behavior.
498: For example, any command which needs to use
499: .Dq cd
500: or
501: .Dq chdir ,
502: without side-effect should be put in parenthesis:
503: .Bd -literal -offset indent
504:
505: avoid-chdir-side-effects:
506: @echo Building $@ in `pwd`
507: @(cd ${.CURDIR} && ${.MAKE} $@)
508: @echo Back in `pwd`
509:
510: ensure-one-shell-regardless-of-mode:
511: @echo Building $@ in `pwd`; \\
512: (cd ${.CURDIR} && ${.MAKE} $@); \\
513: echo Back in `pwd`
514: .Ed
1.1 cgd 515: .Sh VARIABLE ASSIGNMENTS
516: Variables in make are much like variables in the shell, and, by tradition,
517: consist of all upper-case letters.
1.91 lukem 518: .Ss Variable assignment modifiers
1.1 cgd 519: The five operators that can be used to assign values to variables are as
520: follows:
521: .Bl -tag -width Ds
522: .It Ic \&=
523: Assign the value to the variable.
524: Any previous value is overridden.
525: .It Ic \&+=
526: Append the value to the current value of the variable.
527: .It Ic \&?=
528: Assign the value to the variable if it is not already defined.
529: .It Ic \&:=
530: Assign with expansion, i.e. expand the value before assigning it
531: to the variable.
532: Normally, expansion is not done until the variable is referenced.
1.124 sjg 533: .Em NOTE :
534: References to undefined variables are
535: .Em not
1.125 wiz 536: expanded.
537: This can cause problems when variable modifiers are used.
1.1 cgd 538: .It Ic \&!=
539: Expand the value and pass it to the shell for execution and assign
540: the result to the variable.
541: Any newlines in the result are replaced with spaces.
542: .El
543: .Pp
544: Any white-space before the assigned
545: .Ar value
546: is removed; if the value is being appended, a single space is inserted
547: between the previous contents of the variable and the appended value.
548: .Pp
549: Variables are expanded by surrounding the variable name with either
550: curly braces
551: .Pq Ql {}
1.7 mycroft 552: or parentheses
1.1 cgd 553: .Pq Ql ()
554: and preceding it with
555: a dollar sign
556: .Pq Ql \&$ .
557: If the variable name contains only a single letter, the surrounding
1.7 mycroft 558: braces or parentheses are not required.
1.1 cgd 559: This shorter form is not recommended.
560: .Pp
1.149 dsl 561: If the variable name contains a dollar, then the name itself is expanded first.
562: This allows almost arbitrary variable names, however names containing dollar,
563: braces, parenthesis, or whitespace are really best avoided!
564: .Pp
565: If the result of expanding a variable contains a dollar sign
566: .Pq Ql \&$
567: the string is expanded again.
568: .Pp
1.175 christos 569: Variable substitution occurs at three distinct times, depending on where
1.1 cgd 570: the variable is being used.
1.175 christos 571: .Bl -enum
1.176 wiz 572: .It
1.1 cgd 573: Variables in dependency lines are expanded as the line is read.
1.175 christos 574: .It
1.1 cgd 575: Variables in shell commands are expanded when the shell command is
576: executed.
1.175 christos 577: .It
578: .Dq .for
1.176 wiz 579: loop index variables are expanded on each loop iteration.
580: Note that other variables are not expanded inside loops so
1.175 christos 581: the following example code:
582: .Bd -literal -offset indent
583:
584: .Dv .for i in 1 2 3
585: a+= ${i}
586: j= ${i}
587: b+= ${j}
588: .Dv .endfor
589:
590: all:
1.176 wiz 591: @echo ${a}
1.175 christos 592: @echo ${b}
593:
594: .Ed
595: will print:
596: .Bd -literal -offset indent
597: 1 2 3
598: 3 3 3
599:
600: .Ed
601: Because while ${a} contains
602: .Dq 1 2 3
603: after the loop is executed, ${b}
604: contains
605: .Dq ${j} ${j} ${j}
606: which expands to
607: .Dq 3 3 3
608: since after the loop completes ${j} contains
609: .Dq 3 .
610: .El
1.91 lukem 611: .Ss Variable classes
1.1 cgd 612: The four different classes of variables (in order of increasing precedence)
613: are:
614: .Bl -tag -width Ds
615: .It Environment variables
616: Variables defined as part of
1.74 wiz 617: .Nm Ns 's
1.1 cgd 618: environment.
619: .It Global variables
620: Variables defined in the makefile or in included makefiles.
621: .It Command line variables
622: Variables defined as part of the command line.
623: .It Local variables
624: Variables that are defined specific to a certain target.
625: The seven local variables are as follows:
626: .Bl -tag -width ".ARCHIVE"
627: .It Va .ALLSRC
628: The list of all sources for this target; also known as
1.62 ross 629: .Ql Va \&\*[Gt] .
1.1 cgd 630: .It Va .ARCHIVE
631: The name of the archive file.
632: .It Va .IMPSRC
1.136 cube 633: In suffix-transformation rules, the name/path of the source from which the
1.137 wiz 634: target is to be transformed (the
635: .Dq implied
636: source); also known as
1.62 ross 637: .Ql Va \&\*[Lt] .
1.136 cube 638: It is not defined in explicit rules.
1.1 cgd 639: .It Va .MEMBER
640: The name of the archive member.
641: .It Va .OODATE
642: The list of sources for this target that were deemed out-of-date; also
643: known as
644: .Ql Va \&? .
645: .It Va .PREFIX
1.177 dholland 646: The file prefix of the target, containing only the file portion, no suffix
1.1 cgd 647: or preceding directory components; also known as
648: .Ql Va * .
649: .It Va .TARGET
650: The name of the target; also known as
651: .Ql Va @ .
652: .El
653: .Pp
654: The shorter forms
655: .Ql Va @ ,
1.80 wiz 656: .Ql Va \&? ,
1.65 christos 657: .Ql Va \&\*[Lt] ,
658: .Ql Va \&\*[Gt] ,
1.1 cgd 659: and
660: .Ql Va *
661: are permitted for backward
662: compatibility with historical makefiles and are not recommended.
663: The six variables
664: .Ql Va "@F" ,
665: .Ql Va "@D" ,
1.62 ross 666: .Ql Va "\*[Lt]F" ,
667: .Ql Va "\*[Lt]D" ,
1.66 wiz 668: .Ql Va "*F" ,
1.1 cgd 669: and
670: .Ql Va "*D"
1.66 wiz 671: are permitted for compatibility with
1.1 cgd 672: .At V
673: makefiles and are not recommended.
674: .Pp
675: Four of the local variables may be used in sources on dependency lines
676: because they expand to the proper value for each target on the line.
677: These variables are
678: .Ql Va .TARGET ,
679: .Ql Va .PREFIX ,
680: .Ql Va .ARCHIVE ,
681: and
682: .Ql Va .MEMBER .
1.59 bgrayson 683: .El
1.145 christos 684: .Ss Additional built-in variables
1.1 cgd 685: In addition,
1.25 lukem 686: .Nm
1.1 cgd 687: sets or knows about the following variables:
1.50 sjg 688: .Bl -tag -width .MAKEOVERRIDES
1.1 cgd 689: .It Va \&$
690: A single dollar sign
691: .Ql \&$ ,
692: i.e.
693: .Ql \&$$
694: expands to a single dollar
695: sign.
1.56 tv 696: .It Va .ALLTARGETS
1.67 grant 697: The list of all targets encountered in the Makefile.
698: If evaluated during
1.56 tv 699: Makefile parsing, lists only those targets encountered thus far.
1.1 cgd 700: .It Va .CURDIR
701: A path to the directory where
1.25 lukem 702: .Nm
1.1 cgd 703: was executed.
1.117 lukem 704: Refer to the description of
705: .Ql Ev PWD
706: for more details.
1.78 christos 707: .It Ev MAKE
1.55 tv 708: The name that
709: .Nm
1.89 sjg 710: was executed with
711: .Pq Va argv[0] .
1.126 reed 712: For compatibility
1.78 christos 713: .Nm
714: also sets
715: .Va .MAKE
716: with the same value.
1.97 lukem 717: The preferred variable to use is the environment variable
1.78 christos 718: .Ev MAKE
719: because it is more compatible with other versions of
720: .Nm
721: and cannot be confused with the special target with the same name.
1.168 sjg 722: .It Va .MAKE.DEPENDFILE
1.169 wiz 723: Names the makefile (default
1.168 sjg 724: .Ql Pa .depend )
725: from which generated dependencies are read.
1.205 sjg 726: .It Va .MAKE.EXPAND_VARIABLES
727: A boolean that controls the default behavior of the
728: .Fl V
729: option.
1.134 sjg 730: .It Va .MAKE.EXPORTED
731: The list of variables exported by
732: .Nm .
1.171 sjg 733: .It Va .MAKE.JOBS
1.172 joerg 734: The argument to the
1.171 sjg 735: .Fl j
736: option.
1.132 sjg 737: .It Va .MAKE.JOB.PREFIX
1.137 wiz 738: If
1.132 sjg 739: .Nm
740: is run with
741: .Ar j
1.137 wiz 742: then output for each target is prefixed with a token
1.132 sjg 743: .Ql --- target ---
744: the first part of which can be controlled via
745: .Va .MAKE.JOB.PREFIX .
746: .br
1.137 wiz 747: For example:
1.132 sjg 748: .Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}]
749: would produce tokens like
750: .Ql ---make[1234] target ---
751: making it easier to track the degree of parallelism being achieved.
1.1 cgd 752: .It Ev MAKEFLAGS
753: The environment variable
754: .Ql Ev MAKEFLAGS
755: may contain anything that
756: may be specified on
1.74 wiz 757: .Nm Ns 's
1.1 cgd 758: command line.
759: Anything specified on
1.74 wiz 760: .Nm Ns 's
1.1 cgd 761: command line is appended to the
762: .Ql Ev MAKEFLAGS
763: variable which is then
764: entered into the environment for all programs which
1.25 lukem 765: .Nm
1.1 cgd 766: executes.
1.169 wiz 767: .It Va .MAKE.LEVEL
768: The recursion depth of
769: .Nm .
770: The initial instance of
771: .Nm
772: will be 0, and an incremented value is put into the environment
773: to be seen by the next generation.
774: This allows tests like:
775: .Li .if ${.MAKE.LEVEL} == 0
776: to protect things which should only be evaluated in the initial instance of
777: .Nm .
778: .It Va .MAKE.MAKEFILE_PREFERENCE
779: The ordered list of makefile names
780: (default
781: .Ql Pa makefile ,
782: .Ql Pa Makefile )
783: that
784: .Nm
785: will look for.
786: .It Va .MAKE.MAKEFILES
787: The list of makefiles read by
788: .Nm ,
789: which is useful for tracking dependencies.
1.204 sjg 790: Each makefile is recorded only once, regardless of the number of times read.
1.169 wiz 791: .It Va .MAKE.MODE
792: Processed after reading all makefiles.
793: Can affect the mode that
794: .Nm
795: runs in.
1.180 sjg 796: It can contain a number of keywords:
797: .Bl -hang -width ignore-cmd
798: .It Pa compat
1.182 wiz 799: Like
1.184 sjg 800: .Fl B ,
1.182 wiz 801: puts
1.180 sjg 802: .Nm
803: into "compat" mode.
804: .It Pa meta
805: Puts
806: .Nm
1.182 wiz 807: into "meta" mode, where meta files are created for each target
1.180 sjg 808: to capture the command run, the output generated and if
809: .Xr filemon 4
810: is available, the system calls which are of interest to
811: .Nm .
812: The captured output can be very useful when diagnosing errors.
1.185 sjg 813: .It Pa curdirOk= Ar bf
1.184 sjg 814: Normally
815: .Nm
816: will not create .meta files in
817: .Ql Va .CURDIR .
818: This can be overridden by setting
1.188 wiz 819: .Va bf
1.184 sjg 820: to a value which represents True.
1.200 sjg 821: .It Pa env
822: For debugging, it can be useful to inlcude the environment
823: in the .meta file.
1.180 sjg 824: .It Pa verbose
825: If in "meta" mode, print a clue about the target being built.
826: This is useful if the build is otherwise running silently.
827: The message printed the value of:
828: .Va .MAKE.META.PREFIX .
829: .It Pa ignore-cmd
830: Some makefiles have commands which are simply not stable.
1.182 wiz 831: This keyword causes them to be ignored for
1.180 sjg 832: determining whether a target is out of date in "meta" mode.
833: See also
834: .Ic .NOMETA_CMP .
1.195 sjg 835: .It Pa silent= Ar bf
836: If
837: .Va bf
838: is True, when a .meta file is created, mark the target
1.200 sjg 839: .Ic .SILENT .
1.180 sjg 840: .El
1.189 sjg 841: .It Va .MAKE.META.BAILIWICK
842: In "meta" mode, provides a list of prefixes which
843: match the directories controlled by
844: .Nm .
845: If a file that was generated outside of
846: .Va .OBJDIR
847: but within said bailiwick is missing,
848: the current target is considered out-of-date.
1.180 sjg 849: .It Va .MAKE.META.CREATED
850: In "meta" mode, this variable contains a list of all the meta files
851: updated.
852: If not empty, it can be used to trigger processing of
853: .Va .MAKE.META.FILES .
854: .It Va .MAKE.META.FILES
855: In "meta" mode, this variable contains a list of all the meta files
856: used (updated or not).
1.182 wiz 857: This list can be used to process the meta files to extract dependency
1.180 sjg 858: information.
859: .It Va .MAKE.META.PREFIX
860: Defines the message printed for each meta file updated in "meta verbose" mode.
861: The default value is:
862: .Dl Building ${.TARGET:H:tA}/${.TARGET:T}
1.50 sjg 863: .It Va .MAKEOVERRIDES
1.57 wiz 864: This variable is used to record the names of variables assigned to
865: on the command line, so that they may be exported as part of
1.50 sjg 866: .Ql Ev MAKEFLAGS .
1.57 wiz 867: This behaviour can be disabled by assigning an empty value to
1.50 sjg 868: .Ql Va .MAKEOVERRIDES
1.67 grant 869: within a makefile.
870: Extra variables can be exported from a makefile
1.57 wiz 871: by appending their names to
1.51 sjg 872: .Ql Va .MAKEOVERRIDES .
873: .Ql Ev MAKEFLAGS
1.57 wiz 874: is re-exported whenever
1.51 sjg 875: .Ql Va .MAKEOVERRIDES
876: is modified.
1.212 sjg 877: .It Va .MAKE.PATH_FILEMON
878: If
879: .Nm
880: was built with
881: .Xr filemon 4
882: support, this is set to the path of the device node.
883: This allows makefiles to test for this support.
1.169 wiz 884: .It Va .MAKE.PID
885: The process-id of
886: .Nm .
887: .It Va .MAKE.PPID
888: The parent process-id of
889: .Nm .
1.55 tv 890: .It Va MAKE_PRINT_VAR_ON_ERROR
1.57 wiz 891: When
1.55 tv 892: .Nm
893: stops due to an error, it prints its name and the value of
894: .Ql Va .CURDIR
1.57 wiz 895: as well as the value of any variables named in
1.55 tv 896: .Ql Va MAKE_PRINT_VAR_ON_ERROR .
897: .It Va .newline
898: This variable is simply assigned a newline character as its value.
1.91 lukem 899: This allows expansions using the
900: .Cm \&:@
901: modifier to put a newline between
1.67 grant 902: iterations of the loop rather than a space.
903: For example, the printing of
1.55 tv 904: .Ql Va MAKE_PRINT_VAR_ON_ERROR
905: could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}.
906: .It Va .OBJDIR
907: A path to the directory where the targets are built.
1.117 lukem 908: Its value is determined by trying to
909: .Xr chdir 2
910: to the following directories in order and using the first match:
911: .Bl -enum
912: .It
1.118 wiz 913: .Ev ${MAKEOBJDIRPREFIX}${.CURDIR}
914: .Pp
1.117 lukem 915: (Only if
916: .Ql Ev MAKEOBJDIRPREFIX
917: is set in the environment or on the command line.)
918: .It
1.118 wiz 919: .Ev ${MAKEOBJDIR}
920: .Pp
1.117 lukem 921: (Only if
922: .Ql Ev MAKEOBJDIR
923: is set in the environment or on the command line.)
924: .It
925: .Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE}
926: .It
927: .Ev ${.CURDIR} Ns Pa /obj
928: .It
929: .Pa /usr/obj/ Ns Ev ${.CURDIR}
930: .It
931: .Ev ${.CURDIR}
932: .El
933: .Pp
934: Variable expansion is performed on the value before it's used,
935: so expressions such as
1.173 sjg 936: .Dl ${.CURDIR:S,^/usr/src,/var/obj,}
1.117 lukem 937: may be used.
1.173 sjg 938: This is especially useful with
939: .Ql Ev MAKEOBJDIR .
1.117 lukem 940: .Pp
941: .Ql Va .OBJDIR
942: may be modified in the makefile as a global variable.
1.137 wiz 943: In all cases,
1.117 lukem 944: .Nm
945: will
946: .Xr chdir 2
947: to
948: .Ql Va .OBJDIR
949: and set
950: .Ql Ev PWD
951: to that directory before executing any targets.
952: .
1.55 tv 953: .It Va .PARSEDIR
954: A path to the directory of the current
955: .Ql Pa Makefile
956: being parsed.
957: .It Va .PARSEFILE
958: The basename of the current
959: .Ql Pa Makefile
960: being parsed.
961: This variable and
962: .Ql Va .PARSEDIR
963: are both set only while the
964: .Ql Pa Makefiles
965: are being parsed.
1.196 christos 966: If you want to retain their current values, assign them to a variable
967: using assignment with expansion:
968: .Pq Ql Cm \&:= .
1.69 sjg 969: .It Va .PATH
1.82 wiz 970: A variable that represents the list of directories that
1.69 sjg 971: .Nm
1.70 wiz 972: will search for files.
973: The search list should be updated using the target
1.69 sjg 974: .Ql Va .PATH
975: rather than the variable.
1.16 christos 976: .It Ev PWD
977: Alternate path to the current directory.
1.25 lukem 978: .Nm
1.16 christos 979: normally sets
980: .Ql Va .CURDIR
981: to the canonical path given by
1.48 wiz 982: .Xr getcwd 3 .
1.16 christos 983: However, if the environment variable
984: .Ql Ev PWD
985: is set and gives a path to the current directory, then
1.25 lukem 986: .Nm
1.16 christos 987: sets
988: .Ql Va .CURDIR
989: to the value of
990: .Ql Ev PWD
1.67 grant 991: instead.
992: This behaviour is disabled if
1.40 sjg 993: .Ql Ev MAKEOBJDIRPREFIX
1.117 lukem 994: is set or
995: .Ql Ev MAKEOBJDIR
996: contains a variable transform.
1.16 christos 997: .Ql Ev PWD
998: is set to the value of
999: .Ql Va .OBJDIR
1000: for all programs which
1.25 lukem 1001: .Nm
1.16 christos 1002: executes.
1.179 dholland 1003: .It Ev .TARGETS
1004: The list of targets explicitly specified on the command line, if any.
1.145 christos 1005: .It Ev VPATH
1.146 wiz 1006: Colon-separated
1007: .Pq Dq \&:
1008: lists of directories that
1009: .Nm
1010: will search for files.
1.145 christos 1011: The variable is supported for compatibility with old make programs only,
1012: use
1013: .Ql Va .PATH
1014: instead.
1.1 cgd 1015: .El
1.91 lukem 1016: .Ss Variable modifiers
1.1 cgd 1017: Variable expansion may be modified to select or modify each word of the
1.137 wiz 1018: variable (where a
1019: .Dq word
1020: is white-space delimited sequence of characters).
1.1 cgd 1021: The general format of a variable expansion is as follows:
1022: .Pp
1.120 sjg 1023: .Dl ${variable[:modifier[:...]]}
1.1 cgd 1024: .Pp
1.97 lukem 1025: Each modifier begins with a colon,
1026: which may be escaped with a backslash
1.1 cgd 1027: .Pq Ql \e .
1.120 sjg 1028: .Pp
1029: A set of modifiers can be specified via a variable, as follows:
1030: .Pp
1031: .Dl modifier_variable=modifier[:...]
1032: .Dl ${variable:${modifier_variable}[:...]}
1033: .Pp
1034: In this case the first modifier in the modifier_variable does not
1035: start with a colon, since that must appear in the referencing
1036: variable.
1037: If any of the modifiers in the modifier_variable contain a dollar sign
1038: .Pq Ql $ ,
1039: these must be doubled to avoid early expansion.
1040: .Pp
1.97 lukem 1041: The supported modifiers are:
1.61 ross 1042: .Bl -tag -width EEE
1.91 lukem 1043: .It Cm \&:E
1.1 cgd 1044: Replaces each word in the variable with its suffix.
1.91 lukem 1045: .It Cm \&:H
1.1 cgd 1046: Replaces each word in the variable with everything but the last component.
1.91 lukem 1047: .It Cm \&:M Ns Ar pattern
1.72 uebayasi 1048: Select only those words that match
1049: .Ar pattern .
1.1 cgd 1050: The standard shell wildcard characters
1051: .Pf ( Ql * ,
1.80 wiz 1052: .Ql \&? ,
1.1 cgd 1053: and
1.172 joerg 1054: .Ql Oo Oc )
1.1 cgd 1055: may
1056: be used.
1057: The wildcard characters may be escaped with a backslash
1058: .Pq Ql \e .
1.91 lukem 1059: .It Cm \&:N Ns Ar pattern
1.1 cgd 1060: This is identical to
1.91 lukem 1061: .Ql Cm \&:M ,
1.1 cgd 1062: but selects all words which do not match
1.72 uebayasi 1063: .Ar pattern .
1.91 lukem 1064: .It Cm \&:O
1.109 wiz 1065: Order every word in variable alphabetically.
1066: To sort words in
1067: reverse order use the
1.108 sjg 1068: .Ql Cm \&:O:[-1..1]
1069: combination of modifiers.
1070: .It Cm \&:Ox
1.109 wiz 1071: Randomize words in variable.
1072: The results will be different each time you are referring to the
1073: modified variable; use the assignment with expansion
1.108 sjg 1074: .Pq Ql Cm \&:=
1.109 wiz 1075: to prevent such behaviour.
1076: For example,
1.108 sjg 1077: .Bd -literal -offset indent
1078: LIST= uno due tre quattro
1079: RANDOM_LIST= ${LIST:Ox}
1080: STATIC_RANDOM_LIST:= ${LIST:Ox}
1081:
1082: all:
1083: @echo "${RANDOM_LIST}"
1084: @echo "${RANDOM_LIST}"
1085: @echo "${STATIC_RANDOM_LIST}"
1086: @echo "${STATIC_RANDOM_LIST}"
1087: .Ed
1.109 wiz 1088: may produce output similar to:
1.108 sjg 1089: .Bd -literal -offset indent
1090: quattro due tre uno
1091: tre due quattro uno
1092: due uno quattro tre
1093: due uno quattro tre
1094: .Ed
1.91 lukem 1095: .It Cm \&:Q
1.17 christos 1096: Quotes every shell meta-character in the variable, so that it can be passed
1097: safely through recursive invocations of
1.74 wiz 1098: .Nm .
1.91 lukem 1099: .It Cm \&:R
1.1 cgd 1100: Replaces each word in the variable with everything but its suffix.
1.187 sjg 1101: .It Cm \&:gmtime
1.188 wiz 1102: The value is a format string for
1.187 sjg 1103: .Xr strftime 3 ,
1.188 wiz 1104: using the current
1.187 sjg 1105: .Xr gmtime 3 .
1.186 joerg 1106: .It Cm \&:hash
1107: Compute a 32bit hash of the value and encode it as hex digits.
1.187 sjg 1108: .It Cm \&:localtime
1.188 wiz 1109: The value is a format string for
1.187 sjg 1110: .Xr strftime 3 ,
1.188 wiz 1111: using the current
1.187 sjg 1112: .Xr localtime 3 .
1.170 sjg 1113: .It Cm \&:tA
1114: Attempt to convert variable to an absolute path using
1115: .Xr realpath 3 ,
1116: if that fails, the value is unchanged.
1.91 lukem 1117: .It Cm \&:tl
1.60 pk 1118: Converts variable to lower-case letters.
1.91 lukem 1119: .It Cm \&:ts Ns Ar c
1.81 sjg 1120: Words in the variable are normally separated by a space on expansion.
1121: This modifier sets the separator to the character
1122: .Ar c .
1123: If
1124: .Ar c
1125: is omitted, then no separator is used.
1.170 sjg 1126: The common escapes (including octal numeric codes), work as expected.
1.91 lukem 1127: .It Cm \&:tu
1.82 wiz 1128: Converts variable to upper-case letters.
1.91 lukem 1129: .It Cm \&:tW
1.89 sjg 1130: Causes the value to be treated as a single word
1131: (possibly containing embedded white space).
1132: See also
1.91 lukem 1133: .Ql Cm \&:[*] .
1134: .It Cm \&:tw
1.89 sjg 1135: Causes the value to be treated as a sequence of
1136: words delimited by white space.
1137: See also
1.91 lukem 1138: .Ql Cm \&:[@] .
1.1 cgd 1139: .Sm off
1.164 joerg 1140: .It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW
1.1 cgd 1141: .Sm on
1142: Modify the first occurrence of
1.17 christos 1143: .Ar old_string
1144: in the variable's value, replacing it with
1145: .Ar new_string .
1.1 cgd 1146: If a
1147: .Ql g
1148: is appended to the last slash of the pattern, all occurrences
1149: in each word are replaced.
1.17 christos 1150: If a
1151: .Ql 1
1152: is appended to the last slash of the pattern, only the first word
1153: is affected.
1.89 sjg 1154: If a
1155: .Ql W
1156: is appended to the last slash of the pattern,
1157: then the value is treated as a single word
1158: (possibly containing embedded white space).
1.1 cgd 1159: If
1.17 christos 1160: .Ar old_string
1161: begins with a caret
1.1 cgd 1162: .Pq Ql ^ ,
1.17 christos 1163: .Ar old_string
1.1 cgd 1164: is anchored at the beginning of each word.
1165: If
1.17 christos 1166: .Ar old_string
1.1 cgd 1167: ends with a dollar sign
1168: .Pq Ql \&$ ,
1169: it is anchored at the end of each word.
1170: Inside
1171: .Ar new_string ,
1172: an ampersand
1.62 ross 1173: .Pq Ql \*[Am]
1.1 cgd 1174: is replaced by
1.17 christos 1175: .Ar old_string
1176: (without any
1177: .Ql ^
1178: or
1179: .Ql \&$ ) .
1.1 cgd 1180: Any character may be used as a delimiter for the parts of the modifier
1181: string.
1182: The anchoring, ampersand and delimiter characters may be escaped with a
1183: backslash
1184: .Pq Ql \e .
1185: .Pp
1186: Variable expansion occurs in the normal fashion inside both
1187: .Ar old_string
1188: and
1189: .Ar new_string
1190: with the single exception that a backslash is used to prevent the expansion
1191: of a dollar sign
1.17 christos 1192: .Pq Ql \&$ ,
1.1 cgd 1193: not a preceding dollar sign as is usual.
1.17 christos 1194: .Sm off
1.164 joerg 1195: .It Cm \&:C No \&/ Ar pattern No \&/ Ar replacement No \&/ Op Cm 1gW
1.17 christos 1196: .Sm on
1197: The
1.91 lukem 1198: .Cm \&:C
1.17 christos 1199: modifier is just like the
1.91 lukem 1200: .Cm \&:S
1.37 msaitoh 1201: modifier except that the old and new strings, instead of being
1.17 christos 1202: simple strings, are a regular expression (see
1203: .Xr regex 3 )
1.72 uebayasi 1204: string
1205: .Ar pattern
1.17 christos 1206: and an
1207: .Xr ed 1 Ns \-style
1.72 uebayasi 1208: string
1209: .Ar replacement .
1210: Normally, the first occurrence of the pattern
1211: .Ar pattern
1212: in each word of the value is substituted with
1213: .Ar replacement .
1.67 grant 1214: The
1.17 christos 1215: .Ql 1
1216: modifier causes the substitution to apply to at most one word; the
1217: .Ql g
1218: modifier causes the substitution to apply to as many instances of the
1.72 uebayasi 1219: search pattern
1220: .Ar pattern
1.89 sjg 1221: as occur in the word or words it is found in; the
1222: .Ql W
1223: modifier causes the value to be treated as a single word
1224: (possibly containing embedded white space).
1.67 grant 1225: Note that
1.17 christos 1226: .Ql 1
1227: and
1228: .Ql g
1229: are orthogonal; the former specifies whether multiple words are
1230: potentially affected, the latter whether multiple substitutions can
1231: potentially occur within each affected word.
1.91 lukem 1232: .It Cm \&:T
1.1 cgd 1233: Replaces each word in the variable with its last component.
1.91 lukem 1234: .It Cm \&:u
1.43 christos 1235: Remove adjacent duplicate words (like
1.57 wiz 1236: .Xr uniq 1 ) .
1.91 lukem 1237: .Sm off
1238: .It Cm \&:\&? Ar true_string Cm \&: Ar false_string
1239: .Sm on
1.152 dsl 1240: If the variable name (not its value), when parsed as a .if conditional
1241: expression, evaluates to true, return as its value the
1.57 wiz 1242: .Ar true_string ,
1.27 christos 1243: otherwise return the
1.57 wiz 1244: .Ar false_string .
1.152 dsl 1245: Since the variable name is used as the expression, \&:\&? must be the
1246: first modifier after the variable name itself - which will, of course,
1247: usually contain variable expansions.
1.162 dsl 1248: A common error is trying to use expressions like
1249: .Dl ${NUMBERS:M42:?match:no}
1250: which actually tests defined(NUMBERS),
1251: to determine is any words match "42" you need to use something like:
1.183 sjg 1252: .Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} .
1.91 lukem 1253: .It Ar :old_string=new_string
1.1 cgd 1254: This is the
1255: .At V
1256: style variable substitution.
1257: It must be the last modifier specified.
1.16 christos 1258: If
1.6 cgd 1259: .Ar old_string
1260: or
1261: .Ar new_string
1262: do not contain the pattern matching character
1263: .Ar %
1.16 christos 1264: then it is assumed that they are
1.6 cgd 1265: anchored at the end of each word, so only suffixes or entire
1.67 grant 1266: words may be replaced.
1267: Otherwise
1.6 cgd 1268: .Ar %
1.16 christos 1269: is the substring of
1270: .Ar old_string
1.6 cgd 1271: to be replaced in
1.64 wiz 1272: .Ar new_string .
1.95 jmc 1273: .Pp
1274: Variable expansion occurs in the normal fashion inside both
1275: .Ar old_string
1276: and
1277: .Ar new_string
1.96 wiz 1278: with the single exception that a backslash is used to prevent the
1279: expansion of a dollar sign
1280: .Pq Ql \&$ ,
1281: not a preceding dollar sign as is usual.
1.91 lukem 1282: .Sm off
1.164 joerg 1283: .It Cm \&:@ Ar temp Cm @ Ar string Cm @
1.91 lukem 1284: .Sm on
1.40 sjg 1285: This is the loop expansion mechanism from the OSF Development
1.67 grant 1286: Environment (ODE) make.
1287: Unlike
1.48 wiz 1288: .Cm \&.for
1.40 sjg 1289: loops expansion occurs at the time of
1.67 grant 1290: reference.
1291: Assign
1.40 sjg 1292: .Ar temp
1293: to each word in the variable and evaluate
1294: .Ar string .
1.48 wiz 1295: The ODE convention is that
1.40 sjg 1296: .Ar temp
1.67 grant 1297: should start and end with a period.
1298: For example.
1.40 sjg 1299: .Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
1.198 sjg 1300: .Pp
1301: However a single character varaiable is often more readable:
1302: .Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
1.91 lukem 1303: .It Cm \&:U Ns Ar newval
1.40 sjg 1304: If the variable is undefined
1305: .Ar newval
1.63 lukem 1306: is the value.
1307: If the variable is defined, the existing value is returned.
1.67 grant 1308: This is another ODE make feature.
1309: It is handy for setting per-target CFLAGS for instance:
1.40 sjg 1310: .Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
1.63 lukem 1311: If a value is only required if the variable is undefined, use:
1312: .Dl ${VAR:D:Unewval}
1.91 lukem 1313: .It Cm \&:D Ns Ar newval
1.40 sjg 1314: If the variable is defined
1315: .Ar newval
1316: is the value.
1.91 lukem 1317: .It Cm \&:L
1.40 sjg 1318: The name of the variable is the value.
1.91 lukem 1319: .It Cm \&:P
1.40 sjg 1320: The path of the node which has the same name as the variable
1.67 grant 1321: is the value.
1322: If no such node exists or its path is null, then the
1.40 sjg 1323: name of the variable is used.
1.199 sjg 1324: In order for this modifier to work, the name (node) must at least have
1325: appeared on the rhs of a dependency.
1.91 lukem 1326: .Sm off
1327: .It Cm \&:\&! Ar cmd Cm \&!
1328: .Sm on
1.40 sjg 1329: The output of running
1330: .Ar cmd
1331: is the value.
1.91 lukem 1332: .It Cm \&:sh
1.40 sjg 1333: If the variable is non-empty it is run as a command and the output
1334: becomes the new value.
1.91 lukem 1335: .It Cm \&::= Ns Ar str
1.48 wiz 1336: The variable is assigned the value
1.41 sjg 1337: .Ar str
1.67 grant 1338: after substitution.
1339: This modifier and its variations are useful in
1.149 dsl 1340: obscure situations such as wanting to set a variable when shell commands
1341: are being parsed.
1.67 grant 1342: These assignment modifiers always expand to
1.41 sjg 1343: nothing, so if appearing in a rule line by themselves should be
1.48 wiz 1344: preceded with something to keep
1.41 sjg 1345: .Nm
1.67 grant 1346: happy.
1.149 dsl 1347: .Pp
1.91 lukem 1348: The
1349: .Ql Cm \&::
1.42 sjg 1350: helps avoid false matches with the
1351: .At V
1.48 wiz 1352: style
1.91 lukem 1353: .Cm \&:=
1.48 wiz 1354: modifier and since substitution always occurs the
1.91 lukem 1355: .Cm \&::=
1.42 sjg 1356: form is vaguely appropriate.
1.91 lukem 1357: .It Cm \&::?= Ns Ar str
1.41 sjg 1358: As for
1.91 lukem 1359: .Cm \&::=
1.41 sjg 1360: but only if the variable does not already have a value.
1.91 lukem 1361: .It Cm \&::+= Ns Ar str
1.48 wiz 1362: Append
1.41 sjg 1363: .Ar str
1364: to the variable.
1.91 lukem 1365: .It Cm \&::!= Ns Ar cmd
1.48 wiz 1366: Assign the output of
1.41 sjg 1367: .Ar cmd
1368: to the variable.
1.91 lukem 1369: .It Cm \&:\&[ Ns Ar range Ns Cm \&]
1.89 sjg 1370: Selects one or more words from the value,
1371: or performs other operations related to the way in which the
1372: value is divided into words.
1373: .Pp
1374: Ordinarily, a value is treated as a sequence of words
1375: delimited by white space.
1376: Some modifiers suppress this behaviour,
1377: causing a value to be treated as a single word
1378: (possibly containing embedded white space).
1379: An empty value, or a value that consists entirely of white-space,
1380: is treated as a single word.
1381: For the purposes of the
1.91 lukem 1382: .Ql Cm \&:[]
1.89 sjg 1383: modifier, the words are indexed both forwards using positive integers
1384: (where index 1 represents the first word),
1385: and backwards using negative integers
1.194 sjg 1386: (where index \-1 represents the last word).
1.89 sjg 1387: .Pp
1388: The
1389: .Ar range
1390: is subjected to variable expansion, and the expanded result is
1391: then interpreted as follows:
1392: .Bl -tag -width index
1.90 jdolecek 1393: .\" :[n]
1.89 sjg 1394: .It Ar index
1395: Selects a single word from the value.
1.90 jdolecek 1396: .\" :[start..end]
1.89 sjg 1397: .It Ar start Ns Cm \&.. Ns Ar end
1398: Selects all words from
1399: .Ar start
1400: to
1401: .Ar end ,
1402: inclusive.
1403: For example,
1.91 lukem 1404: .Ql Cm \&:[2..-1]
1.89 sjg 1405: selects all words from the second word to the last word.
1406: If
1407: .Ar start
1408: is greater than
1409: .Ar end ,
1.91 lukem 1410: then the words are output in reverse order.
1411: For example,
1412: .Ql Cm \&:[-1..1]
1.89 sjg 1413: selects all the words from last to first.
1.90 jdolecek 1414: .\" :[*]
1.89 sjg 1415: .It Cm \&*
1416: Causes subsequent modifiers to treat the value as a single word
1.109 wiz 1417: (possibly containing embedded white space).
1418: Analogous to the effect of
1.94 wiz 1419: \&"$*\&"
1.89 sjg 1420: in Bourne shell.
1.90 jdolecek 1421: .\" :[0]
1.89 sjg 1422: .It 0
1423: Means the same as
1.91 lukem 1424: .Ql Cm \&:[*] .
1.90 jdolecek 1425: .\" :[*]
1.89 sjg 1426: .It Cm \&@
1427: Causes subsequent modifiers to treat the value as a sequence of words
1.109 wiz 1428: delimited by white space.
1429: Analogous to the effect of
1.94 wiz 1430: \&"$@\&"
1.89 sjg 1431: in Bourne shell.
1.90 jdolecek 1432: .\" :[#]
1.89 sjg 1433: .It Cm \&#
1434: Returns the number of words in the value.
1435: .El \" :[range]
1.6 cgd 1436: .El
1437: .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1.16 christos 1438: Makefile inclusion, conditional structures and for loops reminiscent
1.6 cgd 1439: of the C programming language are provided in
1.74 wiz 1440: .Nm .
1.1 cgd 1441: All such structures are identified by a line beginning with a single
1442: dot
1443: .Pq Ql \&.
1444: character.
1445: Files are included with either
1.29 ross 1446: .Cm \&.include Aq Ar file
1.1 cgd 1447: or
1.29 ross 1448: .Cm \&.include Pf \*q Ar file Ns \*q .
1.1 cgd 1449: Variables between the angle brackets or double quotes are expanded
1450: to form the file name.
1451: If angle brackets are used, the included makefile is expected to be in
1452: the system makefile directory.
1453: If double quotes are used, the including makefile's directory and any
1454: directories specified using the
1455: .Fl I
1456: option are searched before the system
1457: makefile directory.
1.28 christos 1458: For compatibility with other versions of
1459: .Nm
1460: .Ql include file ...
1.67 grant 1461: is also accepted.
1462: If the include statement is written as
1.29 ross 1463: .Cm .-include
1464: or as
1465: .Cm .sinclude
1.28 christos 1466: then errors locating and/or opening include files are ignored.
1.1 cgd 1467: .Pp
1468: Conditional expressions are also preceded by a single dot as the first
1.5 jtc 1469: character of a line.
1.1 cgd 1470: The possible conditionals are as follows:
1471: .Bl -tag -width Ds
1.168 sjg 1472: .It Ic .error Ar message
1473: The message is printed along with the name of the makefile and line number,
1474: then
1475: .Nm
1476: will exit.
1.165 sjg 1477: .It Ic .export Ar variable ...
1.133 sjg 1478: Export the specified global variable.
1.165 sjg 1479: If no variable list is provided, all globals are exported
1.133 sjg 1480: except for internal variables (those that start with
1.157 wiz 1481: .Ql \&. ) .
1.133 sjg 1482: This is not affected by the
1483: .Fl X
1484: flag, so should be used with caution.
1.201 christos 1485: For compatibility with other
1486: .Nm
1487: programs
1488: .Ql export variable=value
1489: is also accepted.
1.165 sjg 1490: .Pp
1.133 sjg 1491: Appending a variable name to
1492: .Va .MAKE.EXPORTED
1493: is equivalent to exporting a variable.
1.173 sjg 1494: .It Ic .export-env Ar variable ...
1.176 wiz 1495: The same as
1.173 sjg 1496: .Ql .export ,
1.176 wiz 1497: except that the variable is not appended to
1.173 sjg 1498: .Va .MAKE.EXPORTED .
1.176 wiz 1499: This allows exporting a value to the environment which is different from that
1500: used by
1.173 sjg 1501: .Nm
1502: internally.
1.168 sjg 1503: .It Ic .info Ar message
1504: The message is printed along with the name of the makefile and line number.
1.169 wiz 1505: .It Ic .undef Ar variable
1506: Un-define the specified global variable.
1507: Only global variables may be un-defined.
1.165 sjg 1508: .It Ic .unexport Ar variable ...
1509: The opposite of
1510: .Ql .export .
1511: The specified global
1.166 wiz 1512: .Va variable
1513: will be removed from
1.165 sjg 1514: .Va .MAKE.EXPORTED .
1515: If no variable list is provided, all globals are unexported,
1516: and
1.166 wiz 1517: .Va .MAKE.EXPORTED
1.165 sjg 1518: deleted.
1519: .It Ic .unexport-env
1520: Unexport all globals previously exported and
1521: clear the environment inherited from the parent.
1.166 wiz 1522: This operation will cause a memory leak of the original environment,
1523: so should be used sparingly.
1524: Testing for
1.165 sjg 1525: .Va .MAKE.LEVEL
1526: being 0, would make sense.
1.166 wiz 1527: Also note that any variables which originated in the parent environment
1.165 sjg 1528: should be explicitly preserved if desired.
1529: For example:
1530: .Bd -literal -offset indent
1531: .Li .if ${.MAKE.LEVEL} == 0
1532: PATH := ${PATH}
1533: .Li .unexport-env
1534: .Li .export PATH
1535: .Li .endif
1536: .Pp
1537: .Ed
1.166 wiz 1538: Would result in an environment containing only
1.165 sjg 1539: .Ql Ev PATH ,
1540: which is the minimal useful environment.
1541: Actually
1.166 wiz 1542: .Ql Ev .MAKE.LEVEL
1.165 sjg 1543: will also be pushed into the new environment.
1.168 sjg 1544: .It Ic .warning Ar message
1545: The message prefixed by
1546: .Ql Pa warning:
1547: is printed along with the name of the makefile and line number.
1.164 joerg 1548: .It Ic \&.if Oo \&! Oc Ns Ar expression Op Ar operator expression ...
1.1 cgd 1549: Test the value of an expression.
1.164 joerg 1550: .It Ic .ifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.7 mycroft 1551: Test the value of a variable.
1.164 joerg 1552: .It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.7 mycroft 1553: Test the value of a variable.
1.164 joerg 1554: .It Ic .ifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.7 mycroft 1555: Test the target being built.
1.164 joerg 1556: .It Ic .ifnmake Oo \&! Ns Oc Ar target Op Ar operator target ...
1.1 cgd 1557: Test the target being built.
1558: .It Ic .else
1559: Reverse the sense of the last conditional.
1.164 joerg 1560: .It Ic .elif Oo \&! Ns Oc Ar expression Op Ar operator expression ...
1.1 cgd 1561: A combination of
1562: .Ql Ic .else
1563: followed by
1564: .Ql Ic .if .
1.164 joerg 1565: .It Ic .elifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.1 cgd 1566: A combination of
1567: .Ql Ic .else
1568: followed by
1569: .Ql Ic .ifdef .
1.164 joerg 1570: .It Ic .elifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.1 cgd 1571: A combination of
1572: .Ql Ic .else
1573: followed by
1574: .Ql Ic .ifndef .
1.164 joerg 1575: .It Ic .elifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.1 cgd 1576: A combination of
1577: .Ql Ic .else
1578: followed by
1579: .Ql Ic .ifmake .
1.164 joerg 1580: .It Ic .elifnmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.1 cgd 1581: A combination of
1582: .Ql Ic .else
1583: followed by
1584: .Ql Ic .ifnmake .
1585: .It Ic .endif
1586: End the body of the conditional.
1587: .El
1588: .Pp
1589: The
1590: .Ar operator
1591: may be any one of the following:
1592: .Bl -tag -width "Cm XX"
1593: .It Cm \&|\&|
1.64 wiz 1594: Logical OR.
1.62 ross 1595: .It Cm \&\*[Am]\*[Am]
1.1 cgd 1596: Logical
1597: .Tn AND ;
1598: of higher precedence than
1.26 hubertf 1599: .Dq \&|\&| .
1.1 cgd 1600: .El
1601: .Pp
1602: As in C,
1.25 lukem 1603: .Nm
1.1 cgd 1604: will only evaluate a conditional as far as is necessary to determine
1605: its value.
1.16 christos 1606: Parentheses may be used to change the order of evaluation.
1.1 cgd 1607: The boolean operator
1608: .Ql Ic \&!
1609: may be used to logically negate an entire
1610: conditional.
1.5 jtc 1611: It is of higher precedence than
1.62 ross 1612: .Ql Ic \&\*[Am]\*[Am] .
1.1 cgd 1613: .Pp
1614: The value of
1615: .Ar expression
1616: may be any of the following:
1.61 ross 1617: .Bl -tag -width defined
1.1 cgd 1618: .It Ic defined
1619: Takes a variable name as an argument and evaluates to true if the variable
1620: has been defined.
1621: .It Ic make
1622: Takes a target name as an argument and evaluates to true if the target
1623: was specified as part of
1.74 wiz 1624: .Nm Ns 's
1.1 cgd 1625: command line or was declared the default target (either implicitly or
1626: explicitly, see
1627: .Va .MAIN )
1628: before the line containing the conditional.
1629: .It Ic empty
1.5 jtc 1630: Takes a variable, with possible modifiers, and evaluates to true if
1.1 cgd 1631: the expansion of the variable would result in an empty string.
1632: .It Ic exists
1633: Takes a file name as an argument and evaluates to true if the file exists.
1634: The file is searched for on the system search path (see
1635: .Va .PATH ) .
1636: .It Ic target
1637: Takes a target name as an argument and evaluates to true if the target
1638: has been defined.
1.47 christos 1639: .It Ic commands
1640: Takes a target name as an argument and evaluates to true if the target
1641: has been defined and has commands associated with it.
1.1 cgd 1642: .El
1643: .Pp
1644: .Ar Expression
1.67 grant 1645: may also be an arithmetic or string comparison.
1646: Variable expansion is
1.6 cgd 1647: performed on both sides of the comparison, after which the integral
1.67 grant 1648: values are compared.
1649: A value is interpreted as hexadecimal if it is
1.6 cgd 1650: preceded by 0x, otherwise it is decimal; octal numbers are not supported.
1.67 grant 1651: The standard C relational operators are all supported.
1652: If after
1.6 cgd 1653: variable expansion, either the left or right hand side of a
1.1 cgd 1654: .Ql Ic ==
1655: or
1656: .Ql Ic "!="
1.6 cgd 1657: operator is not an integral value, then
1658: string comparison is performed between the expanded
1659: variables.
1.1 cgd 1660: If no relational operator is given, it is assumed that the expanded
1.102 sjg 1661: variable is being compared against 0 or an empty string in the case
1662: of a string comparison.
1.1 cgd 1663: .Pp
1664: When
1.25 lukem 1665: .Nm
1.150 dsl 1666: is evaluating one of these conditional expressions, and it encounters
1667: a (white-space separated) word it doesn't recognize, either the
1.137 wiz 1668: .Dq make
1669: or
1670: .Dq defined
1.1 cgd 1671: expression is applied to it, depending on the form of the conditional.
1672: If the form is
1.150 dsl 1673: .Ql Ic .ifdef ,
1674: .Ql Ic .ifndef ,
1.1 cgd 1675: or
1.150 dsl 1676: .Ql Ic .if
1.137 wiz 1677: the
1678: .Dq defined
1679: expression is applied.
1.1 cgd 1680: Similarly, if the form is
1681: .Ql Ic .ifmake
1682: or
1.137 wiz 1683: .Ql Ic .ifnmake , the
1684: .Dq make
1.1 cgd 1685: expression is applied.
1686: .Pp
1687: If the conditional evaluates to true the parsing of the makefile continues
1688: as before.
1689: If it evaluates to false, the following lines are skipped.
1690: In both cases this continues until a
1691: .Ql Ic .else
1692: or
1693: .Ql Ic .endif
1694: is found.
1.16 christos 1695: .Pp
1.6 cgd 1696: For loops are typically used to apply a set of rules to a list of files.
1697: The syntax of a for loop is:
1.59 bgrayson 1698: .Pp
1699: .Bl -tag -compact -width Ds
1.164 joerg 1700: .It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression
1.80 wiz 1701: .It Aq make-rules
1702: .It Ic \&.endfor
1.6 cgd 1703: .El
1.59 bgrayson 1704: .Pp
1.6 cgd 1705: After the for
1.16 christos 1706: .Ic expression
1.67 grant 1707: is evaluated, it is split into words.
1708: On each iteration of the loop, one word is taken and assigned to each
1.39 christos 1709: .Ic variable ,
1710: in order, and these
1711: .Ic variables
1712: are substituted into the
1.16 christos 1713: .Ic make-rules
1.6 cgd 1714: inside the body of the for loop.
1.39 christos 1715: The number of words must come out even; that is, if there are three
1716: iteration variables, the number of words provided must be a multiple
1717: of three.
1.1 cgd 1718: .Sh COMMENTS
1719: Comments begin with a hash
1720: .Pq Ql \&#
1721: character, anywhere but in a shell
1.114 wiz 1722: command line, and continue to the end of an unescaped new line.
1.97 lukem 1723: .Sh SPECIAL SOURCES (ATTRIBUTES)
1.61 ross 1724: .Bl -tag -width .IGNOREx
1.97 lukem 1725: .It Ic .EXEC
1726: Target is never out of date, but always execute commands anyway.
1.1 cgd 1727: .It Ic .IGNORE
1728: Ignore any errors from the commands associated with this target, exactly
1729: as if they all were preceded by a dash
1730: .Pq Ql \- .
1.97 lukem 1731: .\" .It Ic .INVISIBLE
1732: .\" XXX
1733: .\" .It Ic .JOIN
1734: .\" XXX
1.18 christos 1735: .It Ic .MADE
1.48 wiz 1736: Mark all sources of this target as being up-to-date.
1.1 cgd 1737: .It Ic .MAKE
1738: Execute the commands associated with this target even if the
1739: .Fl n
1740: or
1741: .Fl t
1742: options were specified.
1743: Normally used to mark recursive
1.74 wiz 1744: .Nm Ns 's .
1.180 sjg 1745: .It Ic .META
1746: Create a meta file for the target, even if it is flagged as
1747: .Ic .PHONY ,
1.182 wiz 1748: .Ic .MAKE ,
1.180 sjg 1749: or
1750: .Ic .SPECIAL .
1751: Usage in conjunction with
1752: .Ic .MAKE
1753: is the most likely case.
1.194 sjg 1754: In "meta" mode, the target is out-of-date if the meta file is missing.
1.180 sjg 1755: .It Ic .NOMETA
1756: Do not create a meta file for the target.
1757: Meta files are also not created for
1758: .Ic .PHONY ,
1.182 wiz 1759: .Ic .MAKE ,
1.180 sjg 1760: or
1761: .Ic .SPECIAL
1762: targets.
1763: .It Ic .NOMETA_CMP
1764: Ignore differences in commands when deciding if target is out of date.
1765: This is useful if the command contains a value which always changes.
1.182 wiz 1766: If the number of commands change, though, the target will still be out of date.
1.213 sjg 1767: The same effect applies to any command line that uses the variable
1768: .Va .OODATE ,
1769: which can be used for that purpose even when not otherwise needed or desired:
1770: .Bd -literal -offset indent
1771:
1772: skip-compare-for-some:
1773: @echo this will be compared
1774: @echo this will not ${.OODATE:M.NOMETA_CMP}
1775: @echo this will also be compared
1776:
1777: .Ed
1778: The
1779: .Cm \&:M
1780: pattern suppresses any expansion of the unwanted variable.
1.97 lukem 1781: .It Ic .NOPATH
1782: Do not search for the target in the directories specified by
1783: .Ic .PATH .
1.1 cgd 1784: .It Ic .NOTMAIN
1785: Normally
1.25 lukem 1786: .Nm
1.1 cgd 1787: selects the first target it encounters as the default target to be built
1788: if no target was specified.
1789: This source prevents this target from being selected.
1790: .It Ic .OPTIONAL
1791: If a target is marked with this attribute and
1.25 lukem 1792: .Nm
1.1 cgd 1793: can't figure out how to create it, it will ignore this fact and assume
1794: the file isn't needed or already exists.
1.97 lukem 1795: .It Ic .PHONY
1796: The target does not
1797: correspond to an actual file; it is always considered to be out of date,
1798: and will not be created with the
1799: .Fl t
1800: option.
1.179 dholland 1801: Suffix-transformation rules are not applied to
1802: .Ic .PHONY
1803: targets.
1.1 cgd 1804: .It Ic .PRECIOUS
1805: When
1.25 lukem 1806: .Nm
1.131 rillig 1807: is interrupted, it normally removes any partially made targets.
1.1 cgd 1808: This source prevents the target from being removed.
1.97 lukem 1809: .It Ic .RECURSIVE
1810: Synonym for
1811: .Ic .MAKE .
1.1 cgd 1812: .It Ic .SILENT
1813: Do not echo any of the commands associated with this target, exactly
1814: as if they all were preceded by an at sign
1815: .Pq Ql @ .
1816: .It Ic .USE
1817: Turn the target into
1.74 wiz 1818: .Nm Ns 's
1.1 cgd 1819: version of a macro.
1820: When the target is used as a source for another target, the other target
1821: acquires the commands, sources, and attributes (except for
1822: .Ic .USE )
1823: of the
1824: source.
1825: If the target already has commands, the
1826: .Ic .USE
1827: target's commands are appended
1828: to them.
1.52 christos 1829: .It Ic .USEBEFORE
1830: Exactly like
1831: .Ic .USE ,
1.57 wiz 1832: but prepend the
1.52 christos 1833: .Ic .USEBEFORE
1834: target commands to the target.
1.12 christos 1835: .It Ic .WAIT
1.71 mjl 1836: If
1.12 christos 1837: .Ic .WAIT
1.71 mjl 1838: appears in a dependency line, the sources that precede it are
1.67 grant 1839: made before the sources that succeed it in the line.
1.128 dsl 1840: Since the dependents of files are not made until the file itself
1841: could be made, this also stops the dependents being built unless they
1842: are needed for another branch of the dependency tree.
1843: So given:
1844: .Bd -literal
1845: x: a .WAIT b
1846: echo x
1847: a:
1848: echo a
1849: b: b1
1850: echo b
1851: b1:
1852: echo b1
1853:
1854: .Ed
1855: the output is always
1.151 dholland 1856: .Ql a ,
1.128 dsl 1857: .Ql b1 ,
1858: .Ql b ,
1859: .Ql x .
1860: .br
1.122 apb 1861: The ordering imposed by
1862: .Ic .WAIT
1.128 dsl 1863: is only relevant for parallel makes.
1.1 cgd 1864: .El
1.57 wiz 1865: .Sh SPECIAL TARGETS
1.1 cgd 1866: Special targets may not be included with other targets, i.e. they must be
1867: the only target specified.
1.61 ross 1868: .Bl -tag -width .BEGINx
1.1 cgd 1869: .It Ic .BEGIN
1870: Any command lines attached to this target are executed before anything
1871: else is done.
1872: .It Ic .DEFAULT
1873: This is sort of a
1874: .Ic .USE
1875: rule for any target (that was used only as a
1876: source) that
1.25 lukem 1877: .Nm
1.1 cgd 1878: can't figure out any other way to create.
1879: Only the shell script is used.
1880: The
1881: .Ic .IMPSRC
1882: variable of a target that inherits
1883: .Ic .DEFAULT Ns 's
1884: commands is set
1885: to the target's own name.
1886: .It Ic .END
1887: Any command lines attached to this target are executed after everything
1888: else is done.
1.168 sjg 1889: .It Ic .ERROR
1890: Any command lines attached to this target are executed when another target fails.
1891: The
1892: .Ic .ERROR_TARGET
1893: variable is set to the target that failed.
1.169 wiz 1894: See also
1.168 sjg 1895: .Ic MAKE_PRINT_VAR_ON_ERROR .
1.1 cgd 1896: .It Ic .IGNORE
1897: Mark each of the sources with the
1898: .Ic .IGNORE
1899: attribute.
1900: If no sources are specified, this is the equivalent of specifying the
1901: .Fl i
1902: option.
1903: .It Ic .INTERRUPT
1904: If
1.25 lukem 1905: .Nm
1.1 cgd 1906: is interrupted, the commands for this target will be executed.
1907: .It Ic .MAIN
1908: If no target is specified when
1.25 lukem 1909: .Nm
1.1 cgd 1910: is invoked, this target will be built.
1911: .It Ic .MAKEFLAGS
1912: This target provides a way to specify flags for
1.25 lukem 1913: .Nm
1.1 cgd 1914: when the makefile is used.
1915: The flags are as if typed to the shell, though the
1916: .Fl f
1917: option will have
1918: no effect.
1.12 christos 1919: .\" XXX: NOT YET!!!!
1920: .\" .It Ic .NOTPARALLEL
1.70 wiz 1921: .\" The named targets are executed in non parallel mode.
1922: .\" If no targets are
1.12 christos 1923: .\" specified, then all targets are executed in non parallel mode.
1.20 gwr 1924: .It Ic .NOPATH
1925: Apply the
1926: .Ic .NOPATH
1.67 grant 1927: attribute to any specified sources.
1.12 christos 1928: .It Ic .NOTPARALLEL
1929: Disable parallel mode.
1930: .It Ic .NO_PARALLEL
1.97 lukem 1931: Synonym for
1932: .Ic .NOTPARALLEL ,
1933: for compatibility with other pmake variants.
1.12 christos 1934: .It Ic .ORDER
1935: The named targets are made in sequence.
1.128 dsl 1936: This ordering does not add targets to the list of targets to be made.
1937: Since the dependents of a target do not get built until the target itself
1938: could be built, unless
1939: .Ql a
1.129 wiz 1940: is built by another part of the dependency graph,
1.128 dsl 1941: the following is a dependency loop:
1942: .Bd -literal
1.192 cheusov 1943: \&.ORDER: b a
1.128 dsl 1944: b: a
1945: .Ed
1.129 wiz 1946: .Pp
1.122 apb 1947: The ordering imposed by
1948: .Ic .ORDER
1.128 dsl 1949: is only relevant for parallel makes.
1.12 christos 1950: .\" XXX: NOT YET!!!!
1951: .\" .It Ic .PARALLEL
1.70 wiz 1952: .\" The named targets are executed in parallel mode.
1953: .\" If no targets are
1.12 christos 1954: .\" specified, then all targets are executed in parallel mode.
1.1 cgd 1955: .It Ic .PATH
1956: The sources are directories which are to be searched for files not
1957: found in the current directory.
1958: If no sources are specified, any previously specified directories are
1959: deleted.
1.34 thorpej 1960: If the source is the special
1961: .Ic .DOTLAST
1962: target, then the current working
1.33 thorpej 1963: directory is searched last.
1.14 christos 1964: .It Ic .PHONY
1965: Apply the
1966: .Ic .PHONY
1.67 grant 1967: attribute to any specified sources.
1.1 cgd 1968: .It Ic .PRECIOUS
1969: Apply the
1970: .Ic .PRECIOUS
1971: attribute to any specified sources.
1972: If no sources are specified, the
1973: .Ic .PRECIOUS
1974: attribute is applied to every
1975: target in the file.
1.83 sjg 1976: .It Ic .SHELL
1.86 wiz 1977: Sets the shell that
1.83 sjg 1978: .Nm
1.86 wiz 1979: will use to execute commands.
1980: The sources are a set of
1.83 sjg 1981: .Ar field=value
1.86 wiz 1982: pairs.
1.83 sjg 1983: .Bl -tag -width hasErrCtls
1984: .It Ar name
1985: This is the minimal specification, used to select one of the builtin
1986: shell specs;
1987: .Ar sh ,
1988: .Ar ksh ,
1989: and
1990: .Ar csh .
1991: .It Ar path
1992: Specifies the path to the shell.
1993: .It Ar hasErrCtl
1994: Indicates whether the shell supports exit on error.
1995: .It Ar check
1996: The command to turn on error checking.
1997: .It Ar ignore
1998: The command to disable error checking.
1999: .It Ar echo
2000: The command to turn on echoing of commands executed.
2001: .It Ar quiet
2002: The command to turn off echoing of commands executed.
2003: .It Ar filter
2004: The output to filter after issuing the
2005: .Ar quiet
1.86 wiz 2006: command.
2007: It is typically identical to
1.83 sjg 2008: .Ar quiet .
2009: .It Ar errFlag
2010: The flag to pass the shell to enable error checking.
2011: .It Ar echoFlag
2012: The flag to pass the shell to enable command echoing.
1.127 rillig 2013: .It Ar newline
2014: The string literal to pass the shell that results in a single newline
2015: character when used outside of any quoting characters.
1.83 sjg 2016: .El
2017: Example:
2018: .Bd -literal
1.167 joerg 2019: \&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e
1.194 sjg 2020: check="set \-e" ignore="set +e" \e
2021: echo="set \-v" quiet="set +v" filter="set +v" \e
1.167 joerg 2022: echoFlag=v errFlag=e newline="'\en'"
1.83 sjg 2023: .Ed
1.1 cgd 2024: .It Ic .SILENT
2025: Apply the
2026: .Ic .SILENT
2027: attribute to any specified sources.
2028: If no sources are specified, the
2029: .Ic .SILENT
2030: attribute is applied to every
2031: command in the file.
1.211 christos 2032: .It Ic .STALE
2033: This target gets run when a dependency file contains stale entries, having
2034: .Va .ALLSRC
2035: set to the name of that dependency file.
1.1 cgd 2036: .It Ic .SUFFIXES
2037: Each source specifies a suffix to
1.74 wiz 2038: .Nm .
1.71 mjl 2039: If no sources are specified, any previously specified suffixes are deleted.
1.136 cube 2040: It allows the creation of suffix-transformation rules.
2041: .Pp
2042: Example:
2043: .Bd -literal
2044: \&.SUFFIXES: .o
2045: \&.c.o:
1.194 sjg 2046: cc \-o ${.TARGET} \-c ${.IMPSRC}
1.136 cube 2047: .Ed
1.31 ross 2048: .El
1.1 cgd 2049: .Sh ENVIRONMENT
1.25 lukem 2050: .Nm
1.73 perry 2051: uses the following environment variables, if they exist:
1.16 christos 2052: .Ev MACHINE ,
1.26 hubertf 2053: .Ev MACHINE_ARCH ,
1.1 cgd 2054: .Ev MAKE ,
1.16 christos 2055: .Ev MAKEFLAGS ,
2056: .Ev MAKEOBJDIR ,
1.38 sjg 2057: .Ev MAKEOBJDIRPREFIX ,
1.76 jrf 2058: .Ev MAKESYSPATH ,
1.154 apb 2059: .Ev PWD ,
1.1 cgd 2060: and
1.154 apb 2061: .Ev TMPDIR .
1.57 wiz 2062: .Pp
1.38 sjg 2063: .Ev MAKEOBJDIRPREFIX
1.117 lukem 2064: and
1.38 sjg 2065: .Ev MAKEOBJDIR
1.117 lukem 2066: may only be set in the environment or on the command line to
1.38 sjg 2067: .Nm
1.117 lukem 2068: and not as makefile variables;
2069: see the description of
2070: .Ql Va .OBJDIR
2071: for more details.
1.1 cgd 2072: .Sh FILES
2073: .Bl -tag -width /usr/share/mk -compact
2074: .It .depend
2075: list of dependencies
2076: .It Makefile
2077: list of dependencies
2078: .It makefile
2079: list of dependencies
2080: .It sys.mk
2081: system makefile
2082: .It /usr/share/mk
2083: system makefile directory
2084: .El
1.128 dsl 2085: .Sh COMPATIBILITY
2086: The basic make syntax is compatible between different versions of make,
2087: however the special variables, variable modifiers and conditionals are not.
2088: .Pp
1.129 wiz 2089: The way that parallel makes are scheduled changed in
1.130 wiz 2090: .Nx 4.0
1.193 wiz 2091: so that .ORDER and .WAIT apply recursively to the dependent nodes.
1.128 dsl 2092: The algorithms used may change again in the future.
1.152 dsl 2093: .Pp
2094: The way that .for loop variables are substituted changed after
2095: .Nx 5.0
2096: so that they still appear to be variable expansions.
2097: In particular this stops them being treated as syntax, and removes some
2098: obscure problems using them in .if statements.
1.153 wiz 2099: .Sh SEE ALSO
2100: .Xr mkdep 1
2101: .Sh HISTORY
2102: A
2103: .Nm
2104: command appeared in
2105: .At v7 .
1.190 christos 2106: This
2107: .Nm
2108: implementation is based on Adam De Boor's pmake program which was written
1.209 christos 2109: for Sprite at Berkeley.
1.190 christos 2110: It was designed to be a parallel distributed make running jobs on different
1.191 wiz 2111: machines using a daemon called
1.190 christos 2112: .Dq customs .
1.214 ! christos 2113: .Pp
! 2114: Historically the target/dependency
! 2115: .Dq FRC
! 2116: has been used historically to FoRCe rebuilding (since the target/dependency
! 2117: does not exist... unless someone creates an
! 2118: .Dq FRC
! 2119: file.
1.152 dsl 2120: .Sh BUGS
2121: The
2122: .Nm
2123: syntax is difficult to parse without actually acting of the data.
2124: For instance finding the end of a variable use should involve scanning each
2125: the modifiers using the correct terminator for each field.
2126: In many places
2127: .Nm
2128: just counts {} and () in order to find the end of a variable expansion.
2129: .Pp
1.153 wiz 2130: There is no way of escaping a space character in a filename.
CVSweb <webmaster@jp.NetBSD.org>