xref: /freebsd/contrib/bmake/make.1 (revision 9bc300465e48e19d794d88d0c158a2adb92c7197)
1.\"	$NetBSD: make.1,v 1.378 2024/07/01 21:02:26 sjg Exp $
2.\"
3.\" Copyright (c) 1990, 1993
4.\"	The Regents of the University of California.  All rights reserved.
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.
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
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.\"
30.\"	from: @(#)make.1	8.4 (Berkeley) 3/19/94
31.\"
32.Dd July 1, 2024
33.Dt MAKE 1
34.Os
35.Sh NAME
36.Nm make
37.Nd maintain program dependencies
38.Sh SYNOPSIS
39.Nm
40.Op Fl BeikNnqrSstWwX
41.Op Fl C Ar directory
42.Op Fl D Ar variable
43.Op Fl d Ar flags
44.Op Fl f Ar makefile
45.Op Fl I Ar directory
46.Op Fl J Ar private
47.Op Fl j Ar max_jobs
48.Op Fl m Ar directory
49.Op Fl T Ar file
50.Op Fl V Ar variable
51.Op Fl v Ar variable
52.Op Ar variable\| Ns Cm \&= Ns Ar value
53.Op Ar target No ...
54.Sh DESCRIPTION
55.Nm
56is a program designed to simplify the maintenance of other programs.
57Its input is a list of specifications as to the files upon which programs
58and other files depend.
59If no
60.Fl f Ar makefile
61option is given,
62.Nm
63tries to open
64.Sq Pa makefile
65then
66.Sq Pa Makefile
67in order to find the specifications.
68If the file
69.Sq Pa .depend
70exists, it is read, see
71.Xr mkdep 1 .
72.Pp
73This manual page is intended as a reference document only.
74For a more thorough description of
75.Nm
76and makefiles, please refer to
77.%T "PMake \- A Tutorial"
78(from 1993).
79.Pp
80.Nm
81prepends the contents of the
82.Ev MAKEFLAGS
83environment variable to the command line arguments before parsing them.
84.Pp
85The options are as follows:
86.Bl -tag -width Ds
87.It Fl B
88Try to be backwards compatible by executing a single shell per command and
89by making the sources of a dependency line in sequence.
90.It Fl C Ar directory
91Change to
92.Ar directory
93before reading the makefiles or doing anything else.
94If multiple
95.Fl C
96options are specified, each is interpreted relative to the previous one:
97.Fl C Pa / Fl C Pa etc
98is equivalent to
99.Fl C Pa /etc .
100.It Fl D Ar variable
101Define
102.Ar variable
103to be 1, in the global scope.
104.It Fl d Oo Cm \- Oc Ns Ar flags
105Turn on debugging, and specify which portions of
106.Nm
107are to print debugging information.
108Unless the flags are preceded by
109.Ql \- ,
110they are added to the
111.Ev MAKEFLAGS
112environment variable and are passed on to any child make processes.
113By default, debugging information is printed to standard error,
114but this can be changed using the
115.Cm F
116debugging flag.
117The debugging output is always unbuffered; in addition, if debugging
118is enabled but debugging output is not directed to standard output,
119the standard output is line buffered.
120The available
121.Ar flags
122are:
123.Bl -tag -width Ds
124.It Cm A
125Print all possible debugging information;
126equivalent to specifying all of the debugging flags.
127.It Cm a
128Print debugging information about archive searching and caching.
129.It Cm C
130Print debugging information about the current working directory.
131.It Cm c
132Print debugging information about conditional evaluation.
133.It Cm d
134Print debugging information about directory searching and caching.
135.It Cm e
136Print debugging information about failed commands and targets.
137.It Cm F Ns Oo Cm \&+ Oc Ns Ar filename
138Specify where debugging output is written.
139This must be the last flag, because it consumes the remainder of
140the argument.
141If the character immediately after the
142.Cm F
143flag is
144.Ql \&+ ,
145the file is opened in append mode;
146otherwise the file is overwritten.
147If the file name is
148.Ql stdout
149or
150.Ql stderr ,
151debugging output is written to the standard output or standard error output
152respectively (and the
153.Ql \&+
154option has no effect).
155Otherwise, the output is written to the named file.
156If the file name ends with
157.Ql .%d ,
158the
159.Ql %d
160is replaced by the pid.
161.It Cm f
162Print debugging information about loop evaluation.
163.It Cm g1
164Print the input graph before making anything.
165.It Cm g2
166Print the input graph after making everything, or before exiting
167on error.
168.It Cm g3
169Print the input graph before exiting on error.
170.It Cm h
171Print debugging information about hash table operations.
172.It Cm j
173Print debugging information about running multiple shells.
174.It Cm L
175Turn on lint checks.
176This throws errors for variable assignments that do not parse correctly,
177at the time of assignment, so the file and line number are available.
178.It Cm l
179Print commands in Makefiles regardless of whether or not they are prefixed by
180.Ql @
181or other
182.Dq quiet
183flags.
184Also known as
185.Dq loud
186behavior.
187.It Cm M
188Print debugging information about
189.Dq meta
190mode decisions about targets.
191.It Cm m
192Print debugging information about making targets, including modification
193dates.
194.It Cm n
195Don't delete the temporary command scripts created when running commands.
196These temporary scripts are created in the directory
197referred to by the
198.Ev TMPDIR
199environment variable, or in
200.Pa /tmp
201if
202.Ev TMPDIR
203is unset or set to the empty string.
204The temporary scripts are created by
205.Xr mkstemp 3 ,
206and have names of the form
207.Pa makeXXXXXX .
208.Em NOTE :
209This can create many files in
210.Ev TMPDIR
211or
212.Pa /tmp ,
213so use with care.
214.It Cm p
215Print debugging information about makefile parsing.
216.It Cm s
217Print debugging information about suffix-transformation rules.
218.It Cm t
219Print debugging information about target list maintenance.
220.It Cm V
221Force the
222.Fl V
223option to print raw values of variables,
224overriding the default behavior set via
225.Va .MAKE.EXPAND_VARIABLES .
226.It Cm v
227Print debugging information about variable assignment and expansion.
228.It Cm x
229Run shell commands with
230.Fl x
231so the actual commands are printed as they are executed.
232.El
233.It Fl e
234Let environment variables override global variables within makefiles.
235.It Fl f Ar makefile
236Specify a makefile to read instead of the default
237.Pa makefile
238or
239.Pa Makefile .
240If
241.Ar makefile
242is
243.Ql \&- ,
244standard input is read.
245Multiple makefiles may be specified, and are read in the order specified.
246.It Fl I Ar directory
247Specify a directory in which to search for makefiles and included makefiles.
248The system makefile directory (or directories, see the
249.Fl m
250option) is automatically included as part of this list.
251.It Fl i
252Ignore non-zero exit of shell commands in the makefile.
253Equivalent to specifying
254.Ql \&-
255before each command line in the makefile.
256.It Fl J Ar private
257This option should
258.Em not
259be specified by the user.
260.Pp
261When the
262.Fl j
263option is in use in a recursive build, this option is passed by a make
264to child makes to allow all the make processes in the build to
265cooperate to avoid overloading the system.
266.It Fl j Ar max_jobs
267Specify the maximum number of jobs that
268.Nm
269may have running at any one time.
270If
271.Ar max_jobs
272is a floating point number, or ends with
273.Ql C ,
274then the value is multiplied by the number of CPUs reported online by
275.Xr sysconf 3 .
276The value of
277.Ar max_jobs
278is saved in
279.Va .MAKE.JOBS .
280Turns compatibility mode off, unless the
281.Fl B
282option is also specified.
283When compatibility mode is off, all commands associated with a
284target are executed in a single shell invocation as opposed to the
285traditional one shell invocation per line.
286This can break traditional scripts which change directories on each
287command invocation and then expect to start with a fresh environment
288on the next line.
289It is more efficient to correct the scripts rather than turn backwards
290compatibility on.
291.Pp
292A job token pool with
293.Ar max_jobs
294tokens is used to control the total number of jobs running.
295Each instance of
296.Nm
297will wait for a token from the pool before running a new job.
298.It Fl k
299Continue processing after errors are encountered, but only on those targets
300that do not depend on the target whose creation caused the error.
301.It Fl m Ar directory
302Specify a directory in which to search for
303.Pa sys.mk
304and makefiles included via the
305.Li \&< Ns Ar file Ns Li \&> Ns -style
306include statement.
307The
308.Fl m
309option can be used multiple times to form a search path.
310This path overrides the default system include path
311.Pa /usr/share/mk .
312Furthermore, the system include path is appended to the search path used for
313.Li \*q Ns Ar file Ns Li \*q Ns -style
314include statements (see the
315.Fl I
316option).
317The system include path can be referenced via the read-only variable
318.Va .SYSPATH .
319.Pp
320If a directory name in the
321.Fl m
322argument (or the
323.Ev MAKESYSPATH
324environment variable) starts with the string
325.Ql \&.../ ,
326.Nm
327searches for the specified file or directory named in the remaining part
328of the argument string.
329The search starts with the current directory
330and then works upward towards the root of the file system.
331If the search is successful, the resulting directory replaces the
332.Ql \&.../
333specification in the
334.Fl m
335argument.
336This feature allows
337.Nm
338to easily search in the current source tree for customized
339.Pa sys.mk
340files (e.g., by using
341.Ql \&.../mk/sys.mk
342as an argument).
343.It Fl n
344Display the commands that would have been executed, but do not
345actually execute them unless the target depends on the
346.Va .MAKE
347special source (see below) or the command is prefixed with
348.Sq Cm + .
349.It Fl N
350Display the commands that would have been executed,
351but do not actually execute any of them;
352useful for debugging top-level makefiles
353without descending into subdirectories.
354.It Fl q
355Do not execute any commands,
356instead exit 0 if the specified targets are up to date, and 1 otherwise.
357.It Fl r
358Do not use the built-in rules specified in the system makefile.
359.It Fl S
360Stop processing if an error is encountered.
361This is the default behavior and the opposite of
362.Fl k .
363.It Fl s
364Do not echo any commands as they are executed.
365Equivalent to specifying
366.Sq Ic @
367before each command line in the makefile.
368.It Fl T Ar tracefile
369When used with the
370.Fl j
371flag,
372append a trace record to
373.Ar tracefile
374for each job started and completed.
375.It Fl t
376Rather than re-building a target as specified in the makefile, create it
377or update its modification time to make it appear up-to-date.
378.It Fl V Ar variable
379Print the value of
380.Ar variable .
381Do not build any targets.
382Multiple instances of this option may be specified;
383the variables are printed one per line,
384with a blank line for each null or undefined variable.
385The value printed is extracted from the global scope after all
386makefiles have been read.
387.Pp
388By default, the raw variable contents (which may
389include additional unexpanded variable references) are shown.
390If
391.Ar variable
392contains a
393.Ql \&$ ,
394it is not interpreted as a variable name but rather as an expression.
395Its value is expanded before printing.
396The value is also expanded before printing if
397.Va .MAKE.EXPAND_VARIABLES
398is set to true and the
399.Fl dV
400option has not been used to override it.
401.Pp
402Note that loop-local and target-local variables, as well as values
403taken temporarily by global variables during makefile processing, are
404not accessible via this option.
405The
406.Fl dv
407debug mode can be used to see these at the cost of generating
408substantial extraneous output.
409.It Fl v Ar variable
410Like
411.Fl V ,
412but all printed variables are always expanded to their complete value.
413The last occurrence of
414.Fl V
415or
416.Fl v
417decides whether all variables are expanded or not.
418.It Fl W
419Treat any warnings during makefile parsing as errors.
420.It Fl w
421Print entering and leaving directory messages, pre and post processing.
422.It Fl X
423Don't export variables passed on the command line to the environment
424individually.
425Variables passed on the command line are still exported via the
426.Ev MAKEFLAGS
427environment variable.
428This option may be useful on systems which have a small limit on the
429size of command arguments.
430.It Ar variable\| Ns Cm \&= Ns Ar value
431Set the value of the variable
432.Ar variable
433to
434.Ar value .
435Normally, all values passed on the command line are also exported to
436sub-makes in the environment.
437The
438.Fl X
439flag disables this behavior.
440Variable assignments should follow options for POSIX compatibility
441but no ordering is enforced.
442.El
443.Pp
444There are several different types of lines in a makefile: dependency
445specifications, shell commands, variable assignments, include statements,
446conditional directives, for loops, other directives, and comments.
447.Pp
448Lines may be continued from one line to the next
449by ending them with a backslash
450.Pq Ql \e .
451The trailing newline character and initial whitespace on the following
452line are compressed into a single space.
453.Sh FILE DEPENDENCY SPECIFICATIONS
454Dependency lines consist of one or more targets, an operator, and zero
455or more sources.
456This creates a relationship where the targets
457.Dq depend
458on the sources and are customarily created from them.
459A target is considered out of date if it does not exist,
460or if its modification time is less than that of any of its sources.
461An out-of-date target is re-created, but not until all sources
462have been examined and themselves re-created as needed.
463Three operators may be used:
464.Bl -tag -width flag
465.It Ic \&:
466Many dependency lines may name this target but only one may have
467attached shell commands.
468All sources named in all dependency lines are considered together,
469and if needed the attached shell commands are run to create or
470re-create the target.
471If
472.Nm
473is interrupted, the target is removed.
474.It Ic \&!
475The same, but the target is always re-created whether or not it is out
476of date.
477.It Ic \&::
478Any dependency line may have attached shell commands, but each one
479is handled independently: its sources are considered and the attached
480shell commands are run if the target is out of date with respect to
481(only) those sources.
482Thus, different groups of the attached shell commands may be run
483depending on the circumstances.
484Furthermore, unlike
485.Ic \&: ,
486for dependency lines with no sources, the attached shell
487commands are always run.
488Also unlike
489.Ic \&: ,
490the target is not removed if
491.Nm
492is interrupted.
493.El
494.Pp
495All dependency lines mentioning a particular target must use the same
496operator.
497.Pp
498Targets and sources may contain the shell wildcard values
499.Ql \&? ,
500.Ql * ,
501.Ql [] ,
502and
503.Ql {} .
504The values
505.Ql \&? ,
506.Ql * ,
507and
508.Ql []
509may only be used as part of the final component of the target or source,
510and only match existing files.
511The value
512.Ql {}
513need not necessarily be used to describe existing files.
514Expansion is in directory order, not alphabetically as done in the shell.
515.Sh SHELL COMMANDS
516Each target may have associated with it one or more lines of shell commands,
517normally used to create the target.
518Each of the lines in this script
519.Em must
520be preceded by a tab.
521(For historical reasons, spaces are not accepted.)
522While targets can occur in many dependency lines if desired,
523by default only one of these rules may be followed by a creation script.
524If the
525.Sq Ic \&::
526operator is used, however, all rules may include scripts,
527and the respective scripts are executed in the order found.
528.Pp
529Each line is treated as a separate shell command,
530unless the end of line is escaped with a backslash
531.Ql \e ,
532in which case that line and the next are combined.
533If the first characters of the command are any combination of
534.Sq Ic @ ,
535.Sq Ic + ,
536or
537.Sq Ic \- ,
538the command is treated specially.
539.Bl -tag -offset indent -width indent
540.It Ic @
541causes the command not to be echoed before it is executed.
542.It Ic +
543causes the command to be executed even when
544.Fl n
545is given.
546This is similar to the effect of the
547.Va .MAKE
548special source,
549except that the effect can be limited to a single line of a script.
550.It Ic \-
551in compatibility mode
552causes any non-zero exit status of the command line to be ignored.
553.El
554.Pp
555When
556.Nm
557is run in jobs mode with
558.Fl j Ar max_jobs ,
559the entire script for the target is fed to a single instance of the shell.
560In compatibility (non-jobs) mode, each command is run in a separate process.
561If the command contains any shell meta characters
562.Pq Ql #=|^(){};&<>*?[]:$`\e\en ,
563it is passed to the shell; otherwise
564.Nm
565attempts direct execution.
566If a line starts with
567.Sq Ic \-
568and the shell has ErrCtl enabled,
569failure of the command line is ignored as in compatibility mode.
570Otherwise
571.Sq Ic \-
572affects the entire job;
573the script stops at the first command line that fails,
574but the target is not deemed to have failed.
575.Pp
576Makefiles should be written so that the mode of
577.Nm
578operation does not change their behavior.
579For example, any command which uses
580.Dq cd
581or
582.Dq chdir
583without the intention of changing the directory for subsequent commands
584should be put in parentheses so it executes in a subshell.
585To force the use of a single shell, escape the line breaks so as to make
586the whole script one command.
587For example:
588.Bd -literal -offset indent
589avoid-chdir-side-effects:
590	@echo "Building $@ in $$(pwd)"
591	@(cd ${.CURDIR} && ${MAKE} $@)
592	@echo "Back in $$(pwd)"
593
594ensure-one-shell-regardless-of-mode:
595	@echo "Building $@ in $$(pwd)"; \e
596	(cd ${.CURDIR} && ${MAKE} $@); \e
597	echo "Back in $$(pwd)"
598.Ed
599.Pp
600Since
601.Nm
602changes the current working directory to
603.Sq Va .OBJDIR
604before executing any targets,
605each child process starts with that as its current working directory.
606.Sh VARIABLE ASSIGNMENTS
607Variables in make behave much like macros in the C preprocessor.
608.Pp
609Variable assignments have the form
610.Sq Ar NAME Ar op Ar value ,
611where:
612.Bl -tag -offset Ds -width Ds
613.It Ar NAME
614is a single-word variable name,
615consisting, by tradition, of all upper-case letters,
616.It Ar op
617is one of the variable assignment operators described below, and
618.It Ar value
619is interpreted according to the variable assignment operator.
620.El
621.Pp
622Whitespace around
623.Ar NAME ,
624.Ar op
625and
626.Ar value
627is discarded.
628.Ss Variable assignment operators
629The five operators that assign values to variables are:
630.Bl -tag -width Ds
631.It Ic \&=
632Assign the value to the variable.
633Any previous value is overwritten.
634.It Ic \&+=
635Append the value to the current value of the variable,
636separating them by a single space.
637.It Ic \&?=
638Assign the value to the variable if it is not already defined.
639.It Ic \&:=
640Expand the value, then assign it to the variable.
641.Pp
642.Em NOTE :
643References to undefined variables are
644.Em not
645expanded.
646This can cause problems when variable modifiers are used.
647.\" See var-op-expand.mk, the section with LATER and INDIRECT.
648.It Ic \&!=
649Expand the value and pass it to the shell for execution,
650then assign the output from the child's standard output to the variable.
651Any newlines in the result are replaced with spaces.
652.El
653.Ss Expansion of variables
654In most contexts where variables are expanded,
655.Ql \&$$
656expands to a single dollar sign.
657In other contexts (most variable modifiers, string literals in conditions),
658.Ql \&\e$
659expands to a single dollar sign.
660.Pp
661References to variables have the form
662.Cm \&${ Ns Ar name Ns Oo Ns Cm \&: Ns Ar modifiers Oc Ns Cm \&}
663or
664.Cm \&$( Ns Ar name Ns Oo Ns Cm \&: Ns Ar modifiers Oc Ns Cm \&) .
665If the variable name consists of only a single character
666and the expression contains no modifiers,
667the surrounding curly braces or parentheses are not required.
668This shorter form is not recommended.
669.Pp
670If the variable name contains a dollar, the name itself is expanded first.
671This allows almost arbitrary variable names, however names containing dollar,
672braces, parentheses or whitespace are really best avoided.
673.Pp
674If the result of expanding a nested variable expression contains a dollar sign
675.Pq Ql \&$ ,
676the result is subject to further expansion.
677.Pp
678Variable substitution occurs at four distinct times, depending on where
679the variable is being used.
680.Bl -enum
681.It
682Variables in dependency lines are expanded as the line is read.
683.It
684Variables in conditionals are expanded individually,
685but only as far as necessary to determine the result of the conditional.
686.It
687Variables in shell commands are expanded when the shell command is
688executed.
689.It
690.Ic .for
691loop index variables are expanded on each loop iteration.
692Note that other variables are not expanded when composing the body of a loop,
693so the following example code:
694.Bd -literal -offset indent
695\&.for i in 1 2 3
696a+=     ${i}
697j=      ${i}
698b+=     ${j}
699\&.endfor
700
701all:
702	@echo ${a}
703	@echo ${b}
704.Ed
705.Pp
706prints:
707.Bd -literal -offset indent
7081 2 3
7093 3 3
710.Ed
711.Pp
712After the loop is executed:
713.Bl -tag -offset indent -width indent
714.It Va a
715contains
716.Ql ${:U1} ${:U2} ${:U3} ,
717which expands to
718.Ql 1 2 3 .
719.It Va j
720contains
721.Ql ${:U3} ,
722which expands to
723.Ql 3 .
724.It Va b
725contains
726.Ql ${j} ${j} ${j} ,
727which expands to
728.Ql ${:U3} ${:U3} ${:U3}
729and further to
730.Ql 3 3 3 .
731.El
732.El
733.Ss Variable classes
734The four different classes of variables (in order of increasing precedence)
735are:
736.Bl -tag -width Ds
737.It Environment variables
738Variables defined as part of
739.Nm Ns 's
740environment.
741.It Global variables
742Variables defined in the makefile or in included makefiles.
743.It Command line variables
744Variables defined as part of the command line.
745.It Local variables
746Variables that are defined specific to a certain target.
747.El
748.Pp
749Local variables can be set on a dependency line, unless
750.Va .MAKE.TARGET_LOCAL_VARIABLES
751is set to
752.Ql false .
753The rest of the line
754(which already has had global variables expanded)
755is the variable value.
756For example:
757.Bd -literal -offset indent
758COMPILER_WRAPPERS= ccache distcc icecc
759
760${OBJS}: .MAKE.META.CMP_FILTER=${COMPILER_WRAPPERS:S,^,N,}
761.Ed
762.Pp
763Only the targets
764.Ql ${OBJS}
765are impacted by that filter (in
766.Dq meta
767mode) and
768simply enabling/disabling any of the compiler wrappers does not render all
769of those targets out-of-date.
770.Pp
771.Em NOTE :
772target-local variable assignments behave differently in that;
773.Bl -tag -width Ds -offset indent
774.It Ic \&+=
775Only appends to a previous local assignment
776for the same target and variable.
777.It Ic \&:=
778Is redundant with respect to global variables,
779which have already been expanded.
780.El
781.Pp
782The seven built-in local variables are:
783.Bl -tag -width ".Va .ARCHIVE" -offset indent
784.It Va .ALLSRC
785The list of all sources for this target; also known as
786.Sq Va \&> .
787.It Va .ARCHIVE
788The name of the archive file; also known as
789.Sq Va \&! .
790.It Va .IMPSRC
791In suffix-transformation rules, the name/path of the source from which the
792target is to be transformed (the
793.Dq implied
794source); also known as
795.Sq Va \&< .
796It is not defined in explicit rules.
797.It Va .MEMBER
798The name of the archive member; also known as
799.Sq Va % .
800.It Va .OODATE
801The list of sources for this target that were deemed out-of-date; also
802known as
803.Sq Va \&? .
804.It Va .PREFIX
805The name of the target with suffix (if declared in
806.Ic .SUFFIXES )
807removed; also known as
808.Sq Va * .
809.It Va .TARGET
810The name of the target; also known as
811.Sq Va @ .
812For compatibility with other makes this is an alias for
813.Va .ARCHIVE
814in archive member rules.
815.El
816.Pp
817The shorter forms
818.Po
819.Sq Va \&> ,
820.Sq Va \&! ,
821.Sq Va \&< ,
822.Sq Va \&% ,
823.Sq Va \&? ,
824.Sq Va \&* ,
825and
826.Sq Va \&@
827.Pc
828are permitted for backward
829compatibility with historical makefiles and legacy POSIX make and are
830not recommended.
831.Pp
832Variants of these variables with the punctuation followed immediately by
833.Ql D
834or
835.Ql F ,
836e.g.\&
837.Ql $(@D) ,
838are legacy forms equivalent to using the
839.Ql :H
840and
841.Ql :T
842modifiers.
843These forms are accepted for compatibility with
844.At V
845makefiles and POSIX but are not recommended.
846.Pp
847Four of the local variables may be used in sources on dependency lines
848because they expand to the proper value for each target on the line.
849These variables are
850.Sq Va .TARGET ,
851.Sq Va .PREFIX ,
852.Sq Va .ARCHIVE ,
853and
854.Sq Va .MEMBER .
855.Ss Additional built-in variables
856In addition,
857.Nm
858sets or knows about the following variables:
859.Bl -tag
860.\" NB: This list is sorted case-insensitive, ignoring punctuation.
861.\" NB: To find all built-in variables in make's source code,
862.\" NB: search for Var_*, Global_*, SetVarObjdir, GetBooleanExpr,
863.\" NB: and the implementation of Var_SetWithFlags.
864.\" NB: Last synced on 2023-01-01.
865.It Va .ALLTARGETS
866The list of all targets encountered in the makefiles.
867If evaluated during makefile parsing,
868lists only those targets encountered thus far.
869.It Va .CURDIR
870A path to the directory where
871.Nm
872was executed.
873Refer to the description of
874.Sq Va PWD
875for more details.
876.It Va .ERROR_CMD
877Is used in error handling, see
878.Va MAKE_PRINT_VAR_ON_ERROR .
879.It Va .ERROR_CWD
880Is used in error handling, see
881.Va MAKE_PRINT_VAR_ON_ERROR .
882.It Va .ERROR_EXIT
883Is used in error handling, see
884.Va MAKE_PRINT_VAR_ON_ERROR .
885.It Va .ERROR_META_FILE
886Is used in error handling in
887.Dq meta
888mode, see
889.Va MAKE_PRINT_VAR_ON_ERROR .
890.It Va .ERROR_TARGET
891Is used in error handling, see
892.Va MAKE_PRINT_VAR_ON_ERROR .
893.It Va .INCLUDEDFROMDIR
894The directory of the file this makefile was included from.
895.It Va .INCLUDEDFROMFILE
896The filename of the file this makefile was included from.
897.\" .INCLUDES is intentionally undocumented, as it is obsolete.
898.\" .LIBS is intentionally undocumented, as it is obsolete.
899.It Va MACHINE
900The machine hardware name, see
901.Xr uname 1 .
902.It Va MACHINE_ARCH
903The machine processor architecture name, see
904.Xr uname 1 .
905.It Va MAKE
906The name that
907.Nm
908was executed with
909.Pq Va argv[0] .
910.It Va .MAKE
911The same as
912.Va MAKE ,
913for compatibility.
914The preferred variable to use is the environment variable
915.Ev MAKE
916because it is more compatible with other make variants
917and cannot be confused with the special target with the same name.
918.It Va .MAKE.ALWAYS_PASS_JOB_QUEUE
919Tells
920.Nm
921whether to pass the descriptors of the job token queue
922even if the target is not tagged with
923.Ic .MAKE
924The default is
925.Ql Pa yes
926for backwards compatability with
927.Fx 9.0
928and earlier.
929.\" '.MAKE.cmd_filtered' is intentionally undocumented,
930.\" as it is an internal implementation detail.
931.It Va .MAKE.DEPENDFILE
932Names the makefile (default
933.Sq Pa .depend )
934from which generated dependencies are read.
935.It Va .MAKE.DIE_QUIETLY
936If set to
937.Ql true ,
938do not print error information at the end.
939.It Va .MAKE.EXPAND_VARIABLES
940A boolean that controls the default behavior of the
941.Fl V
942option.
943If true, variable values printed with
944.Fl V
945are fully expanded; if false, the raw variable contents (which may
946include additional unexpanded variable references) are shown.
947.It Va .MAKE.EXPORTED
948The list of variables exported by
949.Nm .
950.It Va MAKEFILE
951The top-level makefile that is currently read,
952as given in the command line.
953.It Va .MAKEFLAGS
954The environment variable
955.Sq Ev MAKEFLAGS
956may contain anything that
957may be specified on
958.Nm Ns 's
959command line.
960Anything specified on
961.Nm Ns 's
962command line is appended to the
963.Va .MAKEFLAGS
964variable, which is then added to the environment for all programs that
965.Nm
966executes.
967.It Va .MAKE.GID
968The numeric group ID of the user running
969.Nm .
970It is read-only.
971.It Va .MAKE.JOB.PREFIX
972If
973.Nm
974is run with
975.Fl j ,
976the output for each target is prefixed with a token
977.Dl --- Ar target Li ---
978the first part of which can be controlled via
979.Va .MAKE.JOB.PREFIX .
980If
981.Va .MAKE.JOB.PREFIX
982is empty, no token is printed.
983For example, setting
984.Va .MAKE.JOB.PREFIX
985to
986.Ql ${.newline}---${.MAKE:T}[${.MAKE.PID}]
987would produce tokens like
988.Dl ---make[1234] Ar target Li ---
989making it easier to track the degree of parallelism being achieved.
990.It Va .MAKE.JOBS
991The argument to the
992.Fl j
993option.
994.It Va .MAKE.JOBS.C
995A read-only boolean that indicates whether the
996.Fl j
997option supports use of
998.Ql C .
999.It Va .MAKE.LEVEL
1000The recursion depth of
1001.Nm .
1002The top-level instance of
1003.Nm
1004has level 0, and each child make has its parent level plus 1.
1005This allows tests like:
1006.Li .if ${.MAKE.LEVEL} == 0
1007to protect things which should only be evaluated in the top-level instance of
1008.Nm .
1009.It Va .MAKE.LEVEL.ENV
1010The name of the environment variable that stores the level of nested calls to
1011.Nm .
1012.It Va .MAKE.MAKEFILE_PREFERENCE
1013The ordered list of makefile names
1014(default
1015.Sq Pa makefile ,
1016.Sq Pa Makefile )
1017that
1018.Nm
1019looks for.
1020.It Va .MAKE.MAKEFILES
1021The list of makefiles read by
1022.Nm ,
1023which is useful for tracking dependencies.
1024Each makefile is recorded only once, regardless of the number of times read.
1025.It Va .MAKE.META.BAILIWICK
1026In
1027.Dq meta
1028mode, provides a list of prefixes which
1029match the directories controlled by
1030.Nm .
1031If a file that was generated outside of
1032.Va .OBJDIR
1033but within said bailiwick is missing,
1034the current target is considered out-of-date.
1035.It Va .MAKE.META.CMP_FILTER
1036In
1037.Dq meta
1038mode, it can (very rarely!) be useful to filter command
1039lines before comparison.
1040This variable can be set to a set of modifiers that are applied to
1041each line of the old and new command that differ, if the filtered
1042commands still differ, the target is considered out-of-date.
1043.It Va .MAKE.META.CREATED
1044In
1045.Dq meta
1046mode, this variable contains a list of all the meta files
1047updated.
1048If not empty, it can be used to trigger processing of
1049.Va .MAKE.META.FILES .
1050.It Va .MAKE.META.FILES
1051In
1052.Dq meta
1053mode, this variable contains a list of all the meta files
1054used (updated or not).
1055This list can be used to process the meta files to extract dependency
1056information.
1057.It Va .MAKE.META.IGNORE_FILTER
1058Provides a list of variable modifiers to apply to each pathname.
1059Ignore if the expansion is an empty string.
1060.It Va .MAKE.META.IGNORE_PATHS
1061Provides a list of path prefixes that should be ignored;
1062because the contents are expected to change over time.
1063The default list includes:
1064.Sq Pa /dev /etc /proc /tmp /var/run /var/tmp
1065.It Va .MAKE.META.IGNORE_PATTERNS
1066Provides a list of patterns to match against pathnames.
1067Ignore any that match.
1068.It Va .MAKE.META.PREFIX
1069Defines the message printed for each meta file updated in
1070.Dq meta verbose
1071mode.
1072The default value is:
1073.Dl Building ${.TARGET:H:tA}/${.TARGET:T}
1074.It Va .MAKE.MODE
1075Processed after reading all makefiles.
1076Affects the mode that
1077.Nm
1078runs in.
1079It can contain these keywords:
1080.Bl -tag -width indent
1081.It Cm compat
1082Like
1083.Fl B ,
1084puts
1085.Nm
1086into
1087.Dq compat
1088mode.
1089.It Cm meta
1090Puts
1091.Nm
1092into
1093.Dq meta
1094mode, where meta files are created for each target
1095to capture the command run, the output generated, and if
1096.Xr filemon 4
1097is available, the system calls which are of interest to
1098.Nm .
1099The captured output can be useful when diagnosing errors.
1100.It Cm curdirOk= Ns Ar bf
1101By default,
1102.Nm
1103does not create
1104.Pa .meta
1105files in
1106.Sq Va .CURDIR .
1107This can be overridden by setting
1108.Ar bf
1109to a value which represents true.
1110.It Cm missing-meta= Ns Ar bf
1111If
1112.Ar bf
1113is true, a missing
1114.Pa .meta
1115file makes the target out-of-date.
1116.It Cm missing-filemon= Ns Ar bf
1117If
1118.Ar bf
1119is true, missing filemon data makes the target out-of-date.
1120.It Cm nofilemon
1121Do not use
1122.Xr filemon 4 .
1123.It Cm env
1124For debugging, it can be useful to include the environment
1125in the
1126.Pa .meta
1127file.
1128.It Cm verbose
1129If in
1130.Dq meta
1131mode, print a clue about the target being built.
1132This is useful if the build is otherwise running silently.
1133The message printed is the expanded value of
1134.Va .MAKE.META.PREFIX .
1135.It Cm ignore-cmd
1136Some makefiles have commands which are simply not stable.
1137This keyword causes them to be ignored for
1138determining whether a target is out of date in
1139.Dq meta
1140mode.
1141See also
1142.Ic .NOMETA_CMP .
1143.It Cm silent= Ns Ar bf
1144If
1145.Ar bf
1146is true, when a .meta file is created, mark the target
1147.Ic .SILENT .
1148.It Cm randomize-targets
1149In both compat and parallel mode, do not make the targets in the usual order,
1150but instead randomize their order.
1151This mode can be used to detect undeclared dependencies between files.
1152.El
1153.It Va MAKEOBJDIR
1154Used to create files in a separate directory, see
1155.Va .OBJDIR .
1156.It Va MAKE_OBJDIR_CHECK_WRITABLE
1157When true,
1158.Nm
1159will check that
1160.Va .OBJDIR
1161is writable, and issue a warning if not.
1162.It Va MAKE_DEBUG_OBJDIR_CHECK_WRITABLE
1163When true and
1164.Nm
1165is warning about an unwritable
1166.Va .OBJDIR ,
1167report the variables listed in
1168.Va MAKE_PRINT_VAR_ON_ERROR
1169to help debug.
1170.It Va MAKEOBJDIRPREFIX
1171Used to create files in a separate directory, see
1172.Va .OBJDIR .
1173.It Va .MAKE.OS
1174The name of the operating system, see
1175.Xr uname 1 .
1176It is read-only.
1177.It Va .MAKEOVERRIDES
1178This variable is used to record the names of variables assigned to
1179on the command line, so that they may be exported as part of
1180.Sq Ev MAKEFLAGS .
1181This behavior can be disabled by assigning an empty value to
1182.Sq Va .MAKEOVERRIDES
1183within a makefile.
1184Extra variables can be exported from a makefile
1185by appending their names to
1186.Sq Va .MAKEOVERRIDES .
1187.Sq Ev MAKEFLAGS
1188is re-exported whenever
1189.Sq Va .MAKEOVERRIDES
1190is modified.
1191.It Va .MAKE.PATH_FILEMON
1192If
1193.Nm
1194was built with
1195.Xr filemon 4
1196support, this is set to the path of the device node.
1197This allows makefiles to test for this support.
1198.It Va .MAKE.PID
1199The process ID of
1200.Nm .
1201It is read-only.
1202.It Va .MAKE.PPID
1203The parent process ID of
1204.Nm .
1205It is read-only.
1206.It Va MAKE_PRINT_VAR_ON_ERROR
1207When
1208.Nm
1209stops due to an error, it sets
1210.Sq Va .ERROR_TARGET
1211to the name of the target that failed,
1212.Sq Va .ERROR_EXIT
1213to the exit status of the failed target,
1214.Sq Va .ERROR_CMD
1215to the commands of the failed target,
1216and in
1217.Dq meta
1218mode, it also sets
1219.Sq Va .ERROR_CWD
1220to the
1221.Xr getcwd 3 ,
1222and
1223.Sq Va .ERROR_META_FILE
1224to the path of the meta file (if any) describing the failed target.
1225It then prints its name and the value of
1226.Sq Va .CURDIR
1227as well as the value of any variables named in
1228.Sq Va MAKE_PRINT_VAR_ON_ERROR .
1229.It Va .MAKE.SAVE_DOLLARS
1230If true,
1231.Ql $$
1232are preserved when doing
1233.Ql :=
1234assignments.
1235The default is false, for backwards compatibility.
1236Set to true for compatability with other makes.
1237If set to false,
1238.Ql $$
1239becomes
1240.Ql $
1241per normal evaluation rules.
1242.It Va .MAKE.TARGET_LOCAL_VARIABLES
1243If set to
1244.Ql false ,
1245apparent variable assignments in dependency lines are
1246treated as normal sources.
1247.It Va .MAKE.UID
1248The numeric ID of the user running
1249.Nm .
1250It is read-only.
1251.\" 'MAKE_VERSION' is intentionally undocumented
1252.\" since it is only defined in the bmake distribution,
1253.\" but not in NetBSD's native make.
1254.\" '.meta.%d.lcwd' is intentionally undocumented
1255.\" since it is an internal implementation detail.
1256.\" '.meta.%d.ldir' is intentionally undocumented
1257.\" since it is an internal implementation detail.
1258.\" 'MFLAGS' is intentionally undocumented
1259.\" since it is obsolete.
1260.It Va .newline
1261This variable is simply assigned a newline character as its value.
1262It is read-only.
1263This allows expansions using the
1264.Cm \&:@
1265modifier to put a newline between
1266iterations of the loop rather than a space.
1267For example, in case of an error,
1268.Nm
1269prints the variable names and their values using:
1270.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
1271.It Va .OBJDIR
1272A path to the directory where the targets are built.
1273Its value is determined by trying to
1274.Xr chdir 2
1275to the following directories in order and using the first match:
1276.Bl -enum
1277.It
1278.Cm ${MAKEOBJDIRPREFIX} Ns Cm ${.CURDIR}
1279.Pp
1280(Only if
1281.Sq Ev MAKEOBJDIRPREFIX
1282is set in the environment or on the command line.)
1283.It
1284.Cm ${MAKEOBJDIR}
1285.Pp
1286(Only if
1287.Sq Ev MAKEOBJDIR
1288is set in the environment or on the command line.)
1289.It
1290.Cm ${.CURDIR} Ns Pa /obj. Ns Cm ${MACHINE}
1291.It
1292.Cm ${.CURDIR} Ns Pa /obj
1293.It
1294.Pa /usr/obj/ Ns Cm ${.CURDIR}
1295.It
1296.Cm ${.CURDIR}
1297.El
1298.Pp
1299Variable expansion is performed on the value before it is used,
1300so expressions such as
1301.Cm ${.CURDIR:S,^/usr/src,/var/obj,}
1302may be used.
1303This is especially useful with
1304.Sq Ev MAKEOBJDIR .
1305.Pp
1306.Sq Va .OBJDIR
1307may be modified in the makefile via the special target
1308.Sq Ic .OBJDIR .
1309In all cases,
1310.Nm
1311changes to the specified directory if it exists, and sets
1312.Sq Va .OBJDIR
1313and
1314.Sq Va PWD
1315to that directory before executing any targets.
1316.Pp
1317Except in the case of an explicit
1318.Sq Ic .OBJDIR
1319target,
1320.Nm
1321checks that the specified directory is writable and ignores it if not.
1322This check can be skipped by setting the environment variable
1323.Sq Ev MAKE_OBJDIR_CHECK_WRITABLE
1324to
1325.Dq no .
1326.It Va .PARSEDIR
1327The directory name of the current makefile being parsed.
1328.It Va .PARSEFILE
1329The basename of the current makefile being parsed.
1330This variable and
1331.Sq Va .PARSEDIR
1332are both set only while the makefiles are being parsed.
1333To retain their current values,
1334assign them to a variable using assignment with expansion
1335.Sq Cm \&:= .
1336.It Va .PATH
1337The space-separated list of directories that
1338.Nm
1339searches for files.
1340To update this search list, use the special target
1341.Sq Ic .PATH
1342rather than modifying the variable directly.
1343.It Va %POSIX
1344Is set in POSIX mode, see the special
1345.Ql Va .POSIX
1346target.
1347.\" XXX: There is no make variable named 'PWD',
1348.\" XXX: make only reads and writes the environment variable 'PWD'.
1349.It Va PWD
1350Alternate path to the current directory.
1351.Nm
1352normally sets
1353.Sq Va .CURDIR
1354to the canonical path given by
1355.Xr getcwd 3 .
1356However, if the environment variable
1357.Sq Ev PWD
1358is set and gives a path to the current directory,
1359.Nm
1360sets
1361.Sq Va .CURDIR
1362to the value of
1363.Sq Ev PWD
1364instead.
1365This behavior is disabled if
1366.Sq Ev MAKEOBJDIRPREFIX
1367is set or
1368.Sq Ev MAKEOBJDIR
1369contains a variable transform.
1370.Sq Va PWD
1371is set to the value of
1372.Sq Va .OBJDIR
1373for all programs which
1374.Nm
1375executes.
1376.It Va .SHELL
1377The pathname of the shell used to run target scripts.
1378It is read-only.
1379.It Va .SUFFIXES
1380The list of known suffixes.
1381It is read-only.
1382.It Va .SYSPATH
1383The space-separated list of directories that
1384.Nm
1385searches for makefiles, referred to as the system include path.
1386To update this search list, use the special target
1387.Sq Ic .SYSPATH
1388rather than modifying the variable which is read-only.
1389.It Va .TARGETS
1390The list of targets explicitly specified on the command line, if any.
1391.It Va VPATH
1392The colon-separated
1393.Pq Dq \&:
1394list of directories that
1395.Nm
1396searches for files.
1397This variable is supported for compatibility with old make programs only, use
1398.Sq Va .PATH
1399instead.
1400.El
1401.Ss Variable modifiers
1402The general format of a variable expansion is:
1403.Pp
1404.Sm off
1405.D1 Ic \&${ Ar variable\| Oo Ic \&: Ar modifier\| Oo Ic \&: No ... Oc Oc Ic \&}
1406.Sm on
1407.Pp
1408Each modifier begins with a colon.
1409To escape a colon, precede it with a backslash
1410.Ql \e .
1411.Pp
1412A list of indirect modifiers can be specified via a variable, as follows:
1413.Pp
1414.Bd -literal -offset indent
1415.Ar modifier_variable\^ Li \&= Ar modifier Ns Oo Ic \&: Ns No ... Oc
1416
1417.Sm off
1418.Ic \&${ Ar variable Ic \&:${ Ar modifier_variable Ic \&} Oo Ic \&: No ... Oc Ic \&}
1419.Sm on
1420.Ed
1421.Pp
1422In this case, the first modifier in the
1423.Ar modifier_variable
1424does not start with a colon,
1425since that colon already occurs in the referencing variable.
1426If any of the modifiers in the
1427.Ar modifier_variable
1428contains a dollar sign
1429.Pq Ql $ ,
1430these must be doubled to avoid early expansion.
1431.Pp
1432Some modifiers interpret the expression value as a single string,
1433others treat the expression value as a whitespace-separated list of words.
1434When splitting a string into words,
1435whitespace can be escaped using double quotes, single quotes and backslashes,
1436like in the shell.
1437The quotes and backslashes are retained in the words.
1438.Pp
1439The supported modifiers are:
1440.Bl -tag -width EEE
1441.It Cm \&:E
1442Replaces each word with its suffix.
1443.It Cm \&:H
1444Replaces each word with its dirname.
1445.It Cm \&:M\| Ns Ar pattern
1446Selects only those words that match
1447.Ar pattern .
1448The standard shell wildcard characters
1449.Pf ( Ql * ,
1450.Ql \&? ,
1451and
1452.Ql \&[] )
1453may
1454be used.
1455The wildcard characters may be escaped with a backslash
1456.Pq Ql \e .
1457As a consequence of the way values are split into words, matched,
1458and then joined, the construct
1459.Ql ${VAR:M*}
1460removes all leading and trailing whitespace
1461and normalizes the inter-word spacing to a single space.
1462.It Cm \&:N\| Ns Ar pattern
1463This is the opposite of
1464.Sq Cm \&:M ,
1465selecting all words which do
1466.Em not
1467match
1468.Ar pattern .
1469.It Cm \&:O
1470Orders the words lexicographically.
1471.It Cm \&:On
1472Orders the words numerically.
1473A number followed by one of
1474.Ql k ,
1475.Ql M
1476or
1477.Ql G
1478is multiplied by the appropriate factor, which is 1024 for
1479.Ql k ,
14801048576 for
1481.Ql M ,
1482or 1073741824 for
1483.Ql G .
1484Both upper- and lower-case letters are accepted.
1485.It Cm \&:Or
1486Orders the words in reverse lexicographical order.
1487.It Cm \&:Orn
1488Orders the words in reverse numerical order.
1489.It Cm \&:Ox
1490Shuffles the words.
1491The results are different each time you are referring to the
1492modified variable; use the assignment with expansion
1493.Sq Cm \&:=
1494to prevent such behavior.
1495For example,
1496.Bd -literal -offset indent
1497LIST=			uno due tre quattro
1498RANDOM_LIST=		${LIST:Ox}
1499STATIC_RANDOM_LIST:=	${LIST:Ox}
1500
1501all:
1502	@echo "${RANDOM_LIST}"
1503	@echo "${RANDOM_LIST}"
1504	@echo "${STATIC_RANDOM_LIST}"
1505	@echo "${STATIC_RANDOM_LIST}"
1506.Ed
1507may produce output similar to:
1508.Bd -literal -offset indent
1509quattro due tre uno
1510tre due quattro uno
1511due uno quattro tre
1512due uno quattro tre
1513.Ed
1514.It Cm \&:Q
1515Quotes every shell meta-character in the value, so that it can be passed
1516safely to the shell.
1517.It Cm \&:q
1518Quotes every shell meta-character in the value, and also doubles
1519.Sq $
1520characters so that it can be passed
1521safely through recursive invocations of
1522.Nm .
1523This is equivalent to
1524.Sq Cm \&:S/\e\&$/&&/g:Q .
1525.It Cm \&:R
1526Replaces each word with everything but its suffix.
1527.It Cm \&:range Ns Oo Cm = Ns Ar count Oc
1528The value is an integer sequence representing the words of the original
1529value, or the supplied
1530.Ar count .
1531.It Cm \&:gmtime Ns Oo Cm = Ns Ar timestamp Oc
1532The value is interpreted as a format string for
1533.Xr strftime 3 ,
1534using
1535.Xr gmtime 3 ,
1536producing the formatted timestamp.
1537Note: the
1538.Ql %s
1539format should only be used with
1540.Sq Cm \&:localtime .
1541If a
1542.Ar timestamp
1543value is not provided or is 0, the current time is used.
1544.It Cm \&:hash
1545Computes a 32-bit hash of the value and encodes it as 8 hex digits.
1546.It Cm \&:localtime Ns Oo Cm = Ns Ar timestamp Oc
1547The value is interpreted as a format string for
1548.Xr strftime 3 ,
1549using
1550.Xr localtime 3 ,
1551producing the formatted timestamp.
1552If a
1553.Ar timestamp
1554value is not provided or is 0, the current time is used.
1555.It Cm \&:mtime Ns Oo Cm = Ns Ar timestamp Oc
1556Call
1557.Xr stat 2
1558with each word as pathname;
1559use
1560.Ql st_mtime
1561as the new value.
1562If
1563.Xr stat 2
1564fails; use
1565.Ar timestamp
1566or current time.
1567If
1568.Ar timestamp
1569is set to
1570.Ql error ,
1571then
1572.Xr stat 2
1573failure will cause an error.
1574.It Cm \&:tA
1575Attempts to convert the value to an absolute path using
1576.Xr realpath 3 .
1577If that fails, the value is unchanged.
1578.It Cm \&:tl
1579Converts the value to lower-case letters.
1580.It Cm \&:ts Ns Ar c
1581When joining the words after a modifier that treats the value as words,
1582the words are normally separated by a space.
1583This modifier changes the separator to the character
1584.Ar c .
1585If
1586.Ar c
1587is omitted, no separator is used.
1588The common escapes (including octal numeric codes) work as expected.
1589.It Cm \&:tt
1590Converts the first character of each word to upper-case,
1591and the rest to lower-case letters.
1592.It Cm \&:tu
1593Converts the value to upper-case letters.
1594.It Cm \&:tW
1595Causes subsequent modifiers to treat the value as a single word
1596(possibly containing embedded whitespace).
1597See also
1598.Sq Cm \&:[*] .
1599.It Cm \&:tw
1600Causes the value to be treated as a list of words.
1601See also
1602.Sq Cm \&:[@] .
1603.Sm off
1604.It Cm \&:S\| No \&/ Ar old_string\| No \&/ Ar new_string\| No \&/ Op Cm 1gW
1605.Sm on
1606Modifies the first occurrence of
1607.Ar old_string
1608in each word of the value, replacing it with
1609.Ar new_string .
1610If a
1611.Ql g
1612is appended to the last delimiter of the pattern,
1613all occurrences in each word are replaced.
1614If a
1615.Ql 1
1616is appended to the last delimiter of the pattern,
1617only the first occurrence is affected.
1618If a
1619.Ql W
1620is appended to the last delimiter of the pattern,
1621the value is treated as a single word.
1622If
1623.Ar old_string
1624begins with a caret
1625.Pq Ql ^ ,
1626.Ar old_string
1627is anchored at the beginning of each word.
1628If
1629.Ar old_string
1630ends with a dollar sign
1631.Pq Ql \&$ ,
1632it is anchored at the end of each word.
1633Inside
1634.Ar new_string ,
1635an ampersand
1636.Pq Ql &
1637is replaced by
1638.Ar old_string
1639(without the anchoring
1640.Ql ^
1641or
1642.Ql \&$ ) .
1643Any character may be used as the delimiter for the parts of the modifier
1644string.
1645The anchoring, ampersand and delimiter characters can be escaped with a
1646backslash
1647.Pq Ql \e .
1648.Pp
1649Both
1650.Ar old_string
1651and
1652.Ar new_string
1653may contain nested expressions.
1654To prevent a dollar sign from starting a nested expression,
1655escape it with a backslash.
1656.Sm off
1657.It Cm \&:C\| No \&/ Ar pattern\| No \&/ Ar replacement\| No \&/ Op Cm 1gW
1658.Sm on
1659The
1660.Cm \&:C
1661modifier works like the
1662.Cm \&:S
1663modifier except that the old and new strings, instead of being
1664simple strings, are an extended regular expression
1665.Ar pattern
1666(see
1667.Xr regex 3 )
1668and an
1669.Xr ed 1 Ns \-style
1670.Ar replacement .
1671Normally, the first occurrence of the pattern
1672.Ar pattern
1673in each word of the value is substituted with
1674.Ar replacement .
1675The
1676.Ql 1
1677modifier causes the substitution to apply to at most one word; the
1678.Ql g
1679modifier causes the substitution to apply to as many instances of the
1680search pattern
1681.Ar pattern
1682as occur in the word or words it is found in; the
1683.Ql W
1684modifier causes the value to be treated as a single word
1685(possibly containing embedded whitespace).
1686.Pp
1687As for the
1688.Cm \&:S
1689modifier, the
1690.Ar pattern
1691and
1692.Ar replacement
1693are subjected to variable expansion before being parsed as
1694regular expressions.
1695.It Cm \&:T
1696Replaces each word with its last path component (basename).
1697.It Cm \&:u
1698Removes adjacent duplicate words (like
1699.Xr uniq 1 ) .
1700.Sm off
1701.It Cm \&:\&?\| Ar true_string\| Cm \&: Ar false_string
1702.Sm on
1703If the variable name (not its value), when parsed as a
1704.Cm .if
1705conditional expression, evaluates to true, return as its value the
1706.Ar true_string ,
1707otherwise return the
1708.Ar false_string .
1709Since the variable name is used as the expression,
1710\&:\&? must be the first modifier after the variable name
1711.No itself Ns \^\(em\^ Ns
1712which, of course, usually contains variable expansions.
1713A common error is trying to use expressions like
1714.Dl ${NUMBERS:M42:?match:no}
1715which actually tests defined(NUMBERS).
1716To determine if any words match
1717.Dq 42 ,
1718you need to use something like:
1719.Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} .
1720.It Cm :\| Ns Ar old_string\| Ns Cm = Ns Ar new_string
1721This is the
1722.At V
1723style substitution.
1724It can only be the last modifier specified,
1725as a
1726.Ql \&:
1727in either
1728.Ar old_string
1729or
1730.Ar new_string
1731is treated as a regular character, not as the end of the modifier.
1732.Pp
1733If
1734.Ar old_string
1735does not contain the pattern matching character
1736.Ql % ,
1737and the word ends with
1738.Ar old_string
1739or equals it,
1740that suffix is replaced with
1741.Ar new_string .
1742.Pp
1743Otherwise, the first
1744.Ql %
1745in
1746.Ar old_string
1747matches a possibly empty substring of arbitrary characters,
1748and if the whole pattern is found in the word,
1749the matching part is replaced with
1750.Ar new_string ,
1751and the first occurrence of
1752.Ql %
1753in
1754.Ar new_string
1755(if any) is replaced with the substring matched by the
1756.Ql % .
1757.Pp
1758Both
1759.Ar old_string
1760and
1761.Ar new_string
1762may contain nested expressions.
1763To prevent a dollar sign from starting a nested expression,
1764escape it with a backslash.
1765.Sm off
1766.It Cm \&:@ Ar varname\| Cm @ Ar string\| Cm @
1767.Sm on
1768This is the loop expansion mechanism from the OSF Development
1769Environment (ODE) make.
1770Unlike
1771.Cm \&.for
1772loops, expansion occurs at the time of reference.
1773For each word in the value, assign the word to the variable named
1774.Ar varname
1775and evaluate
1776.Ar string .
1777The ODE convention is that
1778.Ar varname
1779should start and end with a period, for example:
1780.Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
1781.Pp
1782However, a single-letter variable is often more readable:
1783.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
1784.It Cm \&:_ Ns Oo Cm = Ns Ar var Oc
1785Saves the current variable value in
1786.Ql $_
1787or the named
1788.Ar var
1789for later reference.
1790Example usage:
1791.Bd -literal -offset indent
1792M_cmpv.units = 1 1000 1000000
1793M_cmpv = S,., ,g:_:range:@i@+ $${_:[-$$i]} \&\\
1794\\* $${M_cmpv.units:[$$i]}@:S,^,expr 0 ,1:sh
1795
1796.Dv .if ${VERSION:${M_cmpv}} < ${3.1.12:L:${M_cmpv}}
1797
1798.Ed
1799Here
1800.Ql $_
1801is used to save the result of the
1802.Ql :S
1803modifier which is later referenced using the index values from
1804.Ql :range .
1805.It Cm \&:U\| Ns Ar newval
1806If the variable is undefined,
1807the optional
1808.Ar newval
1809(which may be empty) is the value.
1810If the variable is defined, the existing value is returned.
1811This is another ODE make feature.
1812It is handy for setting per-target CFLAGS for instance:
1813.Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
1814If a value is only required if the variable is undefined, use:
1815.Dl ${VAR:D:Unewval}
1816.It Cm \&:D\| Ns Ar newval
1817If the variable is defined,
1818.Ar newval
1819(which may be empty) is the value.
1820.It Cm \&:L
1821The name of the variable is the value.
1822.It Cm \&:P
1823The path of the node which has the same name as the variable is the value.
1824If no such node exists or its path is null, the name of the variable is used.
1825In order for this modifier to work, the name (node) must at least have
1826appeared on the right-hand side of a dependency.
1827.Sm off
1828.It Cm \&:\&! Ar cmd\| Cm \&!
1829.Sm on
1830The output of running
1831.Ar cmd
1832is the value.
1833.It Cm \&:sh
1834The value is run as a command, and the output becomes the new value.
1835.It Cm \&::= Ns Ar str
1836The variable is assigned the value
1837.Ar str
1838after substitution.
1839This modifier and its variations are useful in obscure situations
1840such as wanting to set a variable
1841at a point where a target's shell commands are being parsed.
1842These assignment modifiers always expand to nothing.
1843.Pp
1844The
1845.Sq Cm \&::
1846helps avoid false matches with the
1847.At V
1848style
1849.Ql \&:=
1850modifier and since substitution always occurs, the
1851.Ql \&::=
1852form is vaguely appropriate.
1853.It Cm \&::?= Ns Ar str
1854As for
1855.Cm \&::=
1856but only if the variable does not already have a value.
1857.It Cm \&::+= Ns Ar str
1858Append
1859.Ar str
1860to the variable.
1861.It Cm \&::!= Ns Ar cmd
1862Assign the output of
1863.Ar cmd
1864to the variable.
1865.It Cm \&:\&[ Ns Ar range Ns Cm \&]
1866Selects one or more words from the value,
1867or performs other operations related to the way in which the
1868value is split into words.
1869.Pp
1870An empty value, or a value that consists entirely of white-space,
1871is treated as a single word.
1872For the purposes of the
1873.Sq Cm \&:[]
1874modifier, the words are indexed both forwards using positive integers
1875(where index 1 represents the first word),
1876and backwards using negative integers
1877(where index \-1 represents the last word).
1878.Pp
1879The
1880.Ar range
1881is subjected to variable expansion, and the expanded result is
1882then interpreted as follows:
1883.Bl -tag -width index
1884.\" :[n]
1885.It Ar index
1886Selects a single word from the value.
1887.\" :[start..end]
1888.It Ar start Ns Cm \&.. Ns Ar end
1889Selects all words from
1890.Ar start
1891to
1892.Ar end ,
1893inclusive.
1894For example,
1895.Sq Cm \&:[2..-1]
1896selects all words from the second word to the last word.
1897If
1898.Ar start
1899is greater than
1900.Ar end ,
1901the words are output in reverse order.
1902For example,
1903.Sq Cm \&:[-1..1]
1904selects all the words from last to first.
1905If the list is already ordered,
1906this effectively reverses the list,
1907but it is more efficient to use
1908.Sq Cm \&:Or
1909instead of
1910.Sq Cm \&:O:[-1..1] .
1911.\" :[*]
1912.It Cm \&*
1913Causes subsequent modifiers to treat the value as a single word
1914(possibly containing embedded whitespace).
1915Analogous to the effect of
1916.Li \&$*
1917in Bourne shell.
1918.\" :[0]
1919.It 0
1920Means the same as
1921.Sq Cm \&:[*] .
1922.\" :[*]
1923.It Cm \&@
1924Causes subsequent modifiers to treat the value as a sequence of words
1925delimited by whitespace.
1926Analogous to the effect of
1927.Li \&$@
1928in Bourne shell.
1929.\" :[#]
1930.It Cm \&#
1931Returns the number of words in the value.
1932.El \" :[range]
1933.El
1934.Sh DIRECTIVES
1935.Nm
1936offers directives for including makefiles, conditionals and for loops.
1937All these directives are identified by a line beginning with a single dot
1938.Pq Ql \&.
1939character, followed by the keyword of the directive, such as
1940.Cm include
1941or
1942.Cm if .
1943.Ss File inclusion
1944Files are included with either
1945.Cm \&.include \&< Ns Ar file Ns Cm \&>
1946or
1947.Cm \&.include \&\*q Ns Ar file Ns Cm \&\*q .
1948Variables between the angle brackets or double quotes are expanded
1949to form the file name.
1950If angle brackets are used, the included makefile is expected to be in
1951the system makefile directory.
1952If double quotes are used, the including makefile's directory and any
1953directories specified using the
1954.Fl I
1955option are searched before the system makefile directory.
1956.Pp
1957For compatibility with other make variants,
1958.Sq Cm include Ar file No ...
1959(without leading dot)
1960is also accepted.
1961.Pp
1962If the include statement is written as
1963.Cm .-include
1964or as
1965.Cm .sinclude ,
1966errors locating and/or opening include files are ignored.
1967.Pp
1968If the include statement is written as
1969.Cm .dinclude ,
1970not only are errors locating and/or opening include files ignored,
1971but stale dependencies within the included file are ignored just like in
1972.Va .MAKE.DEPENDFILE .
1973.Ss Exporting variables
1974The directives for exporting and unexporting variables are:
1975.Bl -tag -width Ds
1976.It Ic .export Ar variable No ...
1977Export the specified global variable.
1978.Pp
1979For compatibility with other make programs,
1980.Cm export Ar variable\| Ns Cm \&= Ns Ar value
1981(without leading dot) is also accepted.
1982.Pp
1983Appending a variable name to
1984.Va .MAKE.EXPORTED
1985is equivalent to exporting a variable.
1986.It Ic .export-all
1987Export all globals except for internal variables (those that start with
1988.Ql \&. ) .
1989This is not affected by the
1990.Fl X
1991flag, so should be used with caution.
1992.It Ic .export-env Ar variable No ...
1993The same as
1994.Ql .export ,
1995except that the variable is not appended to
1996.Va .MAKE.EXPORTED .
1997This allows exporting a value to the environment which is different from that
1998used by
1999.Nm
2000internally.
2001.It Ic .export-literal Ar variable No ...
2002The same as
2003.Ql .export-env ,
2004except that variables in the value are not expanded.
2005.It Ic .unexport Ar variable No ...
2006The opposite of
2007.Ql .export .
2008The specified global
2009.Ar variable
2010is removed from
2011.Va .MAKE.EXPORTED .
2012If no variable list is provided, all globals are unexported,
2013and
2014.Va .MAKE.EXPORTED
2015deleted.
2016.It Ic .unexport-env
2017Unexport all globals previously exported and
2018clear the environment inherited from the parent.
2019This operation causes a memory leak of the original environment,
2020so should be used sparingly.
2021Testing for
2022.Va .MAKE.LEVEL
2023being 0 would make sense.
2024Also note that any variables which originated in the parent environment
2025should be explicitly preserved if desired.
2026For example:
2027.Bd -literal -offset indent
2028.Li .if ${.MAKE.LEVEL} == 0
2029PATH := ${PATH}
2030.Li .unexport-env
2031.Li .export PATH
2032.Li .endif
2033.Pp
2034.Ed
2035Would result in an environment containing only
2036.Sq Ev PATH ,
2037which is the minimal useful environment.
2038.\" TODO: Check the below sentence, environment variables don't start with '.'.
2039Actually
2040.Sq Va .MAKE.LEVEL
2041is also pushed into the new environment.
2042.El
2043.Ss Messages
2044The directives for printing messages to the output are:
2045.Bl -tag -width Ds
2046.It Ic .info Ar message
2047The message is printed along with the name of the makefile and line number.
2048.It Ic .warning Ar message
2049The message prefixed by
2050.Sq Li warning:
2051is printed along with the name of the makefile and line number.
2052.It Ic .error Ar message
2053The message is printed along with the name of the makefile and line number,
2054.Nm
2055exits immediately.
2056.El
2057.Ss Conditionals
2058The directives for conditionals are:
2059.ds maybenot Oo Ic \&! Oc Ns
2060.Bl -tag
2061.It Ic .if \*[maybenot] Ar expression Op Ar operator expression No ...
2062Test the value of an expression.
2063.It Ic .ifdef \*[maybenot] Ar variable Op Ar operator variable No ...
2064Test whether a variable is defined.
2065.It Ic .ifndef \*[maybenot] Ar variable Op Ar operator variable No ...
2066Test whether a variable is not defined.
2067.It Ic .ifmake \*[maybenot] Ar target Op Ar operator target No ...
2068Test the target being requested.
2069.It Ic .ifnmake \*[maybenot] Ar target Op Ar operator target No ...
2070Test the target being requested.
2071.It Ic .else
2072Reverse the sense of the last conditional.
2073.It Ic .elif \*[maybenot] Ar expression Op Ar operator expression No ...
2074A combination of
2075.Sq Ic .else
2076followed by
2077.Sq Ic .if .
2078.It Ic .elifdef \*[maybenot] Ar variable Op Ar operator variable No ...
2079A combination of
2080.Sq Ic .else
2081followed by
2082.Sq Ic .ifdef .
2083.It Ic .elifndef \*[maybenot] Ar variable Op Ar operator variable No ...
2084A combination of
2085.Sq Ic .else
2086followed by
2087.Sq Ic .ifndef .
2088.It Ic .elifmake \*[maybenot] Ar target Op Ar operator target No ...
2089A combination of
2090.Sq Ic .else
2091followed by
2092.Sq Ic .ifmake .
2093.It Ic .elifnmake \*[maybenot] Ar target Op Ar operator target No ...
2094A combination of
2095.Sq Ic .else
2096followed by
2097.Sq Ic .ifnmake .
2098.It Ic .endif
2099End the body of the conditional.
2100.El
2101.Pp
2102The
2103.Ar operator
2104may be any one of the following:
2105.Bl -tag
2106.It Ic \&|\&|
2107Logical OR.
2108.It Ic \&&&
2109Logical AND; of higher precedence than
2110.Sq Ic \&|\&| .
2111.El
2112.Pp
2113.Nm
2114only evaluates a conditional as far as is necessary to determine its value.
2115Parentheses can be used to override the operator precedence.
2116The boolean operator
2117.Sq Ic \&!
2118may be used to logically negate an expression, typically a function call.
2119It is of higher precedence than
2120.Sq Ic \&&& .
2121.Pp
2122The value of
2123.Ar expression
2124may be any of the following function call expressions:
2125.Bl -tag
2126.Sm off
2127.It Ic defined Li \&( Ar varname Li \&)
2128.Sm on
2129Evaluates to true if the variable
2130.Ar varname
2131has been defined.
2132.Sm off
2133.It Ic make Li \&( Ar target Li \&)
2134.Sm on
2135Evaluates to true if the target was specified as part of
2136.Nm Ns 's
2137command line or was declared the default target (either implicitly or
2138explicitly, see
2139.Va .MAIN )
2140before the line containing the conditional.
2141.Sm off
2142.It Ic empty Li \&( Ar varname Oo Li : Ar modifiers Oc Li \&)
2143.Sm on
2144Evaluates to true if the expansion of the variable,
2145after applying the modifiers, results in an empty string.
2146.Sm off
2147.It Ic exists Li \&( Ar pathname Li \&)
2148.Sm on
2149Evaluates to true if the given pathname exists.
2150If relative, the pathname is searched for on the system search path (see
2151.Va .PATH ) .
2152.Sm off
2153.It Ic target Li \&( Ar target Li \&)
2154.Sm on
2155Evaluates to true if the target has been defined.
2156.Sm off
2157.It Ic commands Li \&( Ar target Li \&)
2158.Sm on
2159Evaluates to true if the target has been defined
2160and has commands associated with it.
2161.El
2162.Pp
2163.Ar Expression
2164may also be an arithmetic or string comparison.
2165Variable expansion is performed on both sides of the comparison.
2166If both sides are numeric and neither is enclosed in quotes,
2167the comparison is done numerically, otherwise lexicographically.
2168A string is interpreted as a hexadecimal integer if it is preceded by
2169.Li 0x ,
2170otherwise it is interpreted as a decimal floating-point number;
2171octal numbers are not supported.
2172.Pp
2173All comparisons may use the operators
2174.Sq Ic \&==
2175and
2176.Sq Ic \&!= .
2177Numeric comparisons may also use the operators
2178.Sq Ic \&< ,
2179.Sq Ic \&<= ,
2180.Sq Ic \&>
2181and
2182.Sq Ic \&>= .
2183.Pp
2184If the comparison has neither a comparison operator nor a right side,
2185the expression evaluates to true if it is nonempty
2186and its numeric value (if any) is not zero.
2187.Pp
2188When
2189.Nm
2190is evaluating one of these conditional expressions, and it encounters
2191a (whitespace-separated) word it doesn't recognize, either the
2192.Dq make
2193or
2194.Dq defined
2195function is applied to it, depending on the form of the conditional.
2196If the form is
2197.Sq Ic .ifdef ,
2198.Sq Ic .ifndef
2199or
2200.Sq Ic .if ,
2201the
2202.Dq defined
2203function is applied.
2204Similarly, if the form is
2205.Sq Ic .ifmake
2206or
2207.Sq Ic .ifnmake ,
2208the
2209.Dq make
2210function is applied.
2211.Pp
2212If the conditional evaluates to true,
2213parsing of the makefile continues as before.
2214If it evaluates to false, the following lines until the corresponding
2215.Sq Ic .elif
2216variant,
2217.Sq Ic .else
2218or
2219.Sq Ic .endif
2220are skipped.
2221.Ss For loops
2222For loops are typically used to apply a set of rules to a list of files.
2223The syntax of a for loop is:
2224.Pp
2225.Bl -tag -compact -width Ds
2226.It Ic \&.for Ar variable Oo Ar variable No ... Oc Ic in Ar expression
2227.It Aq Ar make-lines
2228.It Ic \&.endfor
2229.El
2230.Pp
2231The
2232.Ar expression
2233is expanded and then split into words.
2234On each iteration of the loop, one word is taken and assigned to each
2235.Ar variable ,
2236in order, and these
2237.Ar variables
2238are substituted into the
2239.Ar make-lines
2240inside the body of the for loop.
2241The number of words must come out even; that is, if there are three
2242iteration variables, the number of words provided must be a multiple
2243of three.
2244.Pp
2245If
2246.Sq Ic .break
2247is encountered within a
2248.Cm \&.for
2249loop, it causes early termination of the loop, otherwise a parse error.
2250.\" TODO: Describe limitations with defined/empty.
2251.Ss Other directives
2252.Bl -tag -width Ds
2253.It Ic .undef Ar variable No ...
2254Un-define the specified global variables.
2255Only global variables can be un-defined.
2256.El
2257.Sh COMMENTS
2258Comments begin with a hash
2259.Pq Ql \&#
2260character, anywhere but in a shell
2261command line, and continue to the end of an unescaped new line.
2262.Sh SPECIAL SOURCES (ATTRIBUTES)
2263.Bl -tag -width .IGNOREx
2264.It Ic .EXEC
2265Target is never out of date, but always execute commands anyway.
2266.It Ic .IGNORE
2267Ignore any errors from the commands associated with this target, exactly
2268as if they all were preceded by a dash
2269.Pq Ql \- .
2270.\" .It Ic .INVISIBLE
2271.\" XXX
2272.\" .It Ic .JOIN
2273.\" XXX
2274.It Ic .MADE
2275Mark all sources of this target as being up to date.
2276.It Ic .MAKE
2277Execute the commands associated with this target even if the
2278.Fl n
2279or
2280.Fl t
2281options were specified.
2282Normally used to mark recursive
2283.Nm Ns s .
2284.It Ic .META
2285Create a meta file for the target, even if it is flagged as
2286.Ic .PHONY ,
2287.Ic .MAKE ,
2288or
2289.Ic .SPECIAL .
2290Usage in conjunction with
2291.Ic .MAKE
2292is the most likely case.
2293In
2294.Dq meta
2295mode, the target is out-of-date if the meta file is missing.
2296.It Ic .NOMETA
2297Do not create a meta file for the target.
2298Meta files are also not created for
2299.Ic .PHONY ,
2300.Ic .MAKE ,
2301or
2302.Ic .SPECIAL
2303targets.
2304.It Ic .NOMETA_CMP
2305Ignore differences in commands when deciding if target is out of date.
2306This is useful if the command contains a value which always changes.
2307If the number of commands change, though,
2308the target is still considered out of date.
2309The same effect applies to any command line that uses the variable
2310.Va .OODATE ,
2311which can be used for that purpose even when not otherwise needed or desired:
2312.Bd -literal -offset indent
2313
2314skip-compare-for-some:
2315	@echo this is compared
2316	@echo this is not ${.OODATE:M.NOMETA_CMP}
2317	@echo this is also compared
2318
2319.Ed
2320The
2321.Cm \&:M
2322pattern suppresses any expansion of the unwanted variable.
2323.It Ic .NOPATH
2324Do not search for the target in the directories specified by
2325.Va .PATH .
2326.It Ic .NOTMAIN
2327Normally
2328.Nm
2329selects the first target it encounters as the default target to be built
2330if no target was specified.
2331This source prevents this target from being selected.
2332.It Ic .OPTIONAL
2333If a target is marked with this attribute and
2334.Nm
2335can't figure out how to create it, it ignores this fact and assumes
2336the file isn't needed or already exists.
2337.It Ic .PHONY
2338The target does not correspond to an actual file;
2339it is always considered to be out of date,
2340and is not created with the
2341.Fl t
2342option.
2343Suffix-transformation rules are not applied to
2344.Ic .PHONY
2345targets.
2346.It Ic .PRECIOUS
2347When
2348.Nm
2349is interrupted, it normally removes any partially made targets.
2350This source prevents the target from being removed.
2351.It Ic .RECURSIVE
2352Synonym for
2353.Ic .MAKE .
2354.It Ic .SILENT
2355Do not echo any of the commands associated with this target, exactly
2356as if they all were preceded by an at sign
2357.Pq Ql @ .
2358.It Ic .USE
2359Turn the target into
2360.Nm Ns 's
2361version of a macro.
2362When the target is used as a source for another target, the other target
2363acquires the commands, sources, and attributes (except for
2364.Ic .USE )
2365of the
2366source.
2367If the target already has commands, the
2368.Ic .USE
2369target's commands are appended
2370to them.
2371.It Ic .USEBEFORE
2372Like
2373.Ic .USE ,
2374but instead of appending, prepend the
2375.Ic .USEBEFORE
2376target commands to the target.
2377.It Ic .WAIT
2378If
2379.Ic .WAIT
2380appears in a dependency line, the sources that precede it are
2381made before the sources that succeed it in the line.
2382Since the dependents of files are not made until the file itself
2383could be made, this also stops the dependents being built unless they
2384are needed for another branch of the dependency tree.
2385So given:
2386.Bd -literal
2387x: a .WAIT b
2388	echo x
2389a:
2390	echo a
2391b: b1
2392	echo b
2393b1:
2394	echo b1
2395
2396.Ed
2397the output is always
2398.Ql a ,
2399.Ql b1 ,
2400.Ql b ,
2401.Ql x .
2402.Pp
2403The ordering imposed by
2404.Ic .WAIT
2405is only relevant for parallel makes.
2406.El
2407.Sh SPECIAL TARGETS
2408Special targets may not be included with other targets, i.e. they must be
2409the only target specified.
2410.Bl -tag -width .BEGINx
2411.It Ic .BEGIN
2412Any command lines attached to this target are executed before anything
2413else is done.
2414.It Ic .DEFAULT
2415This is sort of a
2416.Ic .USE
2417rule for any target (that was used only as a source) that
2418.Nm
2419can't figure out any other way to create.
2420Only the shell script is used.
2421The
2422.Va .IMPSRC
2423variable of a target that inherits
2424.Ic .DEFAULT Ns 's
2425commands is set to the target's own name.
2426.It Ic .DELETE_ON_ERROR
2427If this target is present in the makefile, it globally causes make to
2428delete targets whose commands fail.
2429(By default, only targets whose commands are interrupted during
2430execution are deleted.
2431This is the historical behavior.)
2432This setting can be used to help prevent half-finished or malformed
2433targets from being left around and corrupting future rebuilds.
2434.It Ic .END
2435Any command lines attached to this target are executed after everything
2436else is done successfully.
2437.It Ic .ERROR
2438Any command lines attached to this target are executed when another target fails.
2439See
2440.Va MAKE_PRINT_VAR_ON_ERROR
2441for the variables that will be set.
2442.It Ic .IGNORE
2443Mark each of the sources with the
2444.Ic .IGNORE
2445attribute.
2446If no sources are specified, this is the equivalent of specifying the
2447.Fl i
2448option.
2449.It Ic .INTERRUPT
2450If
2451.Nm
2452is interrupted, the commands for this target are executed.
2453.It Ic .MAIN
2454If no target is specified when
2455.Nm
2456is invoked, this target is built.
2457.It Ic .MAKEFLAGS
2458This target provides a way to specify flags for
2459.Nm
2460at the time when the makefiles are read.
2461The flags are as if typed to the shell, though the
2462.Fl f
2463option has
2464no effect.
2465.\" XXX: NOT YET!!!!
2466.\" .It Ic .NOTPARALLEL
2467.\" The named targets are executed in non parallel mode.
2468.\" If no targets are
2469.\" specified, all targets are executed in non parallel mode.
2470.It Ic .NOPATH
2471Apply the
2472.Ic .NOPATH
2473attribute to any specified sources.
2474.It Ic .NOTPARALLEL
2475Disable parallel mode.
2476.It Ic .NO_PARALLEL
2477Synonym for
2478.Ic .NOTPARALLEL ,
2479for compatibility with other pmake variants.
2480.It Ic .NOREADONLY
2481clear the read-only attribute from the global variables specified as sources.
2482.It Ic .OBJDIR
2483The source is a new value for
2484.Sq Va .OBJDIR .
2485If it exists,
2486.Nm
2487changes the current working directory to it and updates the value of
2488.Sq Va .OBJDIR .
2489.It Ic .ORDER
2490In parallel mode, the named targets are made in sequence.
2491This ordering does not add targets to the list of targets to be made.
2492.Pp
2493Since the dependents of a target do not get built until the target itself
2494could be built, unless
2495.Ql a
2496is built by another part of the dependency graph,
2497the following is a dependency loop:
2498.Bd -literal
2499\&.ORDER: b a
2500b: a
2501.Ed
2502.Pp
2503.\" XXX: NOT YET!!!!
2504.\" .It Ic .PARALLEL
2505.\" The named targets are executed in parallel mode.
2506.\" If no targets are
2507.\" specified, all targets are executed in parallel mode.
2508.It Ic .PATH
2509The sources are directories which are to be searched for files not
2510found in the current directory.
2511If no sources are specified,
2512any previously specified directories are removed from the search path.
2513If the source is the special
2514.Ic .DOTLAST
2515target, the current working directory is searched last.
2516.It Ic .PATH. Ns Ar suffix
2517Like
2518.Ic .PATH
2519but applies only to files with a particular suffix.
2520The suffix must have been previously declared with
2521.Ic .SUFFIXES .
2522.It Ic .PHONY
2523Apply the
2524.Ic .PHONY
2525attribute to any specified sources.
2526.It Ic .POSIX
2527If this is the first non-comment line in the main makefile,
2528the variable
2529.Va %POSIX
2530is set to the value
2531.Ql 1003.2
2532and the makefile
2533.Ql <posix.mk>
2534is included if it exists,
2535to provide POSIX-compatible default rules.
2536If
2537.Nm
2538is run with the
2539.Fl r
2540flag, only
2541.Ql posix.mk
2542contributes to the default rules.
2543.It Ic .PRECIOUS
2544Apply the
2545.Ic .PRECIOUS
2546attribute to any specified sources.
2547If no sources are specified, the
2548.Ic .PRECIOUS
2549attribute is applied to every target in the file.
2550.It Ic .READONLY
2551set the read-only attribute on the global variables specified as sources.
2552.It Ic .SHELL
2553Sets the shell that
2554.Nm
2555uses to execute commands.
2556The sources are a set of
2557.Ar field\| Ns Cm \&= Ns Ar value
2558pairs.
2559.Bl -tag -width ".Li hasErrCtls"
2560.It Li name
2561This is the minimal specification, used to select one of the built-in
2562shell specs;
2563.Li sh ,
2564.Li ksh ,
2565and
2566.Li csh .
2567.It Li path
2568Specifies the absolute path to the shell.
2569.It Li hasErrCtl
2570Indicates whether the shell supports exit on error.
2571.It Li check
2572The command to turn on error checking.
2573.It Li ignore
2574The command to disable error checking.
2575.It Li echo
2576The command to turn on echoing of commands executed.
2577.It Li quiet
2578The command to turn off echoing of commands executed.
2579.It Li filter
2580The output to filter after issuing the
2581.Li quiet
2582command.
2583It is typically identical to
2584.Li quiet .
2585.It Li errFlag
2586The flag to pass the shell to enable error checking.
2587.It Li echoFlag
2588The flag to pass the shell to enable command echoing.
2589.It Li newline
2590The string literal to pass the shell that results in a single newline
2591character when used outside of any quoting characters.
2592.El
2593Example:
2594.Bd -literal
2595\&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e
2596	check="set \-e" ignore="set +e" \e
2597	echo="set \-v" quiet="set +v" filter="set +v" \e
2598	echoFlag=v errFlag=e newline="'\en'"
2599.Ed
2600.It Ic .SILENT
2601Apply the
2602.Ic .SILENT
2603attribute to any specified sources.
2604If no sources are specified, the
2605.Ic .SILENT
2606attribute is applied to every
2607command in the file.
2608.It Ic .STALE
2609This target gets run when a dependency file contains stale entries, having
2610.Va .ALLSRC
2611set to the name of that dependency file.
2612.It Ic .SUFFIXES
2613Each source specifies a suffix to
2614.Nm .
2615If no sources are specified, any previously specified suffixes are deleted.
2616It allows the creation of suffix-transformation rules.
2617.Pp
2618Example:
2619.Bd -literal
2620\&.SUFFIXES: .c .o
2621\&.c.o:
2622	cc \-o ${.TARGET} \-c ${.IMPSRC}
2623.Ed
2624.It Ic .SYSPATH
2625The sources are directories which are to be added to the system
2626include path which
2627.Nm
2628searches for makefiles.
2629If no sources are specified,
2630any previously specified directories are removed from the system
2631include path.
2632.El
2633.Sh ENVIRONMENT
2634.Nm
2635uses the following environment variables, if they exist:
2636.Ev MACHINE ,
2637.Ev MACHINE_ARCH ,
2638.Ev MAKE ,
2639.Ev MAKEFLAGS ,
2640.Ev MAKEOBJDIR ,
2641.Ev MAKEOBJDIRPREFIX ,
2642.Ev MAKESYSPATH ,
2643.Ev PWD ,
2644and
2645.Ev TMPDIR .
2646.Pp
2647.Ev MAKEOBJDIRPREFIX
2648and
2649.Ev MAKEOBJDIR
2650may only be set in the environment or on the command line to
2651.Nm
2652and not as makefile variables;
2653see the description of
2654.Sq Va .OBJDIR
2655for more details.
2656.Sh FILES
2657.Bl -tag -width /usr/share/mk -compact
2658.It .depend
2659list of dependencies
2660.It makefile
2661first default makefile if no makefile is specified on the command line
2662.It Makefile
2663second default makefile if no makefile is specified on the command line
2664.It sys.mk
2665system makefile
2666.It /usr/share/mk
2667system makefile directory
2668.El
2669.Sh COMPATIBILITY
2670The basic make syntax is compatible between different make variants;
2671however the special variables, variable modifiers and conditionals are not.
2672.Ss Older versions
2673An incomplete list of changes in older versions of
2674.Nm :
2675.Pp
2676The way that .for loop variables are substituted changed after
2677.Nx 5.0
2678so that they still appear to be variable expansions.
2679In particular this stops them being treated as syntax, and removes some
2680obscure problems using them in .if statements.
2681.Pp
2682The way that parallel makes are scheduled changed in
2683.Nx 4.0
2684so that .ORDER and .WAIT apply recursively to the dependent nodes.
2685The algorithms used may change again in the future.
2686.Ss Other make dialects
2687Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not
2688support most of the features of
2689.Nm
2690as described in this manual.
2691Most notably:
2692.Bl -bullet -offset indent
2693.It
2694The
2695.Ic .WAIT
2696and
2697.Ic .ORDER
2698declarations and most functionality pertaining to parallelization.
2699(GNU make supports parallelization but lacks the features needed to
2700control it effectively.)
2701.It
2702Directives, including for loops and conditionals and most of the
2703forms of include files.
2704(GNU make has its own incompatible and less powerful syntax for
2705conditionals.)
2706.\" The "less powerful" above means that GNU make does not have the
2707.\" make(target), target(target) and commands(target) functions.
2708.It
2709All built-in variables that begin with a dot.
2710.It
2711Most of the special sources and targets that begin with a dot,
2712with the notable exception of
2713.Ic .PHONY ,
2714.Ic .PRECIOUS ,
2715and
2716.Ic .SUFFIXES .
2717.It
2718Variable modifiers, except for the
2719.Ql :old=new
2720string substitution, which does not portably support globbing with
2721.Ql %
2722and historically only works on declared suffixes.
2723.It
2724The
2725.Ic $>
2726variable even in its short form; most makes support this functionality
2727but its name varies.
2728.El
2729.Pp
2730Some features are somewhat more portable, such as assignment with
2731.Ic += ,
2732.Ic ?= ,
2733and
2734.Ic != .
2735The
2736.Va .PATH
2737functionality is based on an older feature
2738.Ic VPATH
2739found in GNU make and many versions of SVR4 make; however,
2740historically its behavior is too ill-defined (and too buggy) to rely
2741upon.
2742.Pp
2743The
2744.Ic $@
2745and
2746.Ic $<
2747variables are more or less universally portable, as is the
2748.Ic $(MAKE)
2749variable.
2750Basic use of suffix rules (for files only in the current directory,
2751not trying to chain transformations together, etc.) is also reasonably
2752portable.
2753.Sh SEE ALSO
2754.Xr mkdep 1 ,
2755.Xr style.Makefile 5
2756.Sh HISTORY
2757A
2758.Nm
2759command appeared in
2760.At v7 .
2761This
2762.Nm
2763implementation is based on Adam de Boor's pmake program,
2764which was written for Sprite at Berkeley.
2765It was designed to be a parallel distributed make running jobs on different
2766machines using a daemon called
2767.Dq customs .
2768.Pp
2769Historically the target/dependency
2770.Ic FRC
2771has been used to FoRCe rebuilding (since the target/dependency
2772does not exist ... unless someone creates an
2773.Pa FRC
2774file).
2775.Sh BUGS
2776The
2777.Nm
2778syntax is difficult to parse.
2779For instance, finding the end of a variable's use should involve scanning
2780each of the modifiers, using the correct terminator for each field.
2781In many places
2782.Nm
2783just counts {} and () in order to find the end of a variable expansion.
2784.Pp
2785There is no way of escaping a space character in a filename.
2786.Pp
2787In jobs mode, when a target fails;
2788.Nm
2789will put an error token into the job token pool.
2790This will cause all other instances of
2791.Nm
2792using that token pool to abort the build and exit with error code 6.
2793Sometimes the attempt to suppress a cascade of unnecessary errors,
2794can result in a seemingly unexplained
2795.Ql *** Error code 6
2796