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