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