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