xref: /freebsd/contrib/bmake/make.1 (revision a91a246563dffa876a52f53a98de4af9fa364c52)
1.\"	$NetBSD: make.1,v 1.375 2024/03/10 02:53:37 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 March 9, 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
1157Used to force a separate directory for the created files,
1158even if that directory is not writable, see
1159.Va .OBJDIR .
1160.It Va MAKEOBJDIRPREFIX
1161Used to create files in a separate directory, see
1162.Va .OBJDIR .
1163.It Va .MAKE.OS
1164The name of the operating system, see
1165.Xr uname 1 .
1166It is read-only.
1167.It Va .MAKEOVERRIDES
1168This variable is used to record the names of variables assigned to
1169on the command line, so that they may be exported as part of
1170.Sq Ev MAKEFLAGS .
1171This behavior can be disabled by assigning an empty value to
1172.Sq Va .MAKEOVERRIDES
1173within a makefile.
1174Extra variables can be exported from a makefile
1175by appending their names to
1176.Sq Va .MAKEOVERRIDES .
1177.Sq Ev MAKEFLAGS
1178is re-exported whenever
1179.Sq Va .MAKEOVERRIDES
1180is modified.
1181.It Va .MAKE.PATH_FILEMON
1182If
1183.Nm
1184was built with
1185.Xr filemon 4
1186support, this is set to the path of the device node.
1187This allows makefiles to test for this support.
1188.It Va .MAKE.PID
1189The process ID of
1190.Nm .
1191It is read-only.
1192.It Va .MAKE.PPID
1193The parent process ID of
1194.Nm .
1195It is read-only.
1196.It Va MAKE_PRINT_VAR_ON_ERROR
1197When
1198.Nm
1199stops due to an error, it sets
1200.Sq Va .ERROR_TARGET
1201to the name of the target that failed,
1202.Sq Va .ERROR_EXIT
1203to the exit status of the failed target,
1204.Sq Va .ERROR_CMD
1205to the commands of the failed target,
1206and in
1207.Dq meta
1208mode, it also sets
1209.Sq Va .ERROR_CWD
1210to the
1211.Xr getcwd 3 ,
1212and
1213.Sq Va .ERROR_META_FILE
1214to the path of the meta file (if any) describing the failed target.
1215It then prints its name and the value of
1216.Sq Va .CURDIR
1217as well as the value of any variables named in
1218.Sq Va MAKE_PRINT_VAR_ON_ERROR .
1219.It Va .MAKE.SAVE_DOLLARS
1220If true,
1221.Ql $$
1222are preserved when doing
1223.Ql :=
1224assignments.
1225The default is false, for backwards compatibility.
1226Set to true for compatability with other makes.
1227If set to false,
1228.Ql $$
1229becomes
1230.Ql $
1231per normal evaluation rules.
1232.It Va .MAKE.TARGET_LOCAL_VARIABLES
1233If set to
1234.Ql false ,
1235apparent variable assignments in dependency lines are
1236treated as normal sources.
1237.It Va .MAKE.UID
1238The numeric ID of the user running
1239.Nm .
1240It is read-only.
1241.\" 'MAKE_VERSION' is intentionally undocumented
1242.\" since it is only defined in the bmake distribution,
1243.\" but not in NetBSD's native make.
1244.\" '.meta.%d.lcwd' is intentionally undocumented
1245.\" since it is an internal implementation detail.
1246.\" '.meta.%d.ldir' is intentionally undocumented
1247.\" since it is an internal implementation detail.
1248.\" 'MFLAGS' is intentionally undocumented
1249.\" since it is obsolete.
1250.It Va .newline
1251This variable is simply assigned a newline character as its value.
1252It is read-only.
1253This allows expansions using the
1254.Cm \&:@
1255modifier to put a newline between
1256iterations of the loop rather than a space.
1257For example, in case of an error,
1258.Nm
1259prints the variable names and their values using:
1260.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
1261.It Va .OBJDIR
1262A path to the directory where the targets are built.
1263Its value is determined by trying to
1264.Xr chdir 2
1265to the following directories in order and using the first match:
1266.Bl -enum
1267.It
1268.Cm ${MAKEOBJDIRPREFIX} Ns Cm ${.CURDIR}
1269.Pp
1270(Only if
1271.Sq Ev MAKEOBJDIRPREFIX
1272is set in the environment or on the command line.)
1273.It
1274.Cm ${MAKEOBJDIR}
1275.Pp
1276(Only if
1277.Sq Ev MAKEOBJDIR
1278is set in the environment or on the command line.)
1279.It
1280.Cm ${.CURDIR} Ns Pa /obj. Ns Cm ${MACHINE}
1281.It
1282.Cm ${.CURDIR} Ns Pa /obj
1283.It
1284.Pa /usr/obj/ Ns Cm ${.CURDIR}
1285.It
1286.Cm ${.CURDIR}
1287.El
1288.Pp
1289Variable expansion is performed on the value before it is used,
1290so expressions such as
1291.Cm ${.CURDIR:S,^/usr/src,/var/obj,}
1292may be used.
1293This is especially useful with
1294.Sq Ev MAKEOBJDIR .
1295.Pp
1296.Sq Va .OBJDIR
1297may be modified in the makefile via the special target
1298.Sq Ic .OBJDIR .
1299In all cases,
1300.Nm
1301changes to the specified directory if it exists, and sets
1302.Sq Va .OBJDIR
1303and
1304.Sq Va PWD
1305to that directory before executing any targets.
1306.Pp
1307Except in the case of an explicit
1308.Sq Ic .OBJDIR
1309target,
1310.Nm
1311checks that the specified directory is writable and ignores it if not.
1312This check can be skipped by setting the environment variable
1313.Sq Ev MAKE_OBJDIR_CHECK_WRITABLE
1314to
1315.Dq no .
1316.It Va .PARSEDIR
1317The directory name of the current makefile being parsed.
1318.It Va .PARSEFILE
1319The basename of the current makefile being parsed.
1320This variable and
1321.Sq Va .PARSEDIR
1322are both set only while the makefiles are being parsed.
1323To retain their current values,
1324assign them to a variable using assignment with expansion
1325.Sq Cm \&:= .
1326.It Va .PATH
1327The space-separated list of directories that
1328.Nm
1329searches for files.
1330To update this search list, use the special target
1331.Sq Ic .PATH
1332rather than modifying the variable directly.
1333.It Va %POSIX
1334Is set in POSIX mode, see the special
1335.Ql Va .POSIX
1336target.
1337.\" XXX: There is no make variable named 'PWD',
1338.\" XXX: make only reads and writes the environment variable 'PWD'.
1339.It Va PWD
1340Alternate path to the current directory.
1341.Nm
1342normally sets
1343.Sq Va .CURDIR
1344to the canonical path given by
1345.Xr getcwd 3 .
1346However, if the environment variable
1347.Sq Ev PWD
1348is set and gives a path to the current directory,
1349.Nm
1350sets
1351.Sq Va .CURDIR
1352to the value of
1353.Sq Ev PWD
1354instead.
1355This behavior is disabled if
1356.Sq Ev MAKEOBJDIRPREFIX
1357is set or
1358.Sq Ev MAKEOBJDIR
1359contains a variable transform.
1360.Sq Va PWD
1361is set to the value of
1362.Sq Va .OBJDIR
1363for all programs which
1364.Nm
1365executes.
1366.It Va .SHELL
1367The pathname of the shell used to run target scripts.
1368It is read-only.
1369.It Va .SUFFIXES
1370The list of known suffixes.
1371It is read-only.
1372.It Va .SYSPATH
1373The space-separated list of directories that
1374.Nm
1375searches for makefiles, referred to as the system include path.
1376To update this search list, use the special target
1377.Sq Ic .SYSPATH
1378rather than modifying the variable which is read-only.
1379.It Va .TARGETS
1380The list of targets explicitly specified on the command line, if any.
1381.It Va VPATH
1382The colon-separated
1383.Pq Dq \&:
1384list of directories that
1385.Nm
1386searches for files.
1387This variable is supported for compatibility with old make programs only, use
1388.Sq Va .PATH
1389instead.
1390.El
1391.Ss Variable modifiers
1392The general format of a variable expansion is:
1393.Pp
1394.Sm off
1395.D1 Ic \&${ Ar variable\| Oo Ic \&: Ar modifier\| Oo Ic \&: No ... Oc Oc Ic \&}
1396.Sm on
1397.Pp
1398Each modifier begins with a colon.
1399To escape a colon, precede it with a backslash
1400.Ql \e .
1401.Pp
1402A list of indirect modifiers can be specified via a variable, as follows:
1403.Pp
1404.Bd -literal -offset indent
1405.Ar modifier_variable\^ Li \&= Ar modifier Ns Oo Ic \&: Ns No ... Oc
1406
1407.Sm off
1408.Ic \&${ Ar variable Ic \&:${ Ar modifier_variable Ic \&} Oo Ic \&: No ... Oc Ic \&}
1409.Sm on
1410.Ed
1411.Pp
1412In this case, the first modifier in the
1413.Ar modifier_variable
1414does not start with a colon,
1415since that colon already occurs in the referencing variable.
1416If any of the modifiers in the
1417.Ar modifier_variable
1418contains a dollar sign
1419.Pq Ql $ ,
1420these must be doubled to avoid early expansion.
1421.Pp
1422Some modifiers interpret the expression value as a single string,
1423others treat the expression value as a whitespace-separated list of words.
1424When splitting a string into words,
1425whitespace can be escaped using double quotes, single quotes and backslashes,
1426like in the shell.
1427The quotes and backslashes are retained in the words.
1428.Pp
1429The supported modifiers are:
1430.Bl -tag -width EEE
1431.It Cm \&:E
1432Replaces each word with its suffix.
1433.It Cm \&:H
1434Replaces each word with its dirname.
1435.It Cm \&:M\| Ns Ar pattern
1436Selects only those words that match
1437.Ar pattern .
1438The standard shell wildcard characters
1439.Pf ( Ql * ,
1440.Ql \&? ,
1441and
1442.Ql \&[] )
1443may
1444be used.
1445The wildcard characters may be escaped with a backslash
1446.Pq Ql \e .
1447As a consequence of the way values are split into words, matched,
1448and then joined, the construct
1449.Ql ${VAR:M*}
1450removes all leading and trailing whitespace
1451and normalizes the inter-word spacing to a single space.
1452.It Cm \&:N\| Ns Ar pattern
1453This is the opposite of
1454.Sq Cm \&:M ,
1455selecting all words which do
1456.Em not
1457match
1458.Ar pattern .
1459.It Cm \&:O
1460Orders the words lexicographically.
1461.It Cm \&:On
1462Orders the words numerically.
1463A number followed by one of
1464.Ql k ,
1465.Ql M
1466or
1467.Ql G
1468is multiplied by the appropriate factor, which is 1024 for
1469.Ql k ,
14701048576 for
1471.Ql M ,
1472or 1073741824 for
1473.Ql G .
1474Both upper- and lower-case letters are accepted.
1475.It Cm \&:Or
1476Orders the words in reverse lexicographical order.
1477.It Cm \&:Orn
1478Orders the words in reverse numerical order.
1479.It Cm \&:Ox
1480Shuffles the words.
1481The results are different each time you are referring to the
1482modified variable; use the assignment with expansion
1483.Sq Cm \&:=
1484to prevent such behavior.
1485For example,
1486.Bd -literal -offset indent
1487LIST=			uno due tre quattro
1488RANDOM_LIST=		${LIST:Ox}
1489STATIC_RANDOM_LIST:=	${LIST:Ox}
1490
1491all:
1492	@echo "${RANDOM_LIST}"
1493	@echo "${RANDOM_LIST}"
1494	@echo "${STATIC_RANDOM_LIST}"
1495	@echo "${STATIC_RANDOM_LIST}"
1496.Ed
1497may produce output similar to:
1498.Bd -literal -offset indent
1499quattro due tre uno
1500tre due quattro uno
1501due uno quattro tre
1502due uno quattro tre
1503.Ed
1504.It Cm \&:Q
1505Quotes every shell meta-character in the value, so that it can be passed
1506safely to the shell.
1507.It Cm \&:q
1508Quotes every shell meta-character in the value, and also doubles
1509.Sq $
1510characters so that it can be passed
1511safely through recursive invocations of
1512.Nm .
1513This is equivalent to
1514.Sq Cm \&:S/\e\&$/&&/g:Q .
1515.It Cm \&:R
1516Replaces each word with everything but its suffix.
1517.It Cm \&:range Ns Oo Cm = Ns Ar count Oc
1518The value is an integer sequence representing the words of the original
1519value, or the supplied
1520.Ar count .
1521.It Cm \&:gmtime Ns Oo Cm = Ns Ar timestamp Oc
1522The value is interpreted as a format string for
1523.Xr strftime 3 ,
1524using
1525.Xr gmtime 3 ,
1526producing the formatted timestamp.
1527Note: the
1528.Ql %s
1529format should only be used with
1530.Sq Cm \&:localtime .
1531If a
1532.Ar timestamp
1533value is not provided or is 0, the current time is used.
1534.It Cm \&:hash
1535Computes a 32-bit hash of the value and encodes it as 8 hex digits.
1536.It Cm \&:localtime Ns Oo Cm = Ns Ar timestamp Oc
1537The value is interpreted as a format string for
1538.Xr strftime 3 ,
1539using
1540.Xr localtime 3 ,
1541producing the formatted timestamp.
1542If a
1543.Ar timestamp
1544value is not provided or is 0, the current time is used.
1545.It Cm \&:mtime Ns Oo Cm = Ns Ar timestamp Oc
1546Call
1547.Xr stat 2
1548with each word as pathname;
1549use
1550.Ql st_mtime
1551as the new value.
1552If
1553.Xr stat 2
1554fails; use
1555.Ar timestamp
1556or current time.
1557If
1558.Ar timestamp
1559is set to
1560.Ql error ,
1561then
1562.Xr stat 2
1563failure will cause an error.
1564.It Cm \&:tA
1565Attempts to convert the value to an absolute path using
1566.Xr realpath 3 .
1567If that fails, the value is unchanged.
1568.It Cm \&:tl
1569Converts the value to lower-case letters.
1570.It Cm \&:ts Ns Ar c
1571When joining the words after a modifier that treats the value as words,
1572the words are normally separated by a space.
1573This modifier changes the separator to the character
1574.Ar c .
1575If
1576.Ar c
1577is omitted, no separator is used.
1578The common escapes (including octal numeric codes) work as expected.
1579.It Cm \&:tu
1580Converts the value to upper-case letters.
1581.It Cm \&:tW
1582Causes subsequent modifiers to treat the value as a single word
1583(possibly containing embedded whitespace).
1584See also
1585.Sq Cm \&:[*] .
1586.It Cm \&:tw
1587Causes the value to be treated as a list of words.
1588See also
1589.Sq Cm \&:[@] .
1590.Sm off
1591.It Cm \&:S\| No \&/ Ar old_string\| No \&/ Ar new_string\| No \&/ Op Cm 1gW
1592.Sm on
1593Modifies the first occurrence of
1594.Ar old_string
1595in each word of the value, replacing it with
1596.Ar new_string .
1597If a
1598.Ql g
1599is appended to the last delimiter of the pattern,
1600all occurrences in each word are replaced.
1601If a
1602.Ql 1
1603is appended to the last delimiter of the pattern,
1604only the first occurrence is affected.
1605If a
1606.Ql W
1607is appended to the last delimiter of the pattern,
1608the value is treated as a single word.
1609If
1610.Ar old_string
1611begins with a caret
1612.Pq Ql ^ ,
1613.Ar old_string
1614is anchored at the beginning of each word.
1615If
1616.Ar old_string
1617ends with a dollar sign
1618.Pq Ql \&$ ,
1619it is anchored at the end of each word.
1620Inside
1621.Ar new_string ,
1622an ampersand
1623.Pq Ql &
1624is replaced by
1625.Ar old_string
1626(without the anchoring
1627.Ql ^
1628or
1629.Ql \&$ ) .
1630Any character may be used as the delimiter for the parts of the modifier
1631string.
1632The anchoring, ampersand and delimiter characters can be escaped with a
1633backslash
1634.Pq Ql \e .
1635.Pp
1636Both
1637.Ar old_string
1638and
1639.Ar new_string
1640may contain nested expressions.
1641To prevent a dollar sign from starting a nested expression,
1642escape it with a backslash.
1643.Sm off
1644.It Cm \&:C\| No \&/ Ar pattern\| No \&/ Ar replacement\| No \&/ Op Cm 1gW
1645.Sm on
1646The
1647.Cm \&:C
1648modifier works like the
1649.Cm \&:S
1650modifier except that the old and new strings, instead of being
1651simple strings, are an extended regular expression
1652.Ar pattern
1653(see
1654.Xr regex 3 )
1655and an
1656.Xr ed 1 Ns \-style
1657.Ar replacement .
1658Normally, the first occurrence of the pattern
1659.Ar pattern
1660in each word of the value is substituted with
1661.Ar replacement .
1662The
1663.Ql 1
1664modifier causes the substitution to apply to at most one word; the
1665.Ql g
1666modifier causes the substitution to apply to as many instances of the
1667search pattern
1668.Ar pattern
1669as occur in the word or words it is found in; the
1670.Ql W
1671modifier causes the value to be treated as a single word
1672(possibly containing embedded whitespace).
1673.Pp
1674As for the
1675.Cm \&:S
1676modifier, the
1677.Ar pattern
1678and
1679.Ar replacement
1680are subjected to variable expansion before being parsed as
1681regular expressions.
1682.It Cm \&:T
1683Replaces each word with its last path component (basename).
1684.It Cm \&:u
1685Removes adjacent duplicate words (like
1686.Xr uniq 1 ) .
1687.Sm off
1688.It Cm \&:\&?\| Ar true_string\| Cm \&: Ar false_string
1689.Sm on
1690If the variable name (not its value), when parsed as a
1691.Cm .if
1692conditional expression, evaluates to true, return as its value the
1693.Ar true_string ,
1694otherwise return the
1695.Ar false_string .
1696Since the variable name is used as the expression,
1697\&:\&? must be the first modifier after the variable name
1698.No itself Ns \^\(em\^ Ns
1699which, of course, usually contains variable expansions.
1700A common error is trying to use expressions like
1701.Dl ${NUMBERS:M42:?match:no}
1702which actually tests defined(NUMBERS).
1703To determine if any words match
1704.Dq 42 ,
1705you need to use something like:
1706.Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} .
1707.It Cm :\| Ns Ar old_string\| Ns Cm = Ns Ar new_string
1708This is the
1709.At V
1710style substitution.
1711It can only be the last modifier specified,
1712as a
1713.Ql \&:
1714in either
1715.Ar old_string
1716or
1717.Ar new_string
1718is treated as a regular character, not as the end of the modifier.
1719.Pp
1720If
1721.Ar old_string
1722does not contain the pattern matching character
1723.Ql % ,
1724and the word ends with
1725.Ar old_string
1726or equals it,
1727that suffix is replaced with
1728.Ar new_string .
1729.Pp
1730Otherwise, the first
1731.Ql %
1732in
1733.Ar old_string
1734matches a possibly empty substring of arbitrary characters,
1735and if the whole pattern is found in the word,
1736the matching part is replaced with
1737.Ar new_string ,
1738and the first occurrence of
1739.Ql %
1740in
1741.Ar new_string
1742(if any) is replaced with the substring matched by the
1743.Ql % .
1744.Pp
1745Both
1746.Ar old_string
1747and
1748.Ar new_string
1749may contain nested expressions.
1750To prevent a dollar sign from starting a nested expression,
1751escape it with a backslash.
1752.Sm off
1753.It Cm \&:@ Ar varname\| Cm @ Ar string\| Cm @
1754.Sm on
1755This is the loop expansion mechanism from the OSF Development
1756Environment (ODE) make.
1757Unlike
1758.Cm \&.for
1759loops, expansion occurs at the time of reference.
1760For each word in the value, assign the word to the variable named
1761.Ar varname
1762and evaluate
1763.Ar string .
1764The ODE convention is that
1765.Ar varname
1766should start and end with a period, for example:
1767.Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
1768.Pp
1769However, a single-letter variable is often more readable:
1770.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
1771.It Cm \&:_ Ns Oo Cm = Ns Ar var Oc
1772Saves the current variable value in
1773.Ql $_
1774or the named
1775.Ar var
1776for later reference.
1777Example usage:
1778.Bd -literal -offset indent
1779M_cmpv.units = 1 1000 1000000
1780M_cmpv = S,., ,g:_:range:@i@+ $${_:[-$$i]} \&\\
1781\\* $${M_cmpv.units:[$$i]}@:S,^,expr 0 ,1:sh
1782
1783.Dv .if ${VERSION:${M_cmpv}} < ${3.1.12:L:${M_cmpv}}
1784
1785.Ed
1786Here
1787.Ql $_
1788is used to save the result of the
1789.Ql :S
1790modifier which is later referenced using the index values from
1791.Ql :range .
1792.It Cm \&:U\| Ns Ar newval
1793If the variable is undefined,
1794the optional
1795.Ar newval
1796(which may be empty) is the value.
1797If the variable is defined, the existing value is returned.
1798This is another ODE make feature.
1799It is handy for setting per-target CFLAGS for instance:
1800.Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
1801If a value is only required if the variable is undefined, use:
1802.Dl ${VAR:D:Unewval}
1803.It Cm \&:D\| Ns Ar newval
1804If the variable is defined,
1805.Ar newval
1806(which may be empty) is the value.
1807.It Cm \&:L
1808The name of the variable is the value.
1809.It Cm \&:P
1810The path of the node which has the same name as the variable is the value.
1811If no such node exists or its path is null, the name of the variable is used.
1812In order for this modifier to work, the name (node) must at least have
1813appeared on the right-hand side of a dependency.
1814.Sm off
1815.It Cm \&:\&! Ar cmd\| Cm \&!
1816.Sm on
1817The output of running
1818.Ar cmd
1819is the value.
1820.It Cm \&:sh
1821The value is run as a command, and the output becomes the new value.
1822.It Cm \&::= Ns Ar str
1823The variable is assigned the value
1824.Ar str
1825after substitution.
1826This modifier and its variations are useful in obscure situations
1827such as wanting to set a variable
1828at a point where a target's shell commands are being parsed.
1829These assignment modifiers always expand to nothing.
1830.Pp
1831The
1832.Sq Cm \&::
1833helps avoid false matches with the
1834.At V
1835style
1836.Ql \&:=
1837modifier and since substitution always occurs, the
1838.Ql \&::=
1839form is vaguely appropriate.
1840.It Cm \&::?= Ns Ar str
1841As for
1842.Cm \&::=
1843but only if the variable does not already have a value.
1844.It Cm \&::+= Ns Ar str
1845Append
1846.Ar str
1847to the variable.
1848.It Cm \&::!= Ns Ar cmd
1849Assign the output of
1850.Ar cmd
1851to the variable.
1852.It Cm \&:\&[ Ns Ar range Ns Cm \&]
1853Selects one or more words from the value,
1854or performs other operations related to the way in which the
1855value is split into words.
1856.Pp
1857An empty value, or a value that consists entirely of white-space,
1858is treated as a single word.
1859For the purposes of the
1860.Sq Cm \&:[]
1861modifier, the words are indexed both forwards using positive integers
1862(where index 1 represents the first word),
1863and backwards using negative integers
1864(where index \-1 represents the last word).
1865.Pp
1866The
1867.Ar range
1868is subjected to variable expansion, and the expanded result is
1869then interpreted as follows:
1870.Bl -tag -width index
1871.\" :[n]
1872.It Ar index
1873Selects a single word from the value.
1874.\" :[start..end]
1875.It Ar start Ns Cm \&.. Ns Ar end
1876Selects all words from
1877.Ar start
1878to
1879.Ar end ,
1880inclusive.
1881For example,
1882.Sq Cm \&:[2..-1]
1883selects all words from the second word to the last word.
1884If
1885.Ar start
1886is greater than
1887.Ar end ,
1888the words are output in reverse order.
1889For example,
1890.Sq Cm \&:[-1..1]
1891selects all the words from last to first.
1892If the list is already ordered,
1893this effectively reverses the list,
1894but it is more efficient to use
1895.Sq Cm \&:Or
1896instead of
1897.Sq Cm \&:O:[-1..1] .
1898.\" :[*]
1899.It Cm \&*
1900Causes subsequent modifiers to treat the value as a single word
1901(possibly containing embedded whitespace).
1902Analogous to the effect of
1903.Li \&$*
1904in Bourne shell.
1905.\" :[0]
1906.It 0
1907Means the same as
1908.Sq Cm \&:[*] .
1909.\" :[*]
1910.It Cm \&@
1911Causes subsequent modifiers to treat the value as a sequence of words
1912delimited by whitespace.
1913Analogous to the effect of
1914.Li \&$@
1915in Bourne shell.
1916.\" :[#]
1917.It Cm \&#
1918Returns the number of words in the value.
1919.El \" :[range]
1920.El
1921.Sh DIRECTIVES
1922.Nm
1923offers directives for including makefiles, conditionals and for loops.
1924All these directives are identified by a line beginning with a single dot
1925.Pq Ql \&.
1926character, followed by the keyword of the directive, such as
1927.Cm include
1928or
1929.Cm if .
1930.Ss File inclusion
1931Files are included with either
1932.Cm \&.include \&< Ns Ar file Ns Cm \&>
1933or
1934.Cm \&.include \&\*q Ns Ar file Ns Cm \&\*q .
1935Variables between the angle brackets or double quotes are expanded
1936to form the file name.
1937If angle brackets are used, the included makefile is expected to be in
1938the system makefile directory.
1939If double quotes are used, the including makefile's directory and any
1940directories specified using the
1941.Fl I
1942option are searched before the system makefile directory.
1943.Pp
1944For compatibility with other make variants,
1945.Sq Cm include Ar file No ...
1946(without leading dot)
1947is also accepted.
1948.Pp
1949If the include statement is written as
1950.Cm .-include
1951or as
1952.Cm .sinclude ,
1953errors locating and/or opening include files are ignored.
1954.Pp
1955If the include statement is written as
1956.Cm .dinclude ,
1957not only are errors locating and/or opening include files ignored,
1958but stale dependencies within the included file are ignored just like in
1959.Va .MAKE.DEPENDFILE .
1960.Ss Exporting variables
1961The directives for exporting and unexporting variables are:
1962.Bl -tag -width Ds
1963.It Ic .export Ar variable No ...
1964Export the specified global variable.
1965If no variable list is provided, all globals are exported
1966except for internal variables (those that start with
1967.Ql \&. ) .
1968This is not affected by the
1969.Fl X
1970flag, so should be used with caution.
1971For compatibility with other make programs,
1972.Cm export Ar variable\| Ns Cm \&= Ns Ar value
1973(without leading dot) is also accepted.
1974.Pp
1975Appending a variable name to
1976.Va .MAKE.EXPORTED
1977is equivalent to exporting a variable.
1978.It Ic .export-env Ar variable No ...
1979The same as
1980.Ql .export ,
1981except that the variable is not appended to
1982.Va .MAKE.EXPORTED .
1983This allows exporting a value to the environment which is different from that
1984used by
1985.Nm
1986internally.
1987.It Ic .export-literal Ar variable No ...
1988The same as
1989.Ql .export-env ,
1990except that variables in the value are not expanded.
1991.It Ic .unexport Ar variable No ...
1992The opposite of
1993.Ql .export .
1994The specified global
1995.Ar variable
1996is removed from
1997.Va .MAKE.EXPORTED .
1998If no variable list is provided, all globals are unexported,
1999and
2000.Va .MAKE.EXPORTED
2001deleted.
2002.It Ic .unexport-env
2003Unexport all globals previously exported and
2004clear the environment inherited from the parent.
2005This operation causes a memory leak of the original environment,
2006so should be used sparingly.
2007Testing for
2008.Va .MAKE.LEVEL
2009being 0 would make sense.
2010Also note that any variables which originated in the parent environment
2011should be explicitly preserved if desired.
2012For example:
2013.Bd -literal -offset indent
2014.Li .if ${.MAKE.LEVEL} == 0
2015PATH := ${PATH}
2016.Li .unexport-env
2017.Li .export PATH
2018.Li .endif
2019.Pp
2020.Ed
2021Would result in an environment containing only
2022.Sq Ev PATH ,
2023which is the minimal useful environment.
2024.\" TODO: Check the below sentence, environment variables don't start with '.'.
2025Actually
2026.Sq Va .MAKE.LEVEL
2027is also pushed into the new environment.
2028.El
2029.Ss Messages
2030The directives for printing messages to the output are:
2031.Bl -tag -width Ds
2032.It Ic .info Ar message
2033The message is printed along with the name of the makefile and line number.
2034.It Ic .warning Ar message
2035The message prefixed by
2036.Sq Li warning:
2037is printed along with the name of the makefile and line number.
2038.It Ic .error Ar message
2039The message is printed along with the name of the makefile and line number,
2040.Nm
2041exits immediately.
2042.El
2043.Ss Conditionals
2044The directives for conditionals are:
2045.ds maybenot Oo Ic \&! Oc Ns
2046.Bl -tag
2047.It Ic .if \*[maybenot] Ar expression Op Ar operator expression No ...
2048Test the value of an expression.
2049.It Ic .ifdef \*[maybenot] Ar variable Op Ar operator variable No ...
2050Test whether a variable is defined.
2051.It Ic .ifndef \*[maybenot] Ar variable Op Ar operator variable No ...
2052Test whether a variable is not defined.
2053.It Ic .ifmake \*[maybenot] Ar target Op Ar operator target No ...
2054Test the target being requested.
2055.It Ic .ifnmake \*[maybenot] Ar target Op Ar operator target No ...
2056Test the target being requested.
2057.It Ic .else
2058Reverse the sense of the last conditional.
2059.It Ic .elif \*[maybenot] Ar expression Op Ar operator expression No ...
2060A combination of
2061.Sq Ic .else
2062followed by
2063.Sq Ic .if .
2064.It Ic .elifdef \*[maybenot] Ar variable Op Ar operator variable No ...
2065A combination of
2066.Sq Ic .else
2067followed by
2068.Sq Ic .ifdef .
2069.It Ic .elifndef \*[maybenot] Ar variable Op Ar operator variable No ...
2070A combination of
2071.Sq Ic .else
2072followed by
2073.Sq Ic .ifndef .
2074.It Ic .elifmake \*[maybenot] Ar target Op Ar operator target No ...
2075A combination of
2076.Sq Ic .else
2077followed by
2078.Sq Ic .ifmake .
2079.It Ic .elifnmake \*[maybenot] Ar target Op Ar operator target No ...
2080A combination of
2081.Sq Ic .else
2082followed by
2083.Sq Ic .ifnmake .
2084.It Ic .endif
2085End the body of the conditional.
2086.El
2087.Pp
2088The
2089.Ar operator
2090may be any one of the following:
2091.Bl -tag
2092.It Ic \&|\&|
2093Logical OR.
2094.It Ic \&&&
2095Logical AND; of higher precedence than
2096.Sq Ic \&|\&| .
2097.El
2098.Pp
2099.Nm
2100only evaluates a conditional as far as is necessary to determine its value.
2101Parentheses can be used to override the operator precedence.
2102The boolean operator
2103.Sq Ic \&!
2104may be used to logically negate an expression, typically a function call.
2105It is of higher precedence than
2106.Sq Ic \&&& .
2107.Pp
2108The value of
2109.Ar expression
2110may be any of the following function call expressions:
2111.Bl -tag
2112.Sm off
2113.It Ic defined Li \&( Ar varname Li \&)
2114.Sm on
2115Evaluates to true if the variable
2116.Ar varname
2117has been defined.
2118.Sm off
2119.It Ic make Li \&( Ar target Li \&)
2120.Sm on
2121Evaluates to true if the target was specified as part of
2122.Nm Ns 's
2123command line or was declared the default target (either implicitly or
2124explicitly, see
2125.Va .MAIN )
2126before the line containing the conditional.
2127.Sm off
2128.It Ic empty Li \&( Ar varname Oo Li : Ar modifiers Oc Li \&)
2129.Sm on
2130Evaluates to true if the expansion of the variable,
2131after applying the modifiers, results in an empty string.
2132.Sm off
2133.It Ic exists Li \&( Ar pathname Li \&)
2134.Sm on
2135Evaluates to true if the given pathname exists.
2136If relative, the pathname is searched for on the system search path (see
2137.Va .PATH ) .
2138.Sm off
2139.It Ic target Li \&( Ar target Li \&)
2140.Sm on
2141Evaluates to true if the target has been defined.
2142.Sm off
2143.It Ic commands Li \&( Ar target Li \&)
2144.Sm on
2145Evaluates to true if the target has been defined
2146and has commands associated with it.
2147.El
2148.Pp
2149.Ar Expression
2150may also be an arithmetic or string comparison.
2151Variable expansion is performed on both sides of the comparison.
2152If both sides are numeric and neither is enclosed in quotes,
2153the comparison is done numerically, otherwise lexicographically.
2154A string is interpreted as a hexadecimal integer if it is preceded by
2155.Li 0x ,
2156otherwise it is interpreted as a decimal floating-point number;
2157octal numbers are not supported.
2158.Pp
2159All comparisons may use the operators
2160.Sq Ic \&==
2161and
2162.Sq Ic \&!= .
2163Numeric comparisons may also use the operators
2164.Sq Ic \&< ,
2165.Sq Ic \&<= ,
2166.Sq Ic \&>
2167and
2168.Sq Ic \&>= .
2169.Pp
2170If the comparison has neither a comparison operator nor a right side,
2171the expression evaluates to true if it is nonempty
2172and its numeric value (if any) is not zero.
2173.Pp
2174When
2175.Nm
2176is evaluating one of these conditional expressions, and it encounters
2177a (whitespace-separated) word it doesn't recognize, either the
2178.Dq make
2179or
2180.Dq defined
2181function is applied to it, depending on the form of the conditional.
2182If the form is
2183.Sq Ic .ifdef ,
2184.Sq Ic .ifndef
2185or
2186.Sq Ic .if ,
2187the
2188.Dq defined
2189function is applied.
2190Similarly, if the form is
2191.Sq Ic .ifmake
2192or
2193.Sq Ic .ifnmake ,
2194the
2195.Dq make
2196function is applied.
2197.Pp
2198If the conditional evaluates to true,
2199parsing of the makefile continues as before.
2200If it evaluates to false, the following lines until the corresponding
2201.Sq Ic .elif
2202variant,
2203.Sq Ic .else
2204or
2205.Sq Ic .endif
2206are skipped.
2207.Ss For loops
2208For loops are typically used to apply a set of rules to a list of files.
2209The syntax of a for loop is:
2210.Pp
2211.Bl -tag -compact -width Ds
2212.It Ic \&.for Ar variable Oo Ar variable No ... Oc Ic in Ar expression
2213.It Aq Ar make-lines
2214.It Ic \&.endfor
2215.El
2216.Pp
2217The
2218.Ar expression
2219is expanded and then split into words.
2220On each iteration of the loop, one word is taken and assigned to each
2221.Ar variable ,
2222in order, and these
2223.Ar variables
2224are substituted into the
2225.Ar make-lines
2226inside the body of the for loop.
2227The number of words must come out even; that is, if there are three
2228iteration variables, the number of words provided must be a multiple
2229of three.
2230.Pp
2231If
2232.Sq Ic .break
2233is encountered within a
2234.Cm \&.for
2235loop, it causes early termination of the loop, otherwise a parse error.
2236.\" TODO: Describe limitations with defined/empty.
2237.Ss Other directives
2238.Bl -tag -width Ds
2239.It Ic .undef Ar variable No ...
2240Un-define the specified global variables.
2241Only global variables can be un-defined.
2242.El
2243.Sh COMMENTS
2244Comments begin with a hash
2245.Pq Ql \&#
2246character, anywhere but in a shell
2247command line, and continue to the end of an unescaped new line.
2248.Sh SPECIAL SOURCES (ATTRIBUTES)
2249.Bl -tag -width .IGNOREx
2250.It Ic .EXEC
2251Target is never out of date, but always execute commands anyway.
2252.It Ic .IGNORE
2253Ignore any errors from the commands associated with this target, exactly
2254as if they all were preceded by a dash
2255.Pq Ql \- .
2256.\" .It Ic .INVISIBLE
2257.\" XXX
2258.\" .It Ic .JOIN
2259.\" XXX
2260.It Ic .MADE
2261Mark all sources of this target as being up to date.
2262.It Ic .MAKE
2263Execute the commands associated with this target even if the
2264.Fl n
2265or
2266.Fl t
2267options were specified.
2268Normally used to mark recursive
2269.Nm Ns s .
2270.It Ic .META
2271Create a meta file for the target, even if it is flagged as
2272.Ic .PHONY ,
2273.Ic .MAKE ,
2274or
2275.Ic .SPECIAL .
2276Usage in conjunction with
2277.Ic .MAKE
2278is the most likely case.
2279In
2280.Dq meta
2281mode, the target is out-of-date if the meta file is missing.
2282.It Ic .NOMETA
2283Do not create a meta file for the target.
2284Meta files are also not created for
2285.Ic .PHONY ,
2286.Ic .MAKE ,
2287or
2288.Ic .SPECIAL
2289targets.
2290.It Ic .NOMETA_CMP
2291Ignore differences in commands when deciding if target is out of date.
2292This is useful if the command contains a value which always changes.
2293If the number of commands change, though,
2294the target is still considered out of date.
2295The same effect applies to any command line that uses the variable
2296.Va .OODATE ,
2297which can be used for that purpose even when not otherwise needed or desired:
2298.Bd -literal -offset indent
2299
2300skip-compare-for-some:
2301	@echo this is compared
2302	@echo this is not ${.OODATE:M.NOMETA_CMP}
2303	@echo this is also compared
2304
2305.Ed
2306The
2307.Cm \&:M
2308pattern suppresses any expansion of the unwanted variable.
2309.It Ic .NOPATH
2310Do not search for the target in the directories specified by
2311.Va .PATH .
2312.It Ic .NOTMAIN
2313Normally
2314.Nm
2315selects the first target it encounters as the default target to be built
2316if no target was specified.
2317This source prevents this target from being selected.
2318.It Ic .OPTIONAL
2319If a target is marked with this attribute and
2320.Nm
2321can't figure out how to create it, it ignores this fact and assumes
2322the file isn't needed or already exists.
2323.It Ic .PHONY
2324The target does not correspond to an actual file;
2325it is always considered to be out of date,
2326and is not created with the
2327.Fl t
2328option.
2329Suffix-transformation rules are not applied to
2330.Ic .PHONY
2331targets.
2332.It Ic .PRECIOUS
2333When
2334.Nm
2335is interrupted, it normally removes any partially made targets.
2336This source prevents the target from being removed.
2337.It Ic .RECURSIVE
2338Synonym for
2339.Ic .MAKE .
2340.It Ic .SILENT
2341Do not echo any of the commands associated with this target, exactly
2342as if they all were preceded by an at sign
2343.Pq Ql @ .
2344.It Ic .USE
2345Turn the target into
2346.Nm Ns 's
2347version of a macro.
2348When the target is used as a source for another target, the other target
2349acquires the commands, sources, and attributes (except for
2350.Ic .USE )
2351of the
2352source.
2353If the target already has commands, the
2354.Ic .USE
2355target's commands are appended
2356to them.
2357.It Ic .USEBEFORE
2358Like
2359.Ic .USE ,
2360but instead of appending, prepend the
2361.Ic .USEBEFORE
2362target commands to the target.
2363.It Ic .WAIT
2364If
2365.Ic .WAIT
2366appears in a dependency line, the sources that precede it are
2367made before the sources that succeed it in the line.
2368Since the dependents of files are not made until the file itself
2369could be made, this also stops the dependents being built unless they
2370are needed for another branch of the dependency tree.
2371So given:
2372.Bd -literal
2373x: a .WAIT b
2374	echo x
2375a:
2376	echo a
2377b: b1
2378	echo b
2379b1:
2380	echo b1
2381
2382.Ed
2383the output is always
2384.Ql a ,
2385.Ql b1 ,
2386.Ql b ,
2387.Ql x .
2388.Pp
2389The ordering imposed by
2390.Ic .WAIT
2391is only relevant for parallel makes.
2392.El
2393.Sh SPECIAL TARGETS
2394Special targets may not be included with other targets, i.e. they must be
2395the only target specified.
2396.Bl -tag -width .BEGINx
2397.It Ic .BEGIN
2398Any command lines attached to this target are executed before anything
2399else is done.
2400.It Ic .DEFAULT
2401This is sort of a
2402.Ic .USE
2403rule for any target (that was used only as a source) that
2404.Nm
2405can't figure out any other way to create.
2406Only the shell script is used.
2407The
2408.Va .IMPSRC
2409variable of a target that inherits
2410.Ic .DEFAULT Ns 's
2411commands is set to the target's own name.
2412.It Ic .DELETE_ON_ERROR
2413If this target is present in the makefile, it globally causes make to
2414delete targets whose commands fail.
2415(By default, only targets whose commands are interrupted during
2416execution are deleted.
2417This is the historical behavior.)
2418This setting can be used to help prevent half-finished or malformed
2419targets from being left around and corrupting future rebuilds.
2420.It Ic .END
2421Any command lines attached to this target are executed after everything
2422else is done successfully.
2423.It Ic .ERROR
2424Any command lines attached to this target are executed when another target fails.
2425See
2426.Va MAKE_PRINT_VAR_ON_ERROR
2427for the variables that will be set.
2428.It Ic .IGNORE
2429Mark each of the sources with the
2430.Ic .IGNORE
2431attribute.
2432If no sources are specified, this is the equivalent of specifying the
2433.Fl i
2434option.
2435.It Ic .INTERRUPT
2436If
2437.Nm
2438is interrupted, the commands for this target are executed.
2439.It Ic .MAIN
2440If no target is specified when
2441.Nm
2442is invoked, this target is built.
2443.It Ic .MAKEFLAGS
2444This target provides a way to specify flags for
2445.Nm
2446at the time when the makefiles are read.
2447The flags are as if typed to the shell, though the
2448.Fl f
2449option has
2450no effect.
2451.\" XXX: NOT YET!!!!
2452.\" .It Ic .NOTPARALLEL
2453.\" The named targets are executed in non parallel mode.
2454.\" If no targets are
2455.\" specified, all targets are executed in non parallel mode.
2456.It Ic .NOPATH
2457Apply the
2458.Ic .NOPATH
2459attribute to any specified sources.
2460.It Ic .NOTPARALLEL
2461Disable parallel mode.
2462.It Ic .NO_PARALLEL
2463Synonym for
2464.Ic .NOTPARALLEL ,
2465for compatibility with other pmake variants.
2466.It Ic .NOREADONLY
2467clear the read-only attribute from the global variables specified as sources.
2468.It Ic .OBJDIR
2469The source is a new value for
2470.Sq Va .OBJDIR .
2471If it exists,
2472.Nm
2473changes the current working directory to it and updates the value of
2474.Sq Va .OBJDIR .
2475.It Ic .ORDER
2476In parallel mode, the named targets are made in sequence.
2477This ordering does not add targets to the list of targets to be made.
2478.Pp
2479Since the dependents of a target do not get built until the target itself
2480could be built, unless
2481.Ql a
2482is built by another part of the dependency graph,
2483the following is a dependency loop:
2484.Bd -literal
2485\&.ORDER: b a
2486b: a
2487.Ed
2488.Pp
2489.\" XXX: NOT YET!!!!
2490.\" .It Ic .PARALLEL
2491.\" The named targets are executed in parallel mode.
2492.\" If no targets are
2493.\" specified, all targets are executed in parallel mode.
2494.It Ic .PATH
2495The sources are directories which are to be searched for files not
2496found in the current directory.
2497If no sources are specified,
2498any previously specified directories are removed from the search path.
2499If the source is the special
2500.Ic .DOTLAST
2501target, the current working directory is searched last.
2502.It Ic .PATH. Ns Ar suffix
2503Like
2504.Ic .PATH
2505but applies only to files with a particular suffix.
2506The suffix must have been previously declared with
2507.Ic .SUFFIXES .
2508.It Ic .PHONY
2509Apply the
2510.Ic .PHONY
2511attribute to any specified sources.
2512.It Ic .POSIX
2513If this is the first non-comment line in the main makefile,
2514the variable
2515.Va %POSIX
2516is set to the value
2517.Ql 1003.2
2518and the makefile
2519.Ql <posix.mk>
2520is included if it exists,
2521to provide POSIX-compatible default rules.
2522If
2523.Nm
2524is run with the
2525.Fl r
2526flag, only
2527.Ql posix.mk
2528contributes to the default rules.
2529.It Ic .PRECIOUS
2530Apply the
2531.Ic .PRECIOUS
2532attribute to any specified sources.
2533If no sources are specified, the
2534.Ic .PRECIOUS
2535attribute is applied to every target in the file.
2536.It Ic .READONLY
2537set the read-only attribute on the global variables specified as sources.
2538.It Ic .SHELL
2539Sets the shell that
2540.Nm
2541uses to execute commands.
2542The sources are a set of
2543.Ar field\| Ns Cm \&= Ns Ar value
2544pairs.
2545.Bl -tag -width ".Li hasErrCtls"
2546.It Li name
2547This is the minimal specification, used to select one of the built-in
2548shell specs;
2549.Li sh ,
2550.Li ksh ,
2551and
2552.Li csh .
2553.It Li path
2554Specifies the absolute path to the shell.
2555.It Li hasErrCtl
2556Indicates whether the shell supports exit on error.
2557.It Li check
2558The command to turn on error checking.
2559.It Li ignore
2560The command to disable error checking.
2561.It Li echo
2562The command to turn on echoing of commands executed.
2563.It Li quiet
2564The command to turn off echoing of commands executed.
2565.It Li filter
2566The output to filter after issuing the
2567.Li quiet
2568command.
2569It is typically identical to
2570.Li quiet .
2571.It Li errFlag
2572The flag to pass the shell to enable error checking.
2573.It Li echoFlag
2574The flag to pass the shell to enable command echoing.
2575.It Li newline
2576The string literal to pass the shell that results in a single newline
2577character when used outside of any quoting characters.
2578.El
2579Example:
2580.Bd -literal
2581\&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e
2582	check="set \-e" ignore="set +e" \e
2583	echo="set \-v" quiet="set +v" filter="set +v" \e
2584	echoFlag=v errFlag=e newline="'\en'"
2585.Ed
2586.It Ic .SILENT
2587Apply the
2588.Ic .SILENT
2589attribute to any specified sources.
2590If no sources are specified, the
2591.Ic .SILENT
2592attribute is applied to every
2593command in the file.
2594.It Ic .STALE
2595This target gets run when a dependency file contains stale entries, having
2596.Va .ALLSRC
2597set to the name of that dependency file.
2598.It Ic .SUFFIXES
2599Each source specifies a suffix to
2600.Nm .
2601If no sources are specified, any previously specified suffixes are deleted.
2602It allows the creation of suffix-transformation rules.
2603.Pp
2604Example:
2605.Bd -literal
2606\&.SUFFIXES: .c .o
2607\&.c.o:
2608	cc \-o ${.TARGET} \-c ${.IMPSRC}
2609.Ed
2610.It Ic .SYSPATH
2611The sources are directories which are to be added to the system
2612include path which
2613.Nm
2614searches for makefiles.
2615If no sources are specified,
2616any previously specified directories are removed from the system
2617include path.
2618.El
2619.Sh ENVIRONMENT
2620.Nm
2621uses the following environment variables, if they exist:
2622.Ev MACHINE ,
2623.Ev MACHINE_ARCH ,
2624.Ev MAKE ,
2625.Ev MAKEFLAGS ,
2626.Ev MAKEOBJDIR ,
2627.Ev MAKEOBJDIRPREFIX ,
2628.Ev MAKESYSPATH ,
2629.Ev PWD ,
2630and
2631.Ev TMPDIR .
2632.Pp
2633.Ev MAKEOBJDIRPREFIX
2634and
2635.Ev MAKEOBJDIR
2636may only be set in the environment or on the command line to
2637.Nm
2638and not as makefile variables;
2639see the description of
2640.Sq Va .OBJDIR
2641for more details.
2642.Sh FILES
2643.Bl -tag -width /usr/share/mk -compact
2644.It .depend
2645list of dependencies
2646.It makefile
2647first default makefile if no makefile is specified on the command line
2648.It Makefile
2649second default makefile if no makefile is specified on the command line
2650.It sys.mk
2651system makefile
2652.It /usr/share/mk
2653system makefile directory
2654.El
2655.Sh COMPATIBILITY
2656The basic make syntax is compatible between different make variants;
2657however the special variables, variable modifiers and conditionals are not.
2658.Ss Older versions
2659An incomplete list of changes in older versions of
2660.Nm :
2661.Pp
2662The way that .for loop variables are substituted changed after
2663.Nx 5.0
2664so that they still appear to be variable expansions.
2665In particular this stops them being treated as syntax, and removes some
2666obscure problems using them in .if statements.
2667.Pp
2668The way that parallel makes are scheduled changed in
2669.Nx 4.0
2670so that .ORDER and .WAIT apply recursively to the dependent nodes.
2671The algorithms used may change again in the future.
2672.Ss Other make dialects
2673Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not
2674support most of the features of
2675.Nm
2676as described in this manual.
2677Most notably:
2678.Bl -bullet -offset indent
2679.It
2680The
2681.Ic .WAIT
2682and
2683.Ic .ORDER
2684declarations and most functionality pertaining to parallelization.
2685(GNU make supports parallelization but lacks the features needed to
2686control it effectively.)
2687.It
2688Directives, including for loops and conditionals and most of the
2689forms of include files.
2690(GNU make has its own incompatible and less powerful syntax for
2691conditionals.)
2692.\" The "less powerful" above means that GNU make does not have the
2693.\" make(target), target(target) and commands(target) functions.
2694.It
2695All built-in variables that begin with a dot.
2696.It
2697Most of the special sources and targets that begin with a dot,
2698with the notable exception of
2699.Ic .PHONY ,
2700.Ic .PRECIOUS ,
2701and
2702.Ic .SUFFIXES .
2703.It
2704Variable modifiers, except for the
2705.Ql :old=new
2706string substitution, which does not portably support globbing with
2707.Ql %
2708and historically only works on declared suffixes.
2709.It
2710The
2711.Ic $>
2712variable even in its short form; most makes support this functionality
2713but its name varies.
2714.El
2715.Pp
2716Some features are somewhat more portable, such as assignment with
2717.Ic += ,
2718.Ic ?= ,
2719and
2720.Ic != .
2721The
2722.Va .PATH
2723functionality is based on an older feature
2724.Ic VPATH
2725found in GNU make and many versions of SVR4 make; however,
2726historically its behavior is too ill-defined (and too buggy) to rely
2727upon.
2728.Pp
2729The
2730.Ic $@
2731and
2732.Ic $<
2733variables are more or less universally portable, as is the
2734.Ic $(MAKE)
2735variable.
2736Basic use of suffix rules (for files only in the current directory,
2737not trying to chain transformations together, etc.) is also reasonably
2738portable.
2739.Sh SEE ALSO
2740.Xr mkdep 1 ,
2741.Xr style.Makefile 5
2742.Sh HISTORY
2743A
2744.Nm
2745command appeared in
2746.At v7 .
2747This
2748.Nm
2749implementation is based on Adam de Boor's pmake program,
2750which was written for Sprite at Berkeley.
2751It was designed to be a parallel distributed make running jobs on different
2752machines using a daemon called
2753.Dq customs .
2754.Pp
2755Historically the target/dependency
2756.Ic FRC
2757has been used to FoRCe rebuilding (since the target/dependency
2758does not exist ... unless someone creates an
2759.Pa FRC
2760file).
2761.Sh BUGS
2762The
2763.Nm
2764syntax is difficult to parse.
2765For instance, finding the end of a variable's use should involve scanning
2766each of the modifiers, using the correct terminator for each field.
2767In many places
2768.Nm
2769just counts {} and () in order to find the end of a variable expansion.
2770.Pp
2771There is no way of escaping a space character in a filename.
2772.Pp
2773In jobs mode, when a target fails;
2774.Nm
2775will put an error token into the job token pool.
2776This will cause all other instances of
2777.Nm
2778using that token pool to abort the build and exit with error code 6.
2779Sometimes the attempt to suppress a cascade of unnecessary errors,
2780can result in a seemingly unexplained
2781.Ql *** Error code 6
2782