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