Fri Jan 10 16:28:34 2014 UTC ()
Bump date for previous.


(wiz)
diff -r1.227 -r1.228 src/usr.bin/make/make.1

cvs diff -r1.227 -r1.228 src/usr.bin/make/make.1 (switch to unified diff)

--- src/usr.bin/make/make.1 2014/01/10 16:12:52 1.227
+++ src/usr.bin/make/make.1 2014/01/10 16:28:34 1.228
@@ -1,1031 +1,1031 @@ @@ -1,1031 +1,1031 @@
1.\" $NetBSD: make.1,v 1.227 2014/01/10 16:12:52 christos Exp $ 1.\" $NetBSD: make.1,v 1.228 2014/01/10 16:28:34 wiz Exp $
2.\" 2.\"
3.\" Copyright (c) 1990, 1993 3.\" Copyright (c) 1990, 1993
4.\" The Regents of the University of California. All rights reserved. 4.\" The Regents of the University of California. All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors 14.\" 3. Neither the name of the University nor the names of its contributors
15.\" may be used to endorse or promote products derived from this software 15.\" may be used to endorse or promote products derived from this software
16.\" without specific prior written permission. 16.\" without specific prior written permission.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 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 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 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 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 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 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE. 28.\" SUCH DAMAGE.
29.\" 29.\"
30.\" from: @(#)make.1 8.4 (Berkeley) 3/19/94 30.\" from: @(#)make.1 8.4 (Berkeley) 3/19/94
31.\" 31.\"
32.Dd October 25, 2013 32.Dd January 10, 2014
33.Dt MAKE 1 33.Dt MAKE 1
34.Os 34.Os
35.Sh NAME 35.Sh NAME
36.Nm make 36.Nm make
37.Nd maintain program dependencies 37.Nd maintain program dependencies
38.Sh SYNOPSIS 38.Sh SYNOPSIS
39.Nm 39.Nm
40.Op Fl BeikNnqrstWwX 40.Op Fl BeikNnqrstWwX
41.Op Fl C Ar directory 41.Op Fl C Ar directory
42.Op Fl D Ar variable 42.Op Fl D Ar variable
43.Op Fl d Ar flags 43.Op Fl d Ar flags
44.Op Fl f Ar makefile 44.Op Fl f Ar makefile
45.Op Fl I Ar directory 45.Op Fl I Ar directory
46.Op Fl J Ar private 46.Op Fl J Ar private
47.Op Fl j Ar max_jobs 47.Op Fl j Ar max_jobs
48.Op Fl m Ar directory 48.Op Fl m Ar directory
49.Op Fl T Ar file 49.Op Fl T Ar file
50.Op Fl V Ar variable 50.Op Fl V Ar variable
51.Op Ar variable=value 51.Op Ar variable=value
52.Op Ar target ... 52.Op Ar target ...
53.Sh DESCRIPTION 53.Sh DESCRIPTION
54.Nm 54.Nm
55is a program designed to simplify the maintenance of other programs. 55is a program designed to simplify the maintenance of other programs.
56Its input is a list of specifications as to the files upon which programs 56Its input is a list of specifications as to the files upon which programs
57and other files depend. 57and other files depend.
58If no 58If no
59.Fl f Ar makefile 59.Fl f Ar makefile
60makefile option is given, 60makefile option is given,
61.Nm 61.Nm
62will try to open 62will try to open
63.Ql Pa makefile 63.Ql Pa makefile
64then 64then
65.Ql Pa Makefile 65.Ql Pa Makefile
66in order to find the specifications. 66in order to find the specifications.
67If the file 67If the file
68.Ql Pa .depend 68.Ql Pa .depend
69exists, it is read (see 69exists, it is read (see
70.Xr mkdep 1 ) . 70.Xr mkdep 1 ) .
71.Pp 71.Pp
72This manual page is intended as a reference document only. 72This manual page is intended as a reference document only.
73For a more thorough description of 73For a more thorough description of
74.Nm 74.Nm
75and makefiles, please refer to 75and makefiles, please refer to
76.%T "PMake \- A Tutorial" . 76.%T "PMake \- A Tutorial" .
77.Pp 77.Pp
78.Nm 78.Nm
79will prepend the contents of the 79will prepend the contents of the
80.Va MAKEFLAGS 80.Va MAKEFLAGS
81environment variable to the command line arguments before parsing them. 81environment variable to the command line arguments before parsing them.
82.Pp 82.Pp
83The options are as follows: 83The options are as follows:
84.Bl -tag -width Ds 84.Bl -tag -width Ds
85.It Fl B 85.It Fl B
86Try to be backwards compatible by executing a single shell per command and 86Try to be backwards compatible by executing a single shell per command and
87by executing the commands to make the sources of a dependency line in sequence. 87by executing the commands to make the sources of a dependency line in sequence.
88.It Fl C Ar directory 88.It Fl C Ar directory
89Change to 89Change to
90.Ar directory 90.Ar directory
91before reading the makefiles or doing anything else. 91before reading the makefiles or doing anything else.
92If multiple 92If multiple
93.Fl C 93.Fl C
94options are specified, each is interpreted relative to the previous one: 94options are specified, each is interpreted relative to the previous one:
95.Fl C Pa / Fl C Pa etc 95.Fl C Pa / Fl C Pa etc
96is equivalent to 96is equivalent to
97.Fl C Pa /etc . 97.Fl C Pa /etc .
98.It Fl D Ar variable 98.It Fl D Ar variable
99Define 99Define
100.Ar variable 100.Ar variable
101to be 1, in the global context. 101to be 1, in the global context.
102.It Fl d Ar [-]flags 102.It Fl d Ar [-]flags
103Turn on debugging, and specify which portions of 103Turn on debugging, and specify which portions of
104.Nm 104.Nm
105are to print debugging information. 105are to print debugging information.
106Unless the flags are preceded by 106Unless the flags are preceded by
107.Ql \- 107.Ql \-
108they are added to the 108they are added to the
109.Va MAKEFLAGS 109.Va MAKEFLAGS
110environment variable and will be processed by any child make processes. 110environment variable and will be processed by any child make processes.
111By default, debugging information is printed to standard error, 111By default, debugging information is printed to standard error,
112but this can be changed using the 112but this can be changed using the
113.Ar F 113.Ar F
114debugging flag. 114debugging flag.
115The debugging output is always unbuffered; in addition, if debugging 115The debugging output is always unbuffered; in addition, if debugging
116is enabled but debugging output is not directed to standard output, 116is enabled but debugging output is not directed to standard output,
117then the standard output is line buffered. 117then the standard output is line buffered.
118.Ar Flags 118.Ar Flags
119is one or more of the following: 119is one or more of the following:
120.Bl -tag -width Ds 120.Bl -tag -width Ds
121.It Ar A 121.It Ar A
122Print all possible debugging information; 122Print all possible debugging information;
123equivalent to specifying all of the debugging flags. 123equivalent to specifying all of the debugging flags.
124.It Ar a 124.It Ar a
125Print debugging information about archive searching and caching. 125Print debugging information about archive searching and caching.
126.It Ar C 126.It Ar C
127Print debugging information about current working directory. 127Print debugging information about current working directory.
128.It Ar c 128.It Ar c
129Print debugging information about conditional evaluation. 129Print debugging information about conditional evaluation.
130.It Ar d 130.It Ar d
131Print debugging information about directory searching and caching. 131Print debugging information about directory searching and caching.
132.It Ar e 132.It Ar e
133Print debugging information about failed commands and targets. 133Print debugging information about failed commands and targets.
134.It Ar F Ns Oo Sy \&+ Oc Ns Ar filename 134.It Ar F Ns Oo Sy \&+ Oc Ns Ar filename
135Specify where debugging output is written. 135Specify where debugging output is written.
136This must be the last flag, because it consumes the remainder of 136This must be the last flag, because it consumes the remainder of
137the argument. 137the argument.
138If the character immediately after the 138If the character immediately after the
139.Ql F 139.Ql F
140flag is 140flag is
141.Ql \&+ , 141.Ql \&+ ,
142then the file will be opened in append mode; 142then the file will be opened in append mode;
143otherwise the file will be overwritten. 143otherwise the file will be overwritten.
144If the file name is 144If the file name is
145.Ql stdout 145.Ql stdout
146or 146or
147.Ql stderr 147.Ql stderr
148then debugging output will be written to the 148then debugging output will be written to the
149standard output or standard error output file descriptors respectively 149standard output or standard error output file descriptors respectively
150(and the 150(and the
151.Ql \&+ 151.Ql \&+
152option has no effect). 152option has no effect).
153Otherwise, the output will be written to the named file. 153Otherwise, the output will be written to the named file.
154If the file name ends 154If the file name ends
155.Ql .%d 155.Ql .%d
156then the 156then the
157.Ql %d 157.Ql %d
158is replaced by the pid. 158is replaced by the pid.
159.It Ar f 159.It Ar f
160Print debugging information about loop evaluation. 160Print debugging information about loop evaluation.
161.It Ar "g1" 161.It Ar "g1"
162Print the input graph before making anything. 162Print the input graph before making anything.
163.It Ar "g2" 163.It Ar "g2"
164Print the input graph after making everything, or before exiting 164Print the input graph after making everything, or before exiting
165on error. 165on error.
166.It Ar "g3" 166.It Ar "g3"
167Print the input graph before exiting on error. 167Print the input graph before exiting on error.
168.It Ar j 168.It Ar j
169Print debugging information about running multiple shells. 169Print debugging information about running multiple shells.
170.It Ar l 170.It Ar l
171Print commands in Makefiles regardless of whether or not they are prefixed by 171Print commands in Makefiles regardless of whether or not they are prefixed by
172.Ql @ 172.Ql @
173or other "quiet" flags. 173or other "quiet" flags.
174Also known as "loud" behavior. 174Also known as "loud" behavior.
175.It Ar M 175.It Ar M
176Print debugging information about "meta" mode decisions about targets. 176Print debugging information about "meta" mode decisions about targets.
177.It Ar m 177.It Ar m
178Print debugging information about making targets, including modification 178Print debugging information about making targets, including modification
179dates. 179dates.
180.It Ar n 180.It Ar n
181Don't delete the temporary command scripts created when running commands. 181Don't delete the temporary command scripts created when running commands.
182These temporary scripts are created in the directory 182These temporary scripts are created in the directory
183referred to by the 183referred to by the
184.Ev TMPDIR 184.Ev TMPDIR
185environment variable, or in 185environment variable, or in
186.Pa /tmp 186.Pa /tmp
187if 187if
188.Ev TMPDIR 188.Ev TMPDIR
189is unset or set to the empty string. 189is unset or set to the empty string.
190The temporary scripts are created by 190The temporary scripts are created by
191.Xr mkstemp 3 , 191.Xr mkstemp 3 ,
192and have names of the form 192and have names of the form
193.Pa makeXXXXXX . 193.Pa makeXXXXXX .
194.Em NOTE : 194.Em NOTE :
195This can create many files in 195This can create many files in
196.Ev TMPDIR 196.Ev TMPDIR
197or 197or
198.Pa /tmp , 198.Pa /tmp ,
199so use with care. 199so use with care.
200.It Ar p 200.It Ar p
201Print debugging information about makefile parsing. 201Print debugging information about makefile parsing.
202.It Ar s 202.It Ar s
203Print debugging information about suffix-transformation rules. 203Print debugging information about suffix-transformation rules.
204.It Ar t 204.It Ar t
205Print debugging information about target list maintenance. 205Print debugging information about target list maintenance.
206.It Ar V 206.It Ar V
207Force the 207Force the
208.Fl V 208.Fl V
209option to print raw values of variables. 209option to print raw values of variables.
210.It Ar v 210.It Ar v
211Print debugging information about variable assignment. 211Print debugging information about variable assignment.
212.It Ar w 212.It Ar w
213Print entering and leaving directory messages, pre and post processing. 213Print entering and leaving directory messages, pre and post processing.
214.It Ar x 214.It Ar x
215Run shell commands with 215Run shell commands with
216.Fl x 216.Fl x
217so the actual commands are printed as they are executed. 217so the actual commands are printed as they are executed.
218.El 218.El
219.It Fl e 219.It Fl e
220Specify that environment variables override macro assignments within 220Specify that environment variables override macro assignments within
221makefiles. 221makefiles.
222.It Fl f Ar makefile 222.It Fl f Ar makefile
223Specify a makefile to read instead of the default 223Specify a makefile to read instead of the default
224.Ql Pa makefile . 224.Ql Pa makefile .
225If 225If
226.Ar makefile 226.Ar makefile
227is 227is
228.Ql Fl , 228.Ql Fl ,
229standard input is read. 229standard input is read.
230Multiple makefiles may be specified, and are read in the order specified. 230Multiple makefiles may be specified, and are read in the order specified.
231.It Fl I Ar directory 231.It Fl I Ar directory
232Specify a directory in which to search for makefiles and included makefiles. 232Specify a directory in which to search for makefiles and included makefiles.
233The system makefile directory (or directories, see the 233The system makefile directory (or directories, see the
234.Fl m 234.Fl m
235option) is automatically included as part of this list. 235option) is automatically included as part of this list.
236.It Fl i 236.It Fl i
237Ignore non-zero exit of shell commands in the makefile. 237Ignore non-zero exit of shell commands in the makefile.
238Equivalent to specifying 238Equivalent to specifying
239.Ql Fl 239.Ql Fl
240before each command line in the makefile. 240before each command line in the makefile.
241.It Fl J Ar private 241.It Fl J Ar private
242This option should 242This option should
243.Em not 243.Em not
244be specified by the user. 244be specified by the user.
245.Pp 245.Pp
246When the 246When the
247.Ar j 247.Ar j
248option is in use in a recursive build, this option is passed by a make 248option is in use in a recursive build, this option is passed by a make
249to child makes to allow all the make processes in the build to 249to child makes to allow all the make processes in the build to
250cooperate to avoid overloading the system. 250cooperate to avoid overloading the system.
251.It Fl j Ar max_jobs 251.It Fl j Ar max_jobs
252Specify the maximum number of jobs that 252Specify the maximum number of jobs that
253.Nm 253.Nm
254may have running at any one time. 254may have running at any one time.
255The value is saved in 255The value is saved in
256.Va .MAKE.JOBS . 256.Va .MAKE.JOBS .
257Turns compatibility mode off, unless the 257Turns compatibility mode off, unless the
258.Ar B 258.Ar B
259flag is also specified. 259flag is also specified.
260When compatibility mode is off, all commands associated with a 260When compatibility mode is off, all commands associated with a
261target are executed in a single shell invocation as opposed to the 261target are executed in a single shell invocation as opposed to the
262traditional one shell invocation per line. 262traditional one shell invocation per line.
263This can break traditional scripts which change directories on each 263This can break traditional scripts which change directories on each
264command invocation and then expect to start with a fresh environment 264command invocation and then expect to start with a fresh environment
265on the next line. 265on the next line.
266It is more efficient to correct the scripts rather than turn backwards 266It is more efficient to correct the scripts rather than turn backwards
267compatibility on. 267compatibility on.
268.It Fl k 268.It Fl k
269Continue processing after errors are encountered, but only on those targets 269Continue processing after errors are encountered, but only on those targets
270that do not depend on the target whose creation caused the error. 270that do not depend on the target whose creation caused the error.
271.It Fl m Ar directory 271.It Fl m Ar directory
272Specify a directory in which to search for sys.mk and makefiles included 272Specify a directory in which to search for sys.mk and makefiles included
273via the 273via the
274.Ao Ar file Ac Ns -style 274.Ao Ar file Ac Ns -style
275include statement. 275include statement.
276The 276The
277.Fl m 277.Fl m
278option can be used multiple times to form a search path. 278option can be used multiple times to form a search path.
279This path will override the default system include path: /usr/share/mk. 279This path will override the default system include path: /usr/share/mk.
280Furthermore the system include path will be appended to the search path used 280Furthermore the system include path will be appended to the search path used
281for 281for
282.Qo Ar file Qc Ns -style 282.Qo Ar file Qc Ns -style
283include statements (see the 283include statements (see the
284.Fl I 284.Fl I
285option). 285option).
286.Pp 286.Pp
287If a file or directory name in the 287If a file or directory name in the
288.Fl m 288.Fl m
289argument (or the 289argument (or the
290.Ev MAKESYSPATH 290.Ev MAKESYSPATH
291environment variable) starts with the string 291environment variable) starts with the string
292.Qq \&.../ 292.Qq \&.../
293then 293then
294.Nm 294.Nm
295will search for the specified file or directory named in the remaining part 295will search for the specified file or directory named in the remaining part
296of the argument string. 296of the argument string.
297The search starts with the current directory of 297The search starts with the current directory of
298the Makefile and then works upward towards the root of the filesystem. 298the Makefile and then works upward towards the root of the filesystem.
299If the search is successful, then the resulting directory replaces the 299If the search is successful, then the resulting directory replaces the
300.Qq \&.../ 300.Qq \&.../
301specification in the 301specification in the
302.Fl m 302.Fl m
303argument. 303argument.
304If used, this feature allows 304If used, this feature allows
305.Nm 305.Nm
306to easily search in the current source tree for customized sys.mk files 306to easily search in the current source tree for customized sys.mk files
307(e.g., by using 307(e.g., by using
308.Qq \&.../mk/sys.mk 308.Qq \&.../mk/sys.mk
309as an argument). 309as an argument).
310.It Fl n 310.It Fl n
311Display the commands that would have been executed, but do not 311Display the commands that would have been executed, but do not
312actually execute them unless the target depends on the .MAKE special 312actually execute them unless the target depends on the .MAKE special
313source (see below). 313source (see below).
314.It Fl N 314.It Fl N
315Display the commands which would have been executed, but do not 315Display the commands which would have been executed, but do not
316actually execute any of them; useful for debugging top-level makefiles 316actually execute any of them; useful for debugging top-level makefiles
317without descending into subdirectories. 317without descending into subdirectories.
318.It Fl q 318.It Fl q
319Do not execute any commands, but exit 0 if the specified targets are 319Do not execute any commands, but exit 0 if the specified targets are
320up-to-date and 1, otherwise. 320up-to-date and 1, otherwise.
321.It Fl r 321.It Fl r
322Do not use the built-in rules specified in the system makefile. 322Do not use the built-in rules specified in the system makefile.
323.It Fl s 323.It Fl s
324Do not echo any commands as they are executed. 324Do not echo any commands as they are executed.
325Equivalent to specifying 325Equivalent to specifying
326.Ql Ic @ 326.Ql Ic @
327before each command line in the makefile. 327before each command line in the makefile.
328.It Fl T Ar tracefile 328.It Fl T Ar tracefile
329When used with the 329When used with the
330.Fl j 330.Fl j
331flag, 331flag,
332append a trace record to 332append a trace record to
333.Ar tracefile 333.Ar tracefile
334for each job started and completed. 334for each job started and completed.
335.It Fl t 335.It Fl t
336Rather than re-building a target as specified in the makefile, create it 336Rather than re-building a target as specified in the makefile, create it
337or update its modification time to make it appear up-to-date. 337or update its modification time to make it appear up-to-date.
338.It Fl V Ar variable 338.It Fl V Ar variable
339Print 339Print
340.Nm Ns 's 340.Nm Ns 's
341idea of the value of 341idea of the value of
342.Ar variable , 342.Ar variable ,
343in the global context. 343in the global context.
344Do not build any targets. 344Do not build any targets.
345Multiple instances of this option may be specified; 345Multiple instances of this option may be specified;
346the variables will be printed one per line, 346the variables will be printed one per line,
347with a blank line for each null or undefined variable. 347with a blank line for each null or undefined variable.
348If 348If
349.Ar variable 349.Ar variable
350contains a 350contains a
351.Ql \&$ 351.Ql \&$
352then the value will be expanded before printing. 352then the value will be expanded before printing.
353.It Fl W 353.It Fl W
354Treat any warnings during makefile parsing as errors. 354Treat any warnings during makefile parsing as errors.
355.It Fl X 355.It Fl X
356Don't export variables passed on the command line to the environment 356Don't export variables passed on the command line to the environment
357individually. 357individually.
358Variables passed on the command line are still exported 358Variables passed on the command line are still exported
359via the 359via the
360.Va MAKEFLAGS 360.Va MAKEFLAGS
361environment variable. 361environment variable.
362This option may be useful on systems which have a small limit on the 362This option may be useful on systems which have a small limit on the
363size of command arguments. 363size of command arguments.
364.It Ar variable=value 364.It Ar variable=value
365Set the value of the variable 365Set the value of the variable
366.Ar variable 366.Ar variable
367to 367to
368.Ar value . 368.Ar value .
369Normally, all values passed on the command line are also exported to 369Normally, all values passed on the command line are also exported to
370sub-makes in the environment. 370sub-makes in the environment.
371The 371The
372.Fl X 372.Fl X
373flag disables this behavior. 373flag disables this behavior.
374Variable assignments should follow options for POSIX compatibility 374Variable assignments should follow options for POSIX compatibility
375but no ordering is enforced. 375but no ordering is enforced.
376.El 376.El
377.Pp 377.Pp
378There are seven different types of lines in a makefile: file dependency 378There are seven different types of lines in a makefile: file dependency
379specifications, shell commands, variable assignments, include statements, 379specifications, shell commands, variable assignments, include statements,
380conditional directives, for loops, and comments. 380conditional directives, for loops, and comments.
381.Pp 381.Pp
382In general, lines may be continued from one line to the next by ending 382In general, lines may be continued from one line to the next by ending
383them with a backslash 383them with a backslash
384.Pq Ql \e . 384.Pq Ql \e .
385The trailing newline character and initial whitespace on the following 385The trailing newline character and initial whitespace on the following
386line are compressed into a single space. 386line are compressed into a single space.
387.Sh FILE DEPENDENCY SPECIFICATIONS 387.Sh FILE DEPENDENCY SPECIFICATIONS
388Dependency lines consist of one or more targets, an operator, and zero 388Dependency lines consist of one or more targets, an operator, and zero
389or more sources. 389or more sources.
390This creates a relationship where the targets 390This creates a relationship where the targets
391.Dq depend 391.Dq depend
392on the sources 392on the sources
393and are usually created from them. 393and are usually created from them.
394The exact relationship between the target and the source is determined 394The exact relationship between the target and the source is determined
395by the operator that separates them. 395by the operator that separates them.
396The three operators are as follows: 396The three operators are as follows:
397.Bl -tag -width flag 397.Bl -tag -width flag
398.It Ic \&: 398.It Ic \&:
399A target is considered out-of-date if its modification time is less than 399A target is considered out-of-date if its modification time is less than
400those of any of its sources. 400those of any of its sources.
401Sources for a target accumulate over dependency lines when this operator 401Sources for a target accumulate over dependency lines when this operator
402is used. 402is used.
403The target is removed if 403The target is removed if
404.Nm 404.Nm
405is interrupted. 405is interrupted.
406.It Ic \&! 406.It Ic \&!
407Targets are always re-created, but not until all sources have been 407Targets are always re-created, but not until all sources have been
408examined and re-created as necessary. 408examined and re-created as necessary.
409Sources for a target accumulate over dependency lines when this operator 409Sources for a target accumulate over dependency lines when this operator
410is used. 410is used.
411The target is removed if 411The target is removed if
412.Nm 412.Nm
413is interrupted. 413is interrupted.
414.It Ic \&:: 414.It Ic \&::
415If no sources are specified, the target is always re-created. 415If no sources are specified, the target is always re-created.
416Otherwise, a target is considered out-of-date if any of its sources has 416Otherwise, a target is considered out-of-date if any of its sources has
417been modified more recently than the target. 417been modified more recently than the target.
418Sources for a target do not accumulate over dependency lines when this 418Sources for a target do not accumulate over dependency lines when this
419operator is used. 419operator is used.
420The target will not be removed if 420The target will not be removed if
421.Nm 421.Nm
422is interrupted. 422is interrupted.
423.El 423.El
424.Pp 424.Pp
425Targets and sources may contain the shell wildcard values 425Targets and sources may contain the shell wildcard values
426.Ql \&? , 426.Ql \&? ,
427.Ql * , 427.Ql * ,
428.Ql [] , 428.Ql [] ,
429and 429and
430.Ql {} . 430.Ql {} .
431The values 431The values
432.Ql \&? , 432.Ql \&? ,
433.Ql * , 433.Ql * ,
434and 434and
435.Ql [] 435.Ql []
436may only be used as part of the final 436may only be used as part of the final
437component of the target or source, and must be used to describe existing 437component of the target or source, and must be used to describe existing
438files. 438files.
439The value 439The value
440.Ql {} 440.Ql {}
441need not necessarily be used to describe existing files. 441need not necessarily be used to describe existing files.
442Expansion is in directory order, not alphabetically as done in the shell. 442Expansion is in directory order, not alphabetically as done in the shell.
443.Sh SHELL COMMANDS 443.Sh SHELL COMMANDS
444Each target may have associated with it a series of shell commands, normally 444Each target may have associated with it a series of shell commands, normally
445used to create the target. 445used to create the target.
446Each of the commands in this script 446Each of the commands in this script
447.Em must 447.Em must
448be preceded by a tab. 448be preceded by a tab.
449While any target may appear on a dependency line, only one of these 449While any target may appear on a dependency line, only one of these
450dependencies may be followed by a creation script, unless the 450dependencies may be followed by a creation script, unless the
451.Ql Ic \&:: 451.Ql Ic \&::
452operator is used. 452operator is used.
453.Pp 453.Pp
454If the first characters of the command line are any combination of 454If the first characters of the command line are any combination of
455.Ql Ic @ , 455.Ql Ic @ ,
456.Ql Ic + , 456.Ql Ic + ,
457or 457or
458.Ql Ic \- , 458.Ql Ic \- ,
459the command is treated specially. 459the command is treated specially.
460A 460A
461.Ql Ic @ 461.Ql Ic @
462causes the command not to be echoed before it is executed. 462causes the command not to be echoed before it is executed.
463A 463A
464.Ql Ic + 464.Ql Ic +
465causes the command to be executed even when 465causes the command to be executed even when
466.Fl n 466.Fl n
467is given. 467is given.
468This is similar to the effect of the .MAKE special source, 468This is similar to the effect of the .MAKE special source,
469except that the effect can be limited to a single line of a script. 469except that the effect can be limited to a single line of a script.
470A 470A
471.Ql Ic \- 471.Ql Ic \-
472causes any non-zero exit status of the command line to be ignored. 472causes any non-zero exit status of the command line to be ignored.
473.Pp 473.Pp
474When 474When
475.Nm 475.Nm
476is run in jobs mode with 476is run in jobs mode with
477.Fl j Ar max_jobs , 477.Fl j Ar max_jobs ,
478the entire script for the target is fed to a 478the entire script for the target is fed to a
479single instance of the shell. 479single instance of the shell.
480.Pp 480.Pp
481In compatibility (non-jobs) mode, each command is run in a separate process. 481In compatibility (non-jobs) mode, each command is run in a separate process.
482If the command contains any shell meta characters 482If the command contains any shell meta characters
483.Pq Ql #=|^(){};&<>*?[]:$`\e\en 483.Pq Ql #=|^(){};&<>*?[]:$`\e\en
484it will be passed to the shell, otherwise 484it will be passed to the shell, otherwise
485.Nm 485.Nm
486will attempt direct execution. 486will attempt direct execution.
487.Pp 487.Pp
488Since 488Since
489.Nm 489.Nm
490will 490will
491.Xr chdir 2 491.Xr chdir 2
492to 492to
493.Ql Va .OBJDIR 493.Ql Va .OBJDIR
494before executing any targets, each child process 494before executing any targets, each child process
495starts with that as its current working directory. 495starts with that as its current working directory.
496.Pp 496.Pp
497Makefiles should be written so that the mode of 497Makefiles should be written so that the mode of
498.Nm 498.Nm
499operation does not change their behavior. 499operation does not change their behavior.
500For example, any command which needs to use 500For example, any command which needs to use
501.Dq cd 501.Dq cd
502or 502or
503.Dq chdir , 503.Dq chdir ,
504without side-effect should be put in parenthesis: 504without side-effect should be put in parenthesis:
505.Bd -literal -offset indent 505.Bd -literal -offset indent
506 506
507avoid-chdir-side-effects: 507avoid-chdir-side-effects:
508 @echo Building $@ in `pwd` 508 @echo Building $@ in `pwd`
509 @(cd ${.CURDIR} && ${.MAKE} $@) 509 @(cd ${.CURDIR} && ${.MAKE} $@)
510 @echo Back in `pwd` 510 @echo Back in `pwd`
511 511
512ensure-one-shell-regardless-of-mode: 512ensure-one-shell-regardless-of-mode:
513 @echo Building $@ in `pwd`; \\ 513 @echo Building $@ in `pwd`; \\
514 (cd ${.CURDIR} && ${.MAKE} $@); \\ 514 (cd ${.CURDIR} && ${.MAKE} $@); \\
515 echo Back in `pwd` 515 echo Back in `pwd`
516.Ed 516.Ed
517.Sh VARIABLE ASSIGNMENTS 517.Sh VARIABLE ASSIGNMENTS
518Variables in make are much like variables in the shell, and, by tradition, 518Variables in make are much like variables in the shell, and, by tradition,
519consist of all upper-case letters. 519consist of all upper-case letters.
520.Ss Variable assignment modifiers 520.Ss Variable assignment modifiers
521The five operators that can be used to assign values to variables are as 521The five operators that can be used to assign values to variables are as
522follows: 522follows:
523.Bl -tag -width Ds 523.Bl -tag -width Ds
524.It Ic \&= 524.It Ic \&=
525Assign the value to the variable. 525Assign the value to the variable.
526Any previous value is overridden. 526Any previous value is overridden.
527.It Ic \&+= 527.It Ic \&+=
528Append the value to the current value of the variable. 528Append the value to the current value of the variable.
529.It Ic \&?= 529.It Ic \&?=
530Assign the value to the variable if it is not already defined. 530Assign the value to the variable if it is not already defined.
531.It Ic \&:= 531.It Ic \&:=
532Assign with expansion, i.e. expand the value before assigning it 532Assign with expansion, i.e. expand the value before assigning it
533to the variable. 533to the variable.
534Normally, expansion is not done until the variable is referenced. 534Normally, expansion is not done until the variable is referenced.
535.Em NOTE : 535.Em NOTE :
536References to undefined variables are 536References to undefined variables are
537.Em not 537.Em not
538expanded. 538expanded.
539This can cause problems when variable modifiers are used. 539This can cause problems when variable modifiers are used.
540.It Ic \&!= 540.It Ic \&!=
541Expand the value and pass it to the shell for execution and assign 541Expand the value and pass it to the shell for execution and assign
542the result to the variable. 542the result to the variable.
543Any newlines in the result are replaced with spaces. 543Any newlines in the result are replaced with spaces.
544.El 544.El
545.Pp 545.Pp
546Any white-space before the assigned 546Any white-space before the assigned
547.Ar value 547.Ar value
548is removed; if the value is being appended, a single space is inserted 548is removed; if the value is being appended, a single space is inserted
549between the previous contents of the variable and the appended value. 549between the previous contents of the variable and the appended value.
550.Pp 550.Pp
551Variables are expanded by surrounding the variable name with either 551Variables are expanded by surrounding the variable name with either
552curly braces 552curly braces
553.Pq Ql {} 553.Pq Ql {}
554or parentheses 554or parentheses
555.Pq Ql () 555.Pq Ql ()
556and preceding it with 556and preceding it with
557a dollar sign 557a dollar sign
558.Pq Ql \&$ . 558.Pq Ql \&$ .
559If the variable name contains only a single letter, the surrounding 559If the variable name contains only a single letter, the surrounding
560braces or parentheses are not required. 560braces or parentheses are not required.
561This shorter form is not recommended. 561This shorter form is not recommended.
562.Pp 562.Pp
563If the variable name contains a dollar, then the name itself is expanded first. 563If the variable name contains a dollar, then the name itself is expanded first.
564This allows almost arbitrary variable names, however names containing dollar, 564This allows almost arbitrary variable names, however names containing dollar,
565braces, parenthesis, or whitespace are really best avoided! 565braces, parenthesis, or whitespace are really best avoided!
566.Pp 566.Pp
567If the result of expanding a variable contains a dollar sign 567If the result of expanding a variable contains a dollar sign
568.Pq Ql \&$ 568.Pq Ql \&$
569the string is expanded again. 569the string is expanded again.
570.Pp 570.Pp
571Variable substitution occurs at three distinct times, depending on where 571Variable substitution occurs at three distinct times, depending on where
572the variable is being used. 572the variable is being used.
573.Bl -enum 573.Bl -enum
574.It 574.It
575Variables in dependency lines are expanded as the line is read. 575Variables in dependency lines are expanded as the line is read.
576.It 576.It
577Variables in shell commands are expanded when the shell command is 577Variables in shell commands are expanded when the shell command is
578executed. 578executed.
579.It 579.It
580.Dq .for 580.Dq .for
581loop index variables are expanded on each loop iteration. 581loop index variables are expanded on each loop iteration.
582Note that other variables are not expanded inside loops so 582Note that other variables are not expanded inside loops so
583the following example code: 583the following example code:
584.Bd -literal -offset indent 584.Bd -literal -offset indent
585 585
586.Dv .for i in 1 2 3 586.Dv .for i in 1 2 3
587a+= ${i} 587a+= ${i}
588j= ${i} 588j= ${i}
589b+= ${j} 589b+= ${j}
590.Dv .endfor 590.Dv .endfor
591 591
592all: 592all:
593 @echo ${a} 593 @echo ${a}
594 @echo ${b} 594 @echo ${b}
595 595
596.Ed 596.Ed
597will print: 597will print:
598.Bd -literal -offset indent 598.Bd -literal -offset indent
5991 2 3 5991 2 3
6003 3 3 6003 3 3
601 601
602.Ed 602.Ed
603Because while ${a} contains 603Because while ${a} contains
604.Dq 1 2 3 604.Dq 1 2 3
605after the loop is executed, ${b} 605after the loop is executed, ${b}
606contains 606contains
607.Dq ${j} ${j} ${j} 607.Dq ${j} ${j} ${j}
608which expands to 608which expands to
609.Dq 3 3 3 609.Dq 3 3 3
610since after the loop completes ${j} contains 610since after the loop completes ${j} contains
611.Dq 3 . 611.Dq 3 .
612.El 612.El
613.Ss Variable classes 613.Ss Variable classes
614The four different classes of variables (in order of increasing precedence) 614The four different classes of variables (in order of increasing precedence)
615are: 615are:
616.Bl -tag -width Ds 616.Bl -tag -width Ds
617.It Environment variables 617.It Environment variables
618Variables defined as part of 618Variables defined as part of
619.Nm Ns 's 619.Nm Ns 's
620environment. 620environment.
621.It Global variables 621.It Global variables
622Variables defined in the makefile or in included makefiles. 622Variables defined in the makefile or in included makefiles.
623.It Command line variables 623.It Command line variables
624Variables defined as part of the command line. 624Variables defined as part of the command line.
625.It Local variables 625.It Local variables
626Variables that are defined specific to a certain target. 626Variables that are defined specific to a certain target.
627The seven local variables are as follows: 627The seven local variables are as follows:
628.Bl -tag -width ".ARCHIVE" 628.Bl -tag -width ".ARCHIVE"
629.It Va .ALLSRC 629.It Va .ALLSRC
630The list of all sources for this target; also known as 630The list of all sources for this target; also known as
631.Ql Va \&\*[Gt] . 631.Ql Va \&\*[Gt] .
632.It Va .ARCHIVE 632.It Va .ARCHIVE
633The name of the archive file. 633The name of the archive file.
634.It Va .IMPSRC 634.It Va .IMPSRC
635In suffix-transformation rules, the name/path of the source from which the 635In suffix-transformation rules, the name/path of the source from which the
636target is to be transformed (the 636target is to be transformed (the
637.Dq implied 637.Dq implied
638source); also known as 638source); also known as
639.Ql Va \&\*[Lt] . 639.Ql Va \&\*[Lt] .
640It is not defined in explicit rules. 640It is not defined in explicit rules.
641.It Va .INCLUDEDFROMDIR 641.It Va .INCLUDEDFROMDIR
642The directory of the file this Makefile was included from. 642The directory of the file this Makefile was included from.
643.It Va .INCLUDEDFROMFILE 643.It Va .INCLUDEDFROMFILE
644The filename of the file this Makefile was included from. 644The filename of the file this Makefile was included from.
645.It Va .MEMBER 645.It Va .MEMBER
646The name of the archive member. 646The name of the archive member.
647.It Va .OODATE 647.It Va .OODATE
648The list of sources for this target that were deemed out-of-date; also 648The list of sources for this target that were deemed out-of-date; also
649known as 649known as
650.Ql Va \&? . 650.Ql Va \&? .
651.It Va .PREFIX 651.It Va .PREFIX
652The file prefix of the target, containing only the file portion, no suffix 652The file prefix of the target, containing only the file portion, no suffix
653or preceding directory components; also known as 653or preceding directory components; also known as
654.Ql Va * . 654.Ql Va * .
655.It Va .TARGET 655.It Va .TARGET
656The name of the target; also known as 656The name of the target; also known as
657.Ql Va @ . 657.Ql Va @ .
658.El 658.El
659.Pp 659.Pp
660The shorter forms 660The shorter forms
661.Ql Va @ , 661.Ql Va @ ,
662.Ql Va \&? , 662.Ql Va \&? ,
663.Ql Va \&\*[Lt] , 663.Ql Va \&\*[Lt] ,
664.Ql Va \&\*[Gt] , 664.Ql Va \&\*[Gt] ,
665and 665and
666.Ql Va * 666.Ql Va *
667are permitted for backward 667are permitted for backward
668compatibility with historical makefiles and are not recommended. 668compatibility with historical makefiles and are not recommended.
669The six variables 669The six variables
670.Ql Va "@F" , 670.Ql Va "@F" ,
671.Ql Va "@D" , 671.Ql Va "@D" ,
672.Ql Va "\*[Lt]F" , 672.Ql Va "\*[Lt]F" ,
673.Ql Va "\*[Lt]D" , 673.Ql Va "\*[Lt]D" ,
674.Ql Va "*F" , 674.Ql Va "*F" ,
675and 675and
676.Ql Va "*D" 676.Ql Va "*D"
677are permitted for compatibility with 677are permitted for compatibility with
678.At V 678.At V
679makefiles and are not recommended. 679makefiles and are not recommended.
680.Pp 680.Pp
681Four of the local variables may be used in sources on dependency lines 681Four of the local variables may be used in sources on dependency lines
682because they expand to the proper value for each target on the line. 682because they expand to the proper value for each target on the line.
683These variables are 683These variables are
684.Ql Va .TARGET , 684.Ql Va .TARGET ,
685.Ql Va .PREFIX , 685.Ql Va .PREFIX ,
686.Ql Va .ARCHIVE , 686.Ql Va .ARCHIVE ,
687and 687and
688.Ql Va .MEMBER . 688.Ql Va .MEMBER .
689.El 689.El
690.Ss Additional built-in variables 690.Ss Additional built-in variables
691In addition, 691In addition,
692.Nm 692.Nm
693sets or knows about the following variables: 693sets or knows about the following variables:
694.Bl -tag -width .MAKEOVERRIDES 694.Bl -tag -width .MAKEOVERRIDES
695.It Va \&$ 695.It Va \&$
696A single dollar sign 696A single dollar sign
697.Ql \&$ , 697.Ql \&$ ,
698i.e. 698i.e.
699.Ql \&$$ 699.Ql \&$$
700expands to a single dollar 700expands to a single dollar
701sign. 701sign.
702.It Va .ALLTARGETS 702.It Va .ALLTARGETS
703The list of all targets encountered in the Makefile. 703The list of all targets encountered in the Makefile.
704If evaluated during 704If evaluated during
705Makefile parsing, lists only those targets encountered thus far. 705Makefile parsing, lists only those targets encountered thus far.
706.It Va .CURDIR 706.It Va .CURDIR
707A path to the directory where 707A path to the directory where
708.Nm 708.Nm
709was executed. 709was executed.
710Refer to the description of 710Refer to the description of
711.Ql Ev PWD 711.Ql Ev PWD
712for more details. 712for more details.
713.It Ev MAKE 713.It Ev MAKE
714The name that 714The name that
715.Nm 715.Nm
716was executed with 716was executed with
717.Pq Va argv[0] . 717.Pq Va argv[0] .
718For compatibility 718For compatibility
719.Nm 719.Nm
720also sets 720also sets
721.Va .MAKE 721.Va .MAKE
722with the same value. 722with the same value.
723The preferred variable to use is the environment variable 723The preferred variable to use is the environment variable
724.Ev MAKE 724.Ev MAKE
725because it is more compatible with other versions of 725because it is more compatible with other versions of
726.Nm 726.Nm
727and cannot be confused with the special target with the same name. 727and cannot be confused with the special target with the same name.
728.It Va .MAKE.DEPENDFILE 728.It Va .MAKE.DEPENDFILE
729Names the makefile (default 729Names the makefile (default
730.Ql Pa .depend ) 730.Ql Pa .depend )
731from which generated dependencies are read. 731from which generated dependencies are read.
732.It Va .MAKE.EXPAND_VARIABLES 732.It Va .MAKE.EXPAND_VARIABLES
733A boolean that controls the default behavior of the 733A boolean that controls the default behavior of the
734.Fl V 734.Fl V
735option. 735option.
736.It Va .MAKE.EXPORTED 736.It Va .MAKE.EXPORTED
737The list of variables exported by 737The list of variables exported by
738.Nm . 738.Nm .
739.It Va .MAKE.JOBS 739.It Va .MAKE.JOBS
740The argument to the 740The argument to the
741.Fl j 741.Fl j
742option. 742option.
743.It Va .MAKE.JOB.PREFIX 743.It Va .MAKE.JOB.PREFIX
744If 744If
745.Nm 745.Nm
746is run with 746is run with
747.Ar j 747.Ar j
748then output for each target is prefixed with a token 748then output for each target is prefixed with a token
749.Ql --- target --- 749.Ql --- target ---
750the first part of which can be controlled via 750the first part of which can be controlled via
751.Va .MAKE.JOB.PREFIX . 751.Va .MAKE.JOB.PREFIX .
752If 752If
753.Va .MAKE.JOB.PREFIX 753.Va .MAKE.JOB.PREFIX
754is empty, no token is printed. 754is empty, no token is printed.
755.br 755.br
756For example: 756For example:
757.Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}] 757.Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}]
758would produce tokens like 758would produce tokens like
759.Ql ---make[1234] target --- 759.Ql ---make[1234] target ---
760making it easier to track the degree of parallelism being achieved. 760making it easier to track the degree of parallelism being achieved.
761.It Ev MAKEFLAGS 761.It Ev MAKEFLAGS
762The environment variable 762The environment variable
763.Ql Ev MAKEFLAGS 763.Ql Ev MAKEFLAGS
764may contain anything that 764may contain anything that
765may be specified on 765may be specified on
766.Nm Ns 's 766.Nm Ns 's
767command line. 767command line.
768Anything specified on 768Anything specified on
769.Nm Ns 's 769.Nm Ns 's
770command line is appended to the 770command line is appended to the
771.Ql Ev MAKEFLAGS 771.Ql Ev MAKEFLAGS
772variable which is then 772variable which is then
773entered into the environment for all programs which 773entered into the environment for all programs which
774.Nm 774.Nm
775executes. 775executes.
776.It Va .MAKE.LEVEL 776.It Va .MAKE.LEVEL
777The recursion depth of 777The recursion depth of
778.Nm . 778.Nm .
779The initial instance of 779The initial instance of
780.Nm 780.Nm
781will be 0, and an incremented value is put into the environment 781will be 0, and an incremented value is put into the environment
782to be seen by the next generation. 782to be seen by the next generation.
783This allows tests like: 783This allows tests like:
784.Li .if ${.MAKE.LEVEL} == 0 784.Li .if ${.MAKE.LEVEL} == 0
785to protect things which should only be evaluated in the initial instance of 785to protect things which should only be evaluated in the initial instance of
786.Nm . 786.Nm .
787.It Va .MAKE.MAKEFILE_PREFERENCE 787.It Va .MAKE.MAKEFILE_PREFERENCE
788The ordered list of makefile names 788The ordered list of makefile names
789(default 789(default
790.Ql Pa makefile , 790.Ql Pa makefile ,
791.Ql Pa Makefile ) 791.Ql Pa Makefile )
792that 792that
793.Nm 793.Nm
794will look for. 794will look for.
795.It Va .MAKE.MAKEFILES 795.It Va .MAKE.MAKEFILES
796The list of makefiles read by 796The list of makefiles read by
797.Nm , 797.Nm ,
798which is useful for tracking dependencies. 798which is useful for tracking dependencies.
799Each makefile is recorded only once, regardless of the number of times read. 799Each makefile is recorded only once, regardless of the number of times read.
800.It Va .MAKE.MODE 800.It Va .MAKE.MODE
801Processed after reading all makefiles. 801Processed after reading all makefiles.
802Can affect the mode that 802Can affect the mode that
803.Nm 803.Nm
804runs in. 804runs in.
805It can contain a number of keywords: 805It can contain a number of keywords:
806.Bl -hang -width ignore-cmd 806.Bl -hang -width ignore-cmd
807.It Pa compat 807.It Pa compat
808Like 808Like
809.Fl B , 809.Fl B ,
810puts 810puts
811.Nm 811.Nm
812into "compat" mode. 812into "compat" mode.
813.It Pa meta 813.It Pa meta
814Puts 814Puts
815.Nm 815.Nm
816into "meta" mode, where meta files are created for each target 816into "meta" mode, where meta files are created for each target
817to capture the command run, the output generated and if 817to capture the command run, the output generated and if
818.Xr filemon 4 818.Xr filemon 4
819is available, the system calls which are of interest to 819is available, the system calls which are of interest to
820.Nm . 820.Nm .
821The captured output can be very useful when diagnosing errors. 821The captured output can be very useful when diagnosing errors.
822.It Pa curdirOk= Ar bf 822.It Pa curdirOk= Ar bf
823Normally 823Normally
824.Nm 824.Nm
825will not create .meta files in 825will not create .meta files in
826.Ql Va .CURDIR . 826.Ql Va .CURDIR .
827This can be overridden by setting 827This can be overridden by setting
828.Va bf 828.Va bf
829to a value which represents True. 829to a value which represents True.
830.It Pa env 830.It Pa env
831For debugging, it can be useful to inlcude the environment 831For debugging, it can be useful to inlcude the environment
832in the .meta file. 832in the .meta file.
833.It Pa verbose 833.It Pa verbose
834If in "meta" mode, print a clue about the target being built. 834If in "meta" mode, print a clue about the target being built.
835This is useful if the build is otherwise running silently. 835This is useful if the build is otherwise running silently.
836The message printed the value of: 836The message printed the value of:
837.Va .MAKE.META.PREFIX . 837.Va .MAKE.META.PREFIX .
838.It Pa ignore-cmd 838.It Pa ignore-cmd
839Some makefiles have commands which are simply not stable. 839Some makefiles have commands which are simply not stable.
840This keyword causes them to be ignored for 840This keyword causes them to be ignored for
841determining whether a target is out of date in "meta" mode. 841determining whether a target is out of date in "meta" mode.
842See also 842See also
843.Ic .NOMETA_CMP . 843.Ic .NOMETA_CMP .
844.It Pa silent= Ar bf 844.It Pa silent= Ar bf
845If 845If
846.Va bf 846.Va bf
847is True, when a .meta file is created, mark the target 847is True, when a .meta file is created, mark the target
848.Ic .SILENT . 848.Ic .SILENT .
849.El 849.El
850.It Va .MAKE.META.BAILIWICK 850.It Va .MAKE.META.BAILIWICK
851In "meta" mode, provides a list of prefixes which 851In "meta" mode, provides a list of prefixes which
852match the directories controlled by 852match the directories controlled by
853.Nm . 853.Nm .
854If a file that was generated outside of 854If a file that was generated outside of
855.Va .OBJDIR 855.Va .OBJDIR
856but within said bailiwick is missing, 856but within said bailiwick is missing,
857the current target is considered out-of-date. 857the current target is considered out-of-date.
858.It Va .MAKE.META.CREATED 858.It Va .MAKE.META.CREATED
859In "meta" mode, this variable contains a list of all the meta files 859In "meta" mode, this variable contains a list of all the meta files
860updated. 860updated.
861If not empty, it can be used to trigger processing of 861If not empty, it can be used to trigger processing of
862.Va .MAKE.META.FILES . 862.Va .MAKE.META.FILES .
863.It Va .MAKE.META.FILES 863.It Va .MAKE.META.FILES
864In "meta" mode, this variable contains a list of all the meta files 864In "meta" mode, this variable contains a list of all the meta files
865used (updated or not). 865used (updated or not).
866This list can be used to process the meta files to extract dependency 866This list can be used to process the meta files to extract dependency
867information. 867information.
868.It Va .MAKE.META.IGNORE_PATHS 868.It Va .MAKE.META.IGNORE_PATHS
869Provides a list of path prefixes that should be ignored; 869Provides a list of path prefixes that should be ignored;
870because the contents are expected to change over time. 870because the contents are expected to change over time.
871The default list includes: 871The default list includes:
872.Ql Pa /dev /etc /proc /tmp /var/run /var/tmp 872.Ql Pa /dev /etc /proc /tmp /var/run /var/tmp
873.It Va .MAKE.META.PREFIX 873.It Va .MAKE.META.PREFIX
874Defines the message printed for each meta file updated in "meta verbose" mode. 874Defines the message printed for each meta file updated in "meta verbose" mode.
875The default value is: 875The default value is:
876.Dl Building ${.TARGET:H:tA}/${.TARGET:T} 876.Dl Building ${.TARGET:H:tA}/${.TARGET:T}
877.It Va .MAKEOVERRIDES 877.It Va .MAKEOVERRIDES
878This variable is used to record the names of variables assigned to 878This variable is used to record the names of variables assigned to
879on the command line, so that they may be exported as part of 879on the command line, so that they may be exported as part of
880.Ql Ev MAKEFLAGS . 880.Ql Ev MAKEFLAGS .
881This behaviour can be disabled by assigning an empty value to 881This behaviour can be disabled by assigning an empty value to
882.Ql Va .MAKEOVERRIDES 882.Ql Va .MAKEOVERRIDES
883within a makefile. 883within a makefile.
884Extra variables can be exported from a makefile 884Extra variables can be exported from a makefile
885by appending their names to 885by appending their names to
886.Ql Va .MAKEOVERRIDES . 886.Ql Va .MAKEOVERRIDES .
887.Ql Ev MAKEFLAGS 887.Ql Ev MAKEFLAGS
888is re-exported whenever 888is re-exported whenever
889.Ql Va .MAKEOVERRIDES 889.Ql Va .MAKEOVERRIDES
890is modified. 890is modified.
891.It Va .MAKE.PATH_FILEMON 891.It Va .MAKE.PATH_FILEMON
892If 892If
893.Nm 893.Nm
894was built with 894was built with
895.Xr filemon 4 895.Xr filemon 4
896support, this is set to the path of the device node. 896support, this is set to the path of the device node.
897This allows makefiles to test for this support. 897This allows makefiles to test for this support.
898.It Va .MAKE.PID 898.It Va .MAKE.PID
899The process-id of 899The process-id of
900.Nm . 900.Nm .
901.It Va .MAKE.PPID 901.It Va .MAKE.PPID
902The parent process-id of 902The parent process-id of
903.Nm . 903.Nm .
904.It Va MAKE_PRINT_VAR_ON_ERROR 904.It Va MAKE_PRINT_VAR_ON_ERROR
905When 905When
906.Nm 906.Nm
907stops due to an error, it prints its name and the value of 907stops due to an error, it prints its name and the value of
908.Ql Va .CURDIR 908.Ql Va .CURDIR
909as well as the value of any variables named in 909as well as the value of any variables named in
910.Ql Va MAKE_PRINT_VAR_ON_ERROR . 910.Ql Va MAKE_PRINT_VAR_ON_ERROR .
911.It Va .newline 911.It Va .newline
912This variable is simply assigned a newline character as its value. 912This variable is simply assigned a newline character as its value.
913This allows expansions using the 913This allows expansions using the
914.Cm \&:@ 914.Cm \&:@
915modifier to put a newline between 915modifier to put a newline between
916iterations of the loop rather than a space. 916iterations of the loop rather than a space.
917For example, the printing of 917For example, the printing of
918.Ql Va MAKE_PRINT_VAR_ON_ERROR 918.Ql Va MAKE_PRINT_VAR_ON_ERROR
919could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}. 919could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}.
920.It Va .OBJDIR 920.It Va .OBJDIR
921A path to the directory where the targets are built. 921A path to the directory where the targets are built.
922Its value is determined by trying to 922Its value is determined by trying to
923.Xr chdir 2 923.Xr chdir 2
924to the following directories in order and using the first match: 924to the following directories in order and using the first match:
925.Bl -enum 925.Bl -enum
926.It 926.It
927.Ev ${MAKEOBJDIRPREFIX}${.CURDIR} 927.Ev ${MAKEOBJDIRPREFIX}${.CURDIR}
928.Pp 928.Pp
929(Only if 929(Only if
930.Ql Ev MAKEOBJDIRPREFIX 930.Ql Ev MAKEOBJDIRPREFIX
931is set in the environment or on the command line.) 931is set in the environment or on the command line.)
932.It 932.It
933.Ev ${MAKEOBJDIR} 933.Ev ${MAKEOBJDIR}
934.Pp 934.Pp
935(Only if 935(Only if
936.Ql Ev MAKEOBJDIR 936.Ql Ev MAKEOBJDIR
937is set in the environment or on the command line.) 937is set in the environment or on the command line.)
938.It 938.It
939.Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE} 939.Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE}
940.It 940.It
941.Ev ${.CURDIR} Ns Pa /obj 941.Ev ${.CURDIR} Ns Pa /obj
942.It 942.It
943.Pa /usr/obj/ Ns Ev ${.CURDIR} 943.Pa /usr/obj/ Ns Ev ${.CURDIR}
944.It 944.It
945.Ev ${.CURDIR} 945.Ev ${.CURDIR}
946.El 946.El
947.Pp 947.Pp
948Variable expansion is performed on the value before it's used, 948Variable expansion is performed on the value before it's used,
949so expressions such as 949so expressions such as
950.Dl ${.CURDIR:S,^/usr/src,/var/obj,} 950.Dl ${.CURDIR:S,^/usr/src,/var/obj,}
951may be used. 951may be used.
952This is especially useful with 952This is especially useful with
953.Ql Ev MAKEOBJDIR . 953.Ql Ev MAKEOBJDIR .
954.Pp 954.Pp
955.Ql Va .OBJDIR 955.Ql Va .OBJDIR
956may be modified in the makefile as a global variable. 956may be modified in the makefile as a global variable.
957In all cases, 957In all cases,
958.Nm 958.Nm
959will 959will
960.Xr chdir 2 960.Xr chdir 2
961to 961to
962.Ql Va .OBJDIR 962.Ql Va .OBJDIR
963and set 963and set
964.Ql Ev PWD 964.Ql Ev PWD
965to that directory before executing any targets. 965to that directory before executing any targets.
966. 966.
967.It Va .PARSEDIR 967.It Va .PARSEDIR
968A path to the directory of the current 968A path to the directory of the current
969.Ql Pa Makefile 969.Ql Pa Makefile
970being parsed. 970being parsed.
971.It Va .PARSEFILE 971.It Va .PARSEFILE
972The basename of the current 972The basename of the current
973.Ql Pa Makefile 973.Ql Pa Makefile
974being parsed. 974being parsed.
975This variable and 975This variable and
976.Ql Va .PARSEDIR 976.Ql Va .PARSEDIR
977are both set only while the 977are both set only while the
978.Ql Pa Makefiles 978.Ql Pa Makefiles
979are being parsed. 979are being parsed.
980If you want to retain their current values, assign them to a variable 980If you want to retain their current values, assign them to a variable
981using assignment with expansion: 981using assignment with expansion:
982.Pq Ql Cm \&:= . 982.Pq Ql Cm \&:= .
983.It Va .PATH 983.It Va .PATH
984A variable that represents the list of directories that 984A variable that represents the list of directories that
985.Nm 985.Nm
986will search for files. 986will search for files.
987The search list should be updated using the target 987The search list should be updated using the target
988.Ql Va .PATH 988.Ql Va .PATH
989rather than the variable. 989rather than the variable.
990.It Ev PWD 990.It Ev PWD
991Alternate path to the current directory. 991Alternate path to the current directory.
992.Nm 992.Nm
993normally sets 993normally sets
994.Ql Va .CURDIR 994.Ql Va .CURDIR
995to the canonical path given by 995to the canonical path given by
996.Xr getcwd 3 . 996.Xr getcwd 3 .
997However, if the environment variable 997However, if the environment variable
998.Ql Ev PWD 998.Ql Ev PWD
999is set and gives a path to the current directory, then 999is set and gives a path to the current directory, then
1000.Nm 1000.Nm
1001sets 1001sets
1002.Ql Va .CURDIR 1002.Ql Va .CURDIR
1003to the value of 1003to the value of
1004.Ql Ev PWD 1004.Ql Ev PWD
1005instead. 1005instead.
1006This behaviour is disabled if 1006This behaviour is disabled if
1007.Ql Ev MAKEOBJDIRPREFIX 1007.Ql Ev MAKEOBJDIRPREFIX
1008is set or 1008is set or
1009.Ql Ev MAKEOBJDIR 1009.Ql Ev MAKEOBJDIR
1010contains a variable transform. 1010contains a variable transform.
1011.Ql Ev PWD 1011.Ql Ev PWD
1012is set to the value of 1012is set to the value of
1013.Ql Va .OBJDIR 1013.Ql Va .OBJDIR
1014for all programs which 1014for all programs which
1015.Nm 1015.Nm
1016executes. 1016executes.
1017.It Ev .TARGETS 1017.It Ev .TARGETS
1018The list of targets explicitly specified on the command line, if any. 1018The list of targets explicitly specified on the command line, if any.
1019.It Ev VPATH 1019.It Ev VPATH
1020Colon-separated 1020Colon-separated
1021.Pq Dq \&: 1021.Pq Dq \&:
1022lists of directories that 1022lists of directories that
1023.Nm 1023.Nm
1024will search for files. 1024will search for files.
1025The variable is supported for compatibility with old make programs only, 1025The variable is supported for compatibility with old make programs only,
1026use 1026use
1027.Ql Va .PATH 1027.Ql Va .PATH
1028instead. 1028instead.
1029.El 1029.El
1030.Ss Variable modifiers 1030.Ss Variable modifiers
1031Variable expansion may be modified to select or modify each word of the 1031Variable expansion may be modified to select or modify each word of the