xref: /freebsd/contrib/bmake/bmake.1 (revision b85b9c88eb02298ea7fa3885619f54ac0e930ba4)
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 BMAKE 1
34.Os
35.Sh NAME
36.Nm bmake
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.DEPENDFILE
841Names the makefile (default
842.Ql Pa .depend )
843from which generated dependencies are read.
844.It Va .MAKE.EXPAND_VARIABLES
845A boolean that controls the default behavior of the
846.Fl V
847option.
848If true, variable values printed with
849.Fl V
850are fully expanded; if false, the raw variable contents (which may
851include additional unexpanded variable references) are shown.
852.It Va .MAKE.EXPORTED
853The list of variables exported by
854.Nm .
855.It Va .MAKE.JOBS
856The argument to the
857.Fl j
858option.
859.It Va .MAKE.JOB.PREFIX
860If
861.Nm
862is run with
863.Ar j
864then output for each target is prefixed with a token
865.Ql --- target ---
866the first part of which can be controlled via
867.Va .MAKE.JOB.PREFIX .
868If
869.Va .MAKE.JOB.PREFIX
870is empty, no token is printed.
871.br
872For example:
873.Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}]
874would produce tokens like
875.Ql ---make[1234] target ---
876making it easier to track the degree of parallelism being achieved.
877.It .MAKE.TARGET_LOCAL_VARIABLES
878If set to
879.Ql false ,
880apparent variable assignments in dependency lines are
881treated as normal sources.
882.It Ev MAKEFLAGS
883The environment variable
884.Ql Ev MAKEFLAGS
885may contain anything that
886may be specified on
887.Nm Ns 's
888command line.
889Anything specified on
890.Nm Ns 's
891command line is appended to the
892.Ql Ev MAKEFLAGS
893variable which is then
894entered into the environment for all programs which
895.Nm
896executes.
897.It Va .MAKE.LEVEL
898The recursion depth of
899.Nm .
900The initial instance of
901.Nm
902will be 0, and an incremented value is put into the environment
903to be seen by the next generation.
904This allows tests like:
905.Li .if ${.MAKE.LEVEL} == 0
906to protect things which should only be evaluated in the initial instance of
907.Nm .
908.It Va .MAKE.MAKEFILE_PREFERENCE
909The ordered list of makefile names
910(default
911.Ql Pa makefile ,
912.Ql Pa Makefile )
913that
914.Nm
915will look for.
916.It Va .MAKE.MAKEFILES
917The list of makefiles read by
918.Nm ,
919which is useful for tracking dependencies.
920Each makefile is recorded only once, regardless of the number of times read.
921.It Va .MAKE.MODE
922Processed after reading all makefiles.
923Can affect the mode that
924.Nm
925runs in.
926It can contain a number of keywords:
927.Bl -hang -width missing-filemon=bf.
928.It Pa compat
929Like
930.Fl B ,
931puts
932.Nm
933into "compat" mode.
934.It Pa meta
935Puts
936.Nm
937into "meta" mode, where meta files are created for each target
938to capture the command run, the output generated and if
939.Xr filemon 4
940is available, the system calls which are of interest to
941.Nm .
942The captured output can be very useful when diagnosing errors.
943.It Pa curdirOk= Ar bf
944Normally
945.Nm
946will not create .meta files in
947.Ql Va .CURDIR .
948This can be overridden by setting
949.Va bf
950to a value which represents True.
951.It Pa missing-meta= Ar bf
952If
953.Va bf
954is True, then a missing .meta file makes the target out-of-date.
955.It Pa missing-filemon= Ar bf
956If
957.Va bf
958is True, then missing filemon data makes the target out-of-date.
959.It Pa nofilemon
960Do not use
961.Xr filemon 4 .
962.It Pa env
963For debugging, it can be useful to include the environment
964in the .meta file.
965.It Pa verbose
966If in "meta" mode, print a clue about the target being built.
967This is useful if the build is otherwise running silently.
968The message printed the value of:
969.Va .MAKE.META.PREFIX .
970.It Pa ignore-cmd
971Some makefiles have commands which are simply not stable.
972This keyword causes them to be ignored for
973determining whether a target is out of date in "meta" mode.
974See also
975.Ic .NOMETA_CMP .
976.It Pa silent= Ar bf
977If
978.Va bf
979is True, when a .meta file is created, mark the target
980.Ic .SILENT .
981.El
982.It Va .MAKE.META.BAILIWICK
983In "meta" mode, provides a list of prefixes which
984match the directories controlled by
985.Nm .
986If a file that was generated outside of
987.Va .OBJDIR
988but within said bailiwick is missing,
989the current target is considered out-of-date.
990.It Va .MAKE.META.CMP_FILTER
991In "meta" mode, it can (very rarely!) be useful to filter command
992lines before comparison.
993This variable can be set to a set of modifiers that will be applied to
994each line of the old and new command that differ, if the filtered
995commands still differ, the target is considered out-of-date.
996.It Va .MAKE.META.CREATED
997In "meta" mode, this variable contains a list of all the meta files
998updated.
999If not empty, it can be used to trigger processing of
1000.Va .MAKE.META.FILES .
1001.It Va .MAKE.META.FILES
1002In "meta" mode, this variable contains a list of all the meta files
1003used (updated or not).
1004This list can be used to process the meta files to extract dependency
1005information.
1006.It Va .MAKE.META.IGNORE_PATHS
1007Provides a list of path prefixes that should be ignored;
1008because the contents are expected to change over time.
1009The default list includes:
1010.Ql Pa /dev /etc /proc /tmp /var/run /var/tmp
1011.It Va .MAKE.META.IGNORE_PATTERNS
1012Provides a list of patterns to match against pathnames.
1013Ignore any that match.
1014.It Va .MAKE.META.IGNORE_FILTER
1015Provides a list of variable modifiers to apply to each pathname.
1016Ignore if the expansion is an empty string.
1017.It Va .MAKE.META.PREFIX
1018Defines the message printed for each meta file updated in "meta verbose" mode.
1019The default value is:
1020.Dl Building ${.TARGET:H:tA}/${.TARGET:T}
1021.It Va .MAKEOVERRIDES
1022This variable is used to record the names of variables assigned to
1023on the command line, so that they may be exported as part of
1024.Ql Ev MAKEFLAGS .
1025This behavior can be disabled by assigning an empty value to
1026.Ql Va .MAKEOVERRIDES
1027within a makefile.
1028Extra variables can be exported from a makefile
1029by appending their names to
1030.Ql Va .MAKEOVERRIDES .
1031.Ql Ev MAKEFLAGS
1032is re-exported whenever
1033.Ql Va .MAKEOVERRIDES
1034is modified.
1035.It Va .MAKE.PATH_FILEMON
1036If
1037.Nm
1038was built with
1039.Xr filemon 4
1040support, this is set to the path of the device node.
1041This allows makefiles to test for this support.
1042.It Va .MAKE.PID
1043The process-id of
1044.Nm .
1045.It Va .MAKE.PPID
1046The parent process-id of
1047.Nm .
1048.It Va .MAKE.SAVE_DOLLARS
1049value should be a boolean that controls whether
1050.Ql $$
1051are preserved when doing
1052.Ql :=
1053assignments.
1054The default is false, for backwards compatibility.
1055Set to true for compatability with other makes.
1056If set to false,
1057.Ql $$
1058becomes
1059.Ql $
1060per normal evaluation rules.
1061.It Va .MAKE.UID
1062The user-id running
1063.Nm .
1064.It Va .MAKE.GID
1065The group-id running
1066.Nm .
1067.It Va MAKE_PRINT_VAR_ON_ERROR
1068When
1069.Nm
1070stops due to an error, it sets
1071.Ql Va .ERROR_TARGET
1072to the name of the target that failed,
1073.Ql Va .ERROR_CMD
1074to the commands of the failed target,
1075and in "meta" mode, it also sets
1076.Ql Va .ERROR_CWD
1077to the
1078.Xr getcwd 3 ,
1079and
1080.Ql Va .ERROR_META_FILE
1081to the path of the meta file (if any) describing the failed target.
1082It then prints its name and the value of
1083.Ql Va .CURDIR
1084as well as the value of any variables named in
1085.Ql Va MAKE_PRINT_VAR_ON_ERROR .
1086.It Va .newline
1087This variable is simply assigned a newline character as its value.
1088This allows expansions using the
1089.Cm \&:@
1090modifier to put a newline between
1091iterations of the loop rather than a space.
1092For example, the printing of
1093.Ql Va MAKE_PRINT_VAR_ON_ERROR
1094could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}.
1095.It Va .OBJDIR
1096A path to the directory where the targets are built.
1097Its value is determined by trying to
1098.Xr chdir 2
1099to the following directories in order and using the first match:
1100.Bl -enum
1101.It
1102.Ev ${MAKEOBJDIRPREFIX}${.CURDIR}
1103.Pp
1104(Only if
1105.Ql Ev MAKEOBJDIRPREFIX
1106is set in the environment or on the command line.)
1107.It
1108.Ev ${MAKEOBJDIR}
1109.Pp
1110(Only if
1111.Ql Ev MAKEOBJDIR
1112is set in the environment or on the command line.)
1113.It
1114.Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE}
1115.It
1116.Ev ${.CURDIR} Ns Pa /obj
1117.It
1118.Pa /usr/obj/ Ns Ev ${.CURDIR}
1119.It
1120.Ev ${.CURDIR}
1121.El
1122.Pp
1123Variable expansion is performed on the value before it's used,
1124so expressions such as
1125.Dl ${.CURDIR:S,^/usr/src,/var/obj,}
1126may be used.
1127This is especially useful with
1128.Ql Ev MAKEOBJDIR .
1129.Pp
1130.Ql Va .OBJDIR
1131may be modified in the makefile via the special target
1132.Ql Ic .OBJDIR .
1133In all cases,
1134.Nm
1135will
1136.Xr chdir 2
1137to the specified directory if it exists, and set
1138.Ql Va .OBJDIR
1139and
1140.Ql Ev PWD
1141to that directory before executing any targets.
1142.Pp
1143Except in the case of an explicit
1144.Ql Ic .OBJDIR
1145target,
1146.Nm
1147will check that the specified directory is writable and ignore it if not.
1148This check can be skipped by setting the environment variable
1149.Ql Ev MAKE_OBJDIR_CHECK_WRITABLE
1150to "no".
1151.
1152.It Va .PARSEDIR
1153A path to the directory of the current
1154.Ql Pa Makefile
1155being parsed.
1156.It Va .PARSEFILE
1157The basename of the current
1158.Ql Pa Makefile
1159being parsed.
1160This variable and
1161.Ql Va .PARSEDIR
1162are both set only while the
1163.Ql Pa Makefiles
1164are being parsed.
1165If you want to retain their current values, assign them to a variable
1166using assignment with expansion:
1167.Pq Ql Cm \&:= .
1168.It Va .PATH
1169A variable that represents the list of directories that
1170.Nm
1171will search for files.
1172The search list should be updated using the target
1173.Ql Va .PATH
1174rather than the variable.
1175.It Ev PWD
1176Alternate path to the current directory.
1177.Nm
1178normally sets
1179.Ql Va .CURDIR
1180to the canonical path given by
1181.Xr getcwd 3 .
1182However, if the environment variable
1183.Ql Ev PWD
1184is set and gives a path to the current directory, then
1185.Nm
1186sets
1187.Ql Va .CURDIR
1188to the value of
1189.Ql Ev PWD
1190instead.
1191This behavior is disabled if
1192.Ql Ev MAKEOBJDIRPREFIX
1193is set or
1194.Ql Ev MAKEOBJDIR
1195contains a variable transform.
1196.Ql Ev PWD
1197is set to the value of
1198.Ql Va .OBJDIR
1199for all programs which
1200.Nm
1201executes.
1202.It Ev .SHELL
1203The pathname of the shell used to run target scripts.
1204It is read-only.
1205.It Ev .SUFFIXES
1206The list of known suffixes.
1207It is read-only.
1208.It Ev .TARGETS
1209The list of targets explicitly specified on the command line, if any.
1210.It Ev VPATH
1211Colon-separated
1212.Pq Dq \&:
1213lists of directories that
1214.Nm
1215will search for files.
1216The variable is supported for compatibility with old make programs only,
1217use
1218.Ql Va .PATH
1219instead.
1220.El
1221.Ss Variable modifiers
1222Variable expansion may be modified to select or modify each word of the
1223variable (where a
1224.Dq word
1225is white-space delimited sequence of characters).
1226The general format of a variable expansion is as follows:
1227.Pp
1228.Dl ${variable[:modifier[:...]]}
1229.Pp
1230Each modifier begins with a colon,
1231which may be escaped with a backslash
1232.Pq Ql \e .
1233.Pp
1234A set of modifiers can be specified via a variable, as follows:
1235.Pp
1236.Dl modifier_variable=modifier[:...]
1237.Dl ${variable:${modifier_variable}[:...]}
1238.Pp
1239In this case the first modifier in the modifier_variable does not
1240start with a colon, since that must appear in the referencing
1241variable.
1242If any of the modifiers in the modifier_variable contain a dollar sign
1243.Pq Ql $ ,
1244these must be doubled to avoid early expansion.
1245.Pp
1246The supported modifiers are:
1247.Bl -tag -width EEE
1248.It Cm \&:E
1249Replaces each word in the variable with its suffix.
1250.It Cm \&:H
1251Replaces each word in the variable with everything but the last component.
1252.It Cm \&:M Ns Ar pattern
1253Selects only those words that match
1254.Ar pattern .
1255The standard shell wildcard characters
1256.Pf ( Ql * ,
1257.Ql \&? ,
1258and
1259.Ql Oo Oc )
1260may
1261be used.
1262The wildcard characters may be escaped with a backslash
1263.Pq Ql \e .
1264As a consequence of the way values are split into words, matched,
1265and then joined, a construct like
1266.Dl ${VAR:M*}
1267will normalize the inter-word spacing, removing all leading and
1268trailing space, and converting multiple consecutive spaces
1269to single spaces.
1270.
1271.It Cm \&:N Ns Ar pattern
1272This is identical to
1273.Ql Cm \&:M ,
1274but selects all words which do not match
1275.Ar pattern .
1276.It Cm \&:O
1277Orders every word in variable alphabetically.
1278.It Cm \&:On
1279Orders every word in variable numerically.
1280A number followed by one of
1281.Ql k ,
1282.Ql M
1283or
1284.Ql G
1285is multiplied by the appropriate factor (1024 (k), 1048576 (M), or
12861073741824 (G)).
1287Both upper- and lower-case letters are accepted.
1288.It Cm \&:Or
1289Orders every word in variable in reverse alphabetical order.
1290.It Cm \&:Orn
1291Orders every word in variable in reverse numerical order.
1292.It Cm \&:Ox
1293Shuffles the words in variable.
1294The results will be different each time you are referring to the
1295modified variable; use the assignment with expansion
1296.Pq Ql Cm \&:=
1297to prevent such behavior.
1298For example,
1299.Bd -literal -offset indent
1300LIST=			uno due tre quattro
1301RANDOM_LIST=		${LIST:Ox}
1302STATIC_RANDOM_LIST:=	${LIST:Ox}
1303
1304all:
1305	@echo "${RANDOM_LIST}"
1306	@echo "${RANDOM_LIST}"
1307	@echo "${STATIC_RANDOM_LIST}"
1308	@echo "${STATIC_RANDOM_LIST}"
1309.Ed
1310may produce output similar to:
1311.Bd -literal -offset indent
1312quattro due tre uno
1313tre due quattro uno
1314due uno quattro tre
1315due uno quattro tre
1316.Ed
1317.It Cm \&:Q
1318Quotes every shell meta-character in the variable, so that it can be passed
1319safely to the shell.
1320.It Cm \&:q
1321Quotes every shell meta-character in the variable, and also doubles
1322.Sq $
1323characters so that it can be passed
1324safely through recursive invocations of
1325.Nm .
1326This is equivalent to:
1327.Sq \&:S/\e\&$/&&/g:Q .
1328.It Cm \&:R
1329Replaces each word in the variable with everything but its suffix.
1330.It Cm \&:range[=count]
1331The value is an integer sequence representing the words of the original
1332value, or the supplied
1333.Va count .
1334.It Cm \&:gmtime[=utc]
1335The value is a format string for
1336.Xr strftime 3 ,
1337using
1338.Xr gmtime 3 .
1339If a
1340.Va utc
1341value is not provided or is 0, the current time is used.
1342.It Cm \&:hash
1343Computes a 32-bit hash of the value and encode it as hex digits.
1344.It Cm \&:localtime[=utc]
1345The value is a format string for
1346.Xr strftime 3 ,
1347using
1348.Xr localtime 3 .
1349If a
1350.Va utc
1351value is not provided or is 0, the current time is used.
1352.It Cm \&:tA
1353Attempts to convert variable to an absolute path using
1354.Xr realpath 3 ,
1355if that fails, the value is unchanged.
1356.It Cm \&:tl
1357Converts variable to lower-case letters.
1358.It Cm \&:ts Ns Ar c
1359Words in the variable are normally separated by a space on expansion.
1360This modifier sets the separator to the character
1361.Ar c .
1362If
1363.Ar c
1364is omitted, then no separator is used.
1365The common escapes (including octal numeric codes) work as expected.
1366.It Cm \&:tu
1367Converts variable to upper-case letters.
1368.It Cm \&:tW
1369Causes the value to be treated as a single word
1370(possibly containing embedded white space).
1371See also
1372.Ql Cm \&:[*] .
1373.It Cm \&:tw
1374Causes the value to be treated as a sequence of
1375words delimited by white space.
1376See also
1377.Ql Cm \&:[@] .
1378.Sm off
1379.It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW
1380.Sm on
1381Modifies the first occurrence of
1382.Ar old_string
1383in each word of the variable's value, replacing it with
1384.Ar new_string .
1385If a
1386.Ql g
1387is appended to the last delimiter of the pattern, all occurrences
1388in each word are replaced.
1389If a
1390.Ql 1
1391is appended to the last delimiter of the pattern, only the first occurrence
1392is affected.
1393If a
1394.Ql W
1395is appended to the last delimiter of the pattern,
1396then the value is treated as a single word
1397(possibly containing embedded white space).
1398If
1399.Ar old_string
1400begins with a caret
1401.Pq Ql ^ ,
1402.Ar old_string
1403is anchored at the beginning of each word.
1404If
1405.Ar old_string
1406ends with a dollar sign
1407.Pq Ql \&$ ,
1408it is anchored at the end of each word.
1409Inside
1410.Ar new_string ,
1411an ampersand
1412.Pq Ql &
1413is replaced by
1414.Ar old_string
1415(without any
1416.Ql ^
1417or
1418.Ql \&$ ) .
1419Any character may be used as a delimiter for the parts of the modifier
1420string.
1421The anchoring, ampersand and delimiter characters may be escaped with a
1422backslash
1423.Pq Ql \e .
1424.Pp
1425Variable expansion occurs in the normal fashion inside both
1426.Ar old_string
1427and
1428.Ar new_string
1429with the single exception that a backslash is used to prevent the expansion
1430of a dollar sign
1431.Pq Ql \&$ ,
1432not a preceding dollar sign as is usual.
1433.Sm off
1434.It Cm \&:C No \&/ Ar pattern No \&/ Ar replacement No \&/ Op Cm 1gW
1435.Sm on
1436The
1437.Cm \&:C
1438modifier is just like the
1439.Cm \&:S
1440modifier except that the old and new strings, instead of being
1441simple strings, are an extended regular expression (see
1442.Xr regex 3 )
1443string
1444.Ar pattern
1445and an
1446.Xr ed 1 Ns \-style
1447string
1448.Ar replacement .
1449Normally, the first occurrence of the pattern
1450.Ar pattern
1451in each word of the value is substituted with
1452.Ar replacement .
1453The
1454.Ql 1
1455modifier causes the substitution to apply to at most one word; the
1456.Ql g
1457modifier causes the substitution to apply to as many instances of the
1458search pattern
1459.Ar pattern
1460as occur in the word or words it is found in; the
1461.Ql W
1462modifier causes the value to be treated as a single word
1463(possibly containing embedded white space).
1464.Pp
1465As for the
1466.Cm \&:S
1467modifier, the
1468.Ar pattern
1469and
1470.Ar replacement
1471are subjected to variable expansion before being parsed as
1472regular expressions.
1473.It Cm \&:T
1474Replaces each word in the variable with its last path component.
1475.It Cm \&:u
1476Removes adjacent duplicate words (like
1477.Xr uniq 1 ) .
1478.Sm off
1479.It Cm \&:\&? Ar true_string Cm \&: Ar false_string
1480.Sm on
1481If the variable name (not its value), when parsed as a .if conditional
1482expression, evaluates to true, return as its value the
1483.Ar true_string ,
1484otherwise return the
1485.Ar false_string .
1486Since the variable name is used as the expression, \&:\&? must be the
1487first modifier after the variable name itself - which will, of course,
1488usually contain variable expansions.
1489A common error is trying to use expressions like
1490.Dl ${NUMBERS:M42:?match:no}
1491which actually tests defined(NUMBERS),
1492to determine if any words match "42" you need to use something like:
1493.Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} .
1494.It Ar :old_string=new_string
1495This is the
1496.At V
1497style variable substitution.
1498It must be the last modifier specified.
1499If
1500.Ar old_string
1501or
1502.Ar new_string
1503do not contain the pattern matching character
1504.Ar %
1505then it is assumed that they are
1506anchored at the end of each word, so only suffixes or entire
1507words may be replaced.
1508Otherwise
1509.Ar %
1510is the substring of
1511.Ar old_string
1512to be replaced in
1513.Ar new_string .
1514If only
1515.Ar old_string
1516contains the pattern matching character
1517.Ar % ,
1518and
1519.Ar old_string
1520matches, then the result is the
1521.Ar new_string .
1522If only the
1523.Ar new_string
1524contains the pattern matching character
1525.Ar % ,
1526then it is not treated specially and it is printed as a literal
1527.Ar %
1528on match.
1529If there is more than one pattern matching character
1530.Ar ( % )
1531in either the
1532.Ar new_string
1533or
1534.Ar old_string ,
1535only the first instance is treated specially (as the pattern character);
1536all subsequent instances are treated as regular characters.
1537.Pp
1538Variable expansion occurs in the normal fashion inside both
1539.Ar old_string
1540and
1541.Ar new_string
1542with the single exception that a backslash is used to prevent the
1543expansion of a dollar sign
1544.Pq Ql \&$ ,
1545not a preceding dollar sign as is usual.
1546.Sm off
1547.It Cm \&:@ Ar temp Cm @ Ar string Cm @
1548.Sm on
1549This is the loop expansion mechanism from the OSF Development
1550Environment (ODE) make.
1551Unlike
1552.Cm \&.for
1553loops, expansion occurs at the time of reference.
1554Assigns
1555.Ar temp
1556to each word in the variable and evaluates
1557.Ar string .
1558The ODE convention is that
1559.Ar temp
1560should start and end with a period.
1561For example.
1562.Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
1563.Pp
1564However a single character variable is often more readable:
1565.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
1566.It Cm \&:_[=var]
1567Saves the current variable value in
1568.Ql $_
1569or the named
1570.Va var
1571for later reference.
1572Example usage:
1573.Bd -literal -offset indent
1574M_cmpv.units = 1 1000 1000000
1575M_cmpv = S,., ,g:_:range:@i@+ $${_:[-$$i]} \&\\
1576\\* $${M_cmpv.units:[$$i]}@:S,^,expr 0 ,1:sh
1577
1578.Dv .if ${VERSION:${M_cmpv}} < ${3.1.12:L:${M_cmpv}}
1579
1580.Ed
1581Here
1582.Ql $_
1583is used to save the result of the
1584.Ql :S
1585modifier which is later referenced using the index values from
1586.Ql :range .
1587.It Cm \&:U Ns Ar newval
1588If the variable is undefined,
1589.Ar newval
1590is the value.
1591If the variable is defined, the existing value is returned.
1592This is another ODE make feature.
1593It is handy for setting per-target CFLAGS for instance:
1594.Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
1595If a value is only required if the variable is undefined, use:
1596.Dl ${VAR:D:Unewval}
1597.It Cm \&:D Ns Ar newval
1598If the variable is defined,
1599.Ar newval
1600is the value.
1601.It Cm \&:L
1602The name of the variable is the value.
1603.It Cm \&:P
1604The path of the node which has the same name as the variable
1605is the value.
1606If no such node exists or its path is null, then the
1607name of the variable is used.
1608In order for this modifier to work, the name (node) must at least have
1609appeared on the rhs of a dependency.
1610.Sm off
1611.It Cm \&:\&! Ar cmd Cm \&!
1612.Sm on
1613The output of running
1614.Ar cmd
1615is the value.
1616.It Cm \&:sh
1617If the variable is non-empty it is run as a command and the output
1618becomes the new value.
1619.It Cm \&::= Ns Ar str
1620The variable is assigned the value
1621.Ar str
1622after substitution.
1623This modifier and its variations are useful in
1624obscure situations such as wanting to set a variable when shell commands
1625are being parsed.
1626These assignment modifiers always expand to
1627nothing, so if appearing in a rule line by themselves should be
1628preceded with something to keep
1629.Nm
1630happy.
1631.Pp
1632The
1633.Ql Cm \&::
1634helps avoid false matches with the
1635.At V
1636style
1637.Cm \&:=
1638modifier and since substitution always occurs the
1639.Cm \&::=
1640form is vaguely appropriate.
1641.It Cm \&::?= Ns Ar str
1642As for
1643.Cm \&::=
1644but only if the variable does not already have a value.
1645.It Cm \&::+= Ns Ar str
1646Append
1647.Ar str
1648to the variable.
1649.It Cm \&::!= Ns Ar cmd
1650Assign the output of
1651.Ar cmd
1652to the variable.
1653.It Cm \&:\&[ Ns Ar range Ns Cm \&]
1654Selects one or more words from the value,
1655or performs other operations related to the way in which the
1656value is divided into words.
1657.Pp
1658Ordinarily, a value is treated as a sequence of words
1659delimited by white space.
1660Some modifiers suppress this behavior,
1661causing a value to be treated as a single word
1662(possibly containing embedded white space).
1663An empty value, or a value that consists entirely of white-space,
1664is treated as a single word.
1665For the purposes of the
1666.Ql Cm \&:[]
1667modifier, the words are indexed both forwards using positive integers
1668(where index 1 represents the first word),
1669and backwards using negative integers
1670(where index \-1 represents the last word).
1671.Pp
1672The
1673.Ar range
1674is subjected to variable expansion, and the expanded result is
1675then interpreted as follows:
1676.Bl -tag -width index
1677.\" :[n]
1678.It Ar index
1679Selects a single word from the value.
1680.\" :[start..end]
1681.It Ar start Ns Cm \&.. Ns Ar end
1682Selects all words from
1683.Ar start
1684to
1685.Ar end ,
1686inclusive.
1687For example,
1688.Ql Cm \&:[2..-1]
1689selects all words from the second word to the last word.
1690If
1691.Ar start
1692is greater than
1693.Ar end ,
1694then the words are output in reverse order.
1695For example,
1696.Ql Cm \&:[-1..1]
1697selects all the words from last to first.
1698If the list is already ordered, then this effectively reverses
1699the list, but it is more efficient to use
1700.Ql Cm \&:Or
1701instead of
1702.Ql Cm \&:O:[-1..1] .
1703.\" :[*]
1704.It Cm \&*
1705Causes subsequent modifiers to treat the value as a single word
1706(possibly containing embedded white space).
1707Analogous to the effect of
1708\&"$*\&"
1709in Bourne shell.
1710.\" :[0]
1711.It 0
1712Means the same as
1713.Ql Cm \&:[*] .
1714.\" :[*]
1715.It Cm \&@
1716Causes subsequent modifiers to treat the value as a sequence of words
1717delimited by white space.
1718Analogous to the effect of
1719\&"$@\&"
1720in Bourne shell.
1721.\" :[#]
1722.It Cm \&#
1723Returns the number of words in the value.
1724.El \" :[range]
1725.El
1726.Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1727Makefile inclusion, conditional structures and for loops reminiscent
1728of the C programming language are provided in
1729.Nm .
1730All such structures are identified by a line beginning with a single
1731dot
1732.Pq Ql \&.
1733character.
1734Files are included with either
1735.Cm \&.include \&< Ns Ar file Ns Cm \&>
1736or
1737.Cm \&.include \&\*q Ns Ar file Ns Cm \&\*q .
1738Variables between the angle brackets or double quotes are expanded
1739to form the file name.
1740If angle brackets are used, the included makefile is expected to be in
1741the system makefile directory.
1742If double quotes are used, the including makefile's directory and any
1743directories specified using the
1744.Fl I
1745option are searched before the system
1746makefile directory.
1747For compatibility with other versions of
1748.Nm
1749.Ql include file ...
1750is also accepted.
1751.Pp
1752If the include statement is written as
1753.Cm .-include
1754or as
1755.Cm .sinclude
1756then errors locating and/or opening include files are ignored.
1757.Pp
1758If the include statement is written as
1759.Cm .dinclude
1760not only are errors locating and/or opening include files ignored,
1761but stale dependencies within the included file will be ignored
1762just like
1763.Va .MAKE.DEPENDFILE .
1764.Pp
1765Conditional expressions are also preceded by a single dot as the first
1766character of a line.
1767The possible conditionals are as follows:
1768.Bl -tag -width Ds
1769.It Ic .error Ar message
1770The message is printed along with the name of the makefile and line number,
1771then
1772.Nm
1773will exit immediately.
1774.It Ic .export Ar variable ...
1775Export the specified global variable.
1776If no variable list is provided, all globals are exported
1777except for internal variables (those that start with
1778.Ql \&. ) .
1779This is not affected by the
1780.Fl X
1781flag, so should be used with caution.
1782For compatibility with other
1783.Nm
1784programs
1785.Ql export variable=value
1786is also accepted.
1787.Pp
1788Appending a variable name to
1789.Va .MAKE.EXPORTED
1790is equivalent to exporting a variable.
1791.It Ic .export-env Ar variable ...
1792The same as
1793.Ql .export ,
1794except that the variable is not appended to
1795.Va .MAKE.EXPORTED .
1796This allows exporting a value to the environment which is different from that
1797used by
1798.Nm
1799internally.
1800.It Ic .export-literal Ar variable ...
1801The same as
1802.Ql .export-env ,
1803except that variables in the value are not expanded.
1804.It Ic .info Ar message
1805The message is printed along with the name of the makefile and line number.
1806.It Ic .undef Ar variable ...
1807Un-define the specified global variables.
1808Only global variables can be un-defined.
1809.It Ic .unexport Ar variable ...
1810The opposite of
1811.Ql .export .
1812The specified global
1813.Va variable
1814will be removed from
1815.Va .MAKE.EXPORTED .
1816If no variable list is provided, all globals are unexported,
1817and
1818.Va .MAKE.EXPORTED
1819deleted.
1820.It Ic .unexport-env
1821Unexport all globals previously exported and
1822clear the environment inherited from the parent.
1823This operation will cause a memory leak of the original environment,
1824so should be used sparingly.
1825Testing for
1826.Va .MAKE.LEVEL
1827being 0, would make sense.
1828Also note that any variables which originated in the parent environment
1829should be explicitly preserved if desired.
1830For example:
1831.Bd -literal -offset indent
1832.Li .if ${.MAKE.LEVEL} == 0
1833PATH := ${PATH}
1834.Li .unexport-env
1835.Li .export PATH
1836.Li .endif
1837.Pp
1838.Ed
1839Would result in an environment containing only
1840.Ql Ev PATH ,
1841which is the minimal useful environment.
1842Actually
1843.Ql Ev .MAKE.LEVEL
1844will also be pushed into the new environment.
1845.It Ic .warning Ar message
1846The message prefixed by
1847.Ql Pa warning:
1848is printed along with the name of the makefile and line number.
1849.It Ic \&.if Oo \&! Oc Ns Ar expression Op Ar operator expression ...
1850Test the value of an expression.
1851.It Ic .ifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1852Test the value of a variable.
1853.It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1854Test the value of a variable.
1855.It Ic .ifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1856Test the target being built.
1857.It Ic .ifnmake Oo \&! Ns Oc Ar target Op Ar operator target ...
1858Test the target being built.
1859.It Ic .else
1860Reverse the sense of the last conditional.
1861.It Ic .elif Oo \&! Ns Oc Ar expression Op Ar operator expression ...
1862A combination of
1863.Ql Ic .else
1864followed by
1865.Ql Ic .if .
1866.It Ic .elifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1867A combination of
1868.Ql Ic .else
1869followed by
1870.Ql Ic .ifdef .
1871.It Ic .elifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1872A combination of
1873.Ql Ic .else
1874followed by
1875.Ql Ic .ifndef .
1876.It Ic .elifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1877A combination of
1878.Ql Ic .else
1879followed by
1880.Ql Ic .ifmake .
1881.It Ic .elifnmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1882A combination of
1883.Ql Ic .else
1884followed by
1885.Ql Ic .ifnmake .
1886.It Ic .endif
1887End the body of the conditional.
1888.El
1889.Pp
1890The
1891.Ar operator
1892may be any one of the following:
1893.Bl -tag -width "Cm XX"
1894.It Cm \&|\&|
1895Logical OR.
1896.It Cm \&&&
1897Logical
1898.Tn AND ;
1899of higher precedence than
1900.Dq \&|\&| .
1901.El
1902.Pp
1903As in C,
1904.Nm
1905will only evaluate a conditional as far as is necessary to determine
1906its value.
1907Parentheses may be used to change the order of evaluation.
1908The boolean operator
1909.Ql Ic \&!
1910may be used to logically negate an entire
1911conditional.
1912It is of higher precedence than
1913.Ql Ic \&&& .
1914.Pp
1915The value of
1916.Ar expression
1917may be any of the following:
1918.Bl -tag -width defined
1919.It Ic defined
1920Takes a variable name as an argument and evaluates to true if the variable
1921has been defined.
1922.It Ic make
1923Takes a target name as an argument and evaluates to true if the target
1924was specified as part of
1925.Nm Ns 's
1926command line or was declared the default target (either implicitly or
1927explicitly, see
1928.Va .MAIN )
1929before the line containing the conditional.
1930.It Ic empty
1931Takes a variable, with possible modifiers, and evaluates to true if
1932the expansion of the variable would result in an empty string.
1933.It Ic exists
1934Takes a file name as an argument and evaluates to true if the file exists.
1935The file is searched for on the system search path (see
1936.Va .PATH ) .
1937.It Ic target
1938Takes a target name as an argument and evaluates to true if the target
1939has been defined.
1940.It Ic commands
1941Takes a target name as an argument and evaluates to true if the target
1942has been defined and has commands associated with it.
1943.El
1944.Pp
1945.Ar Expression
1946may also be an arithmetic or string comparison.
1947Variable expansion is
1948performed on both sides of the comparison, after which the numerical
1949values are compared.
1950A value is interpreted as hexadecimal if it is
1951preceded by 0x, otherwise it is decimal; octal numbers are not supported.
1952The standard C relational operators are all supported.
1953If after
1954variable expansion, either the left or right hand side of a
1955.Ql Ic ==
1956or
1957.Ql Ic "!="
1958operator is not a numerical value, then
1959string comparison is performed between the expanded
1960variables.
1961If no relational operator is given, it is assumed that the expanded
1962variable is being compared against 0, or an empty string in the case
1963of a string comparison.
1964.Pp
1965When
1966.Nm
1967is evaluating one of these conditional expressions, and it encounters
1968a (white-space separated) word it doesn't recognize, either the
1969.Dq make
1970or
1971.Dq defined
1972expression is applied to it, depending on the form of the conditional.
1973If the form is
1974.Ql Ic .ifdef ,
1975.Ql Ic .ifndef ,
1976or
1977.Ql Ic .if
1978the
1979.Dq defined
1980expression is applied.
1981Similarly, if the form is
1982.Ql Ic .ifmake
1983or
1984.Ql Ic .ifnmake ,
1985the
1986.Dq make
1987expression is applied.
1988.Pp
1989If the conditional evaluates to true the parsing of the makefile continues
1990as before.
1991If it evaluates to false, the following lines are skipped.
1992In both cases this continues until a
1993.Ql Ic .else
1994or
1995.Ql Ic .endif
1996is found.
1997.Pp
1998For loops are typically used to apply a set of rules to a list of files.
1999The syntax of a for loop is:
2000.Pp
2001.Bl -tag -compact -width Ds
2002.It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression
2003.It Aq make-lines
2004.It Ic \&.endfor
2005.El
2006.Pp
2007After the for
2008.Ic expression
2009is evaluated, it is split into words.
2010On each iteration of the loop, one word is taken and assigned to each
2011.Ic variable ,
2012in order, and these
2013.Ic variables
2014are substituted into the
2015.Ic make-lines
2016inside the body of the for loop.
2017The number of words must come out even; that is, if there are three
2018iteration variables, the number of words provided must be a multiple
2019of three.
2020.Sh COMMENTS
2021Comments begin with a hash
2022.Pq Ql \&#
2023character, anywhere but in a shell
2024command line, and continue to the end of an unescaped new line.
2025.Sh SPECIAL SOURCES (ATTRIBUTES)
2026.Bl -tag -width .IGNOREx
2027.It Ic .EXEC
2028Target is never out of date, but always execute commands anyway.
2029.It Ic .IGNORE
2030Ignore any errors from the commands associated with this target, exactly
2031as if they all were preceded by a dash
2032.Pq Ql \- .
2033.\" .It Ic .INVISIBLE
2034.\" XXX
2035.\" .It Ic .JOIN
2036.\" XXX
2037.It Ic .MADE
2038Mark all sources of this target as being up-to-date.
2039.It Ic .MAKE
2040Execute the commands associated with this target even if the
2041.Fl n
2042or
2043.Fl t
2044options were specified.
2045Normally used to mark recursive
2046.Nm Ns s .
2047.It Ic .META
2048Create a meta file for the target, even if it is flagged as
2049.Ic .PHONY ,
2050.Ic .MAKE ,
2051or
2052.Ic .SPECIAL .
2053Usage in conjunction with
2054.Ic .MAKE
2055is the most likely case.
2056In "meta" mode, the target is out-of-date if the meta file is missing.
2057.It Ic .NOMETA
2058Do not create a meta file for the target.
2059Meta files are also not created for
2060.Ic .PHONY ,
2061.Ic .MAKE ,
2062or
2063.Ic .SPECIAL
2064targets.
2065.It Ic .NOMETA_CMP
2066Ignore differences in commands when deciding if target is out of date.
2067This is useful if the command contains a value which always changes.
2068If the number of commands change, though, the target will still be out of date.
2069The same effect applies to any command line that uses the variable
2070.Va .OODATE ,
2071which can be used for that purpose even when not otherwise needed or desired:
2072.Bd -literal -offset indent
2073
2074skip-compare-for-some:
2075	@echo this will be compared
2076	@echo this will not ${.OODATE:M.NOMETA_CMP}
2077	@echo this will also be compared
2078
2079.Ed
2080The
2081.Cm \&:M
2082pattern suppresses any expansion of the unwanted variable.
2083.It Ic .NOPATH
2084Do not search for the target in the directories specified by
2085.Ic .PATH .
2086.It Ic .NOTMAIN
2087Normally
2088.Nm
2089selects the first target it encounters as the default target to be built
2090if no target was specified.
2091This source prevents this target from being selected.
2092.It Ic .OPTIONAL
2093If a target is marked with this attribute and
2094.Nm
2095can't figure out how to create it, it will ignore this fact and assume
2096the file isn't needed or already exists.
2097.It Ic .PHONY
2098The target does not
2099correspond to an actual file; it is always considered to be out of date,
2100and will not be created with the
2101.Fl t
2102option.
2103Suffix-transformation rules are not applied to
2104.Ic .PHONY
2105targets.
2106.It Ic .PRECIOUS
2107When
2108.Nm
2109is interrupted, it normally removes any partially made targets.
2110This source prevents the target from being removed.
2111.It Ic .RECURSIVE
2112Synonym for
2113.Ic .MAKE .
2114.It Ic .SILENT
2115Do not echo any of the commands associated with this target, exactly
2116as if they all were preceded by an at sign
2117.Pq Ql @ .
2118.It Ic .USE
2119Turn the target into
2120.Nm Ns 's
2121version of a macro.
2122When the target is used as a source for another target, the other target
2123acquires the commands, sources, and attributes (except for
2124.Ic .USE )
2125of the
2126source.
2127If the target already has commands, the
2128.Ic .USE
2129target's commands are appended
2130to them.
2131.It Ic .USEBEFORE
2132Exactly like
2133.Ic .USE ,
2134but prepend the
2135.Ic .USEBEFORE
2136target commands to the target.
2137.It Ic .WAIT
2138If
2139.Ic .WAIT
2140appears in a dependency line, the sources that precede it are
2141made before the sources that succeed it in the line.
2142Since the dependents of files are not made until the file itself
2143could be made, this also stops the dependents being built unless they
2144are needed for another branch of the dependency tree.
2145So given:
2146.Bd -literal
2147x: a .WAIT b
2148	echo x
2149a:
2150	echo a
2151b: b1
2152	echo b
2153b1:
2154	echo b1
2155
2156.Ed
2157the output is always
2158.Ql a ,
2159.Ql b1 ,
2160.Ql b ,
2161.Ql x .
2162.br
2163The ordering imposed by
2164.Ic .WAIT
2165is only relevant for parallel makes.
2166.El
2167.Sh SPECIAL TARGETS
2168Special targets may not be included with other targets, i.e. they must be
2169the only target specified.
2170.Bl -tag -width .BEGINx
2171.It Ic .BEGIN
2172Any command lines attached to this target are executed before anything
2173else is done.
2174.It Ic .DEFAULT
2175This is sort of a
2176.Ic .USE
2177rule for any target (that was used only as a
2178source) that
2179.Nm
2180can't figure out any other way to create.
2181Only the shell script is used.
2182The
2183.Ic .IMPSRC
2184variable of a target that inherits
2185.Ic .DEFAULT Ns 's
2186commands is set
2187to the target's own name.
2188.It Ic .DELETE_ON_ERROR
2189If this target is present in the makefile, it globally causes make to
2190delete targets whose commands fail.
2191(By default, only targets whose commands are interrupted during
2192execution are deleted.
2193This is the historical behavior.)
2194This setting can be used to help prevent half-finished or malformed
2195targets from being left around and corrupting future rebuilds.
2196.It Ic .END
2197Any command lines attached to this target are executed after everything
2198else is done.
2199.It Ic .ERROR
2200Any command lines attached to this target are executed when another target fails.
2201The
2202.Ic .ERROR_TARGET
2203variable is set to the target that failed.
2204See also
2205.Ic MAKE_PRINT_VAR_ON_ERROR .
2206.It Ic .IGNORE
2207Mark each of the sources with the
2208.Ic .IGNORE
2209attribute.
2210If no sources are specified, this is the equivalent of specifying the
2211.Fl i
2212option.
2213.It Ic .INTERRUPT
2214If
2215.Nm
2216is interrupted, the commands for this target will be executed.
2217.It Ic .MAIN
2218If no target is specified when
2219.Nm
2220is invoked, this target will be built.
2221.It Ic .MAKEFLAGS
2222This target provides a way to specify flags for
2223.Nm
2224when the makefile is used.
2225The flags are as if typed to the shell, though the
2226.Fl f
2227option will have
2228no effect.
2229.\" XXX: NOT YET!!!!
2230.\" .It Ic .NOTPARALLEL
2231.\" The named targets are executed in non parallel mode.
2232.\" If no targets are
2233.\" specified, then all targets are executed in non parallel mode.
2234.It Ic .NOPATH
2235Apply the
2236.Ic .NOPATH
2237attribute to any specified sources.
2238.It Ic .NOTPARALLEL
2239Disable parallel mode.
2240.It Ic .NO_PARALLEL
2241Synonym for
2242.Ic .NOTPARALLEL ,
2243for compatibility with other pmake variants.
2244.It Ic .OBJDIR
2245The source is a new value for
2246.Ql Va .OBJDIR .
2247If it exists,
2248.Nm
2249will
2250.Xr chdir 2
2251to it and update the value of
2252.Ql Va .OBJDIR .
2253.It Ic .ORDER
2254The named targets are made in sequence.
2255This ordering does not add targets to the list of targets to be made.
2256Since the dependents of a target do not get built until the target itself
2257could be built, unless
2258.Ql a
2259is built by another part of the dependency graph,
2260the following is a dependency loop:
2261.Bd -literal
2262\&.ORDER: b a
2263b: a
2264.Ed
2265.Pp
2266The ordering imposed by
2267.Ic .ORDER
2268is only relevant for parallel makes.
2269.\" XXX: NOT YET!!!!
2270.\" .It Ic .PARALLEL
2271.\" The named targets are executed in parallel mode.
2272.\" If no targets are
2273.\" specified, then all targets are executed in parallel mode.
2274.It Ic .PATH
2275The sources are directories which are to be searched for files not
2276found in the current directory.
2277If no sources are specified, any previously specified directories are
2278deleted.
2279If the source is the special
2280.Ic .DOTLAST
2281target, then the current working
2282directory is searched last.
2283.It Ic .PATH. Ns Va suffix
2284Like
2285.Ic .PATH
2286but applies only to files with a particular suffix.
2287The suffix must have been previously declared with
2288.Ic .SUFFIXES .
2289.It Ic .PHONY
2290Apply the
2291.Ic .PHONY
2292attribute to any specified sources.
2293.It Ic .POSIX
2294This should be the first non-comment line in a Makefile.
2295It results in the variable
2296.Va %POSIX
2297being defined with the value
2298.Ql 1003.2 .
2299The first time
2300.Ic .POSIX
2301is encountered, the makefile
2302.Ql posix.mk
2303will be included if possible,
2304to provide POSIX compatible default rules.
2305If
2306.Nm
2307is run with the
2308.Fl r
2309flag, then only
2310.Ql posix.mk
2311will contribute to the default rules.
2312.It Ic .PRECIOUS
2313Apply the
2314.Ic .PRECIOUS
2315attribute to any specified sources.
2316If no sources are specified, the
2317.Ic .PRECIOUS
2318attribute is applied to every
2319target in the file.
2320.It Ic .SHELL
2321Sets the shell that
2322.Nm
2323will use to execute commands.
2324The sources are a set of
2325.Ar field=value
2326pairs.
2327.Bl -tag -width hasErrCtls
2328.It Ar name
2329This is the minimal specification, used to select one of the built-in
2330shell specs;
2331.Ar sh ,
2332.Ar ksh ,
2333and
2334.Ar csh .
2335.It Ar path
2336Specifies the path to the shell.
2337.It Ar hasErrCtl
2338Indicates whether the shell supports exit on error.
2339.It Ar check
2340The command to turn on error checking.
2341.It Ar ignore
2342The command to disable error checking.
2343.It Ar echo
2344The command to turn on echoing of commands executed.
2345.It Ar quiet
2346The command to turn off echoing of commands executed.
2347.It Ar filter
2348The output to filter after issuing the
2349.Ar quiet
2350command.
2351It is typically identical to
2352.Ar quiet .
2353.It Ar errFlag
2354The flag to pass the shell to enable error checking.
2355.It Ar echoFlag
2356The flag to pass the shell to enable command echoing.
2357.It Ar newline
2358The string literal to pass the shell that results in a single newline
2359character when used outside of any quoting characters.
2360.El
2361Example:
2362.Bd -literal
2363\&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e
2364	check="set \-e" ignore="set +e" \e
2365	echo="set \-v" quiet="set +v" filter="set +v" \e
2366	echoFlag=v errFlag=e newline="'\en'"
2367.Ed
2368.It Ic .SILENT
2369Apply the
2370.Ic .SILENT
2371attribute to any specified sources.
2372If no sources are specified, the
2373.Ic .SILENT
2374attribute is applied to every
2375command in the file.
2376.It Ic .STALE
2377This target gets run when a dependency file contains stale entries, having
2378.Va .ALLSRC
2379set to the name of that dependency file.
2380.It Ic .SUFFIXES
2381Each source specifies a suffix to
2382.Nm .
2383If no sources are specified, any previously specified suffixes are deleted.
2384It allows the creation of suffix-transformation rules.
2385.Pp
2386Example:
2387.Bd -literal
2388\&.SUFFIXES: .o
2389\&.c.o:
2390	cc \-o ${.TARGET} \-c ${.IMPSRC}
2391.Ed
2392.El
2393.Sh ENVIRONMENT
2394.Nm
2395uses the following environment variables, if they exist:
2396.Ev MACHINE ,
2397.Ev MACHINE_ARCH ,
2398.Ev MAKE ,
2399.Ev MAKEFLAGS ,
2400.Ev MAKEOBJDIR ,
2401.Ev MAKEOBJDIRPREFIX ,
2402.Ev MAKESYSPATH ,
2403.Ev PWD ,
2404and
2405.Ev TMPDIR .
2406.Pp
2407.Ev MAKEOBJDIRPREFIX
2408and
2409.Ev MAKEOBJDIR
2410may only be set in the environment or on the command line to
2411.Nm
2412and not as makefile variables;
2413see the description of
2414.Ql Va .OBJDIR
2415for more details.
2416.Sh FILES
2417.Bl -tag -width /usr/share/mk -compact
2418.It .depend
2419list of dependencies
2420.It Makefile
2421list of dependencies
2422.It makefile
2423list of dependencies
2424.It sys.mk
2425system makefile
2426.It /usr/share/mk
2427system makefile directory
2428.El
2429.Sh COMPATIBILITY
2430The basic make syntax is compatible between different versions of make;
2431however the special variables, variable modifiers and conditionals are not.
2432.Ss Older versions
2433An incomplete list of changes in older versions of
2434.Nm :
2435.Pp
2436The way that .for loop variables are substituted changed after
2437NetBSD 5.0
2438so that they still appear to be variable expansions.
2439In particular this stops them being treated as syntax, and removes some
2440obscure problems using them in .if statements.
2441.Pp
2442The way that parallel makes are scheduled changed in
2443NetBSD 4.0
2444so that .ORDER and .WAIT apply recursively to the dependent nodes.
2445The algorithms used may change again in the future.
2446.Ss Other make dialects
2447Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not
2448support most of the features of
2449.Nm
2450as described in this manual.
2451Most notably:
2452.Bl -bullet -offset indent
2453.It
2454The
2455.Ic .WAIT
2456and
2457.Ic .ORDER
2458declarations and most functionality pertaining to parallelization.
2459(GNU make supports parallelization but lacks these features needed to
2460control it effectively.)
2461.It
2462Directives, including for loops and conditionals and most of the
2463forms of include files.
2464(GNU make has its own incompatible and less powerful syntax for
2465conditionals.)
2466.It
2467All built-in variables that begin with a dot.
2468.It
2469Most of the special sources and targets that begin with a dot,
2470with the notable exception of
2471.Ic .PHONY ,
2472.Ic .PRECIOUS ,
2473and
2474.Ic .SUFFIXES .
2475.It
2476Variable modifiers, except for the
2477.Dl :old=new
2478string substitution, which does not portably support globbing with
2479.Ql %
2480and historically only works on declared suffixes.
2481.It
2482The
2483.Ic $>
2484variable even in its short form; most makes support this functionality
2485but its name varies.
2486.El
2487.Pp
2488Some features are somewhat more portable, such as assignment with
2489.Ic += ,
2490.Ic ?= ,
2491and
2492.Ic != .
2493The
2494.Ic .PATH
2495functionality is based on an older feature
2496.Ic VPATH
2497found in GNU make and many versions of SVR4 make; however,
2498historically its behavior is too ill-defined (and too buggy) to rely
2499upon.
2500.Pp
2501The
2502.Ic $@
2503and
2504.Ic $<
2505variables are more or less universally portable, as is the
2506.Ic $(MAKE)
2507variable.
2508Basic use of suffix rules (for files only in the current directory,
2509not trying to chain transformations together, etc.) is also reasonably
2510portable.
2511.Sh SEE ALSO
2512.Xr mkdep 1
2513.Sh HISTORY
2514.Nm
2515is derived from NetBSD
2516.Xr make 1 .
2517It uses autoconf to facilitate portability to other platforms.
2518.Pp
2519A
2520make
2521command appeared in
2522.At v7 .
2523This
2524make
2525implementation is based on Adam De Boor's pmake program which was written
2526for Sprite at Berkeley.
2527It was designed to be a parallel distributed make running jobs on different
2528machines using a daemon called
2529.Dq customs .
2530.Pp
2531Historically the target/dependency
2532.Dq FRC
2533has been used to FoRCe rebuilding (since the target/dependency
2534does not exist... unless someone creates an
2535.Dq FRC
2536file).
2537.Sh BUGS
2538The
2539make
2540syntax is difficult to parse without actually acting on the data.
2541For instance, finding the end of a variable's use should involve scanning
2542each of the modifiers, using the correct terminator for each field.
2543In many places
2544make
2545just counts {} and () in order to find the end of a variable expansion.
2546.Pp
2547There is no way of escaping a space character in a filename.
2548