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