1.\" $NetBSD: make.1,v 1.210 2013/01/27 18:52:01 sjg Exp $
| 1.\" $NetBSD: make.1,v 1.213 2013/03/31 05:49:51 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.\"
| 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
| 32.Dd March 30, 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.
| 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.PATH_FILEMON
878If
879.Nm
880was built with
881.Xr filemon 4
882support, this is set to the path of the device node.
883This allows makefiles to test for this support.
|
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.
| 884.It Va .MAKE.PID
885The process-id of
886.Nm .
887.It Va .MAKE.PPID
888The parent process-id of
889.Nm .
890.It Va MAKE_PRINT_VAR_ON_ERROR
891When
892.Nm
893stops due to an error, it prints its name and the value of
894.Ql Va .CURDIR
895as well as the value of any variables named in
896.Ql Va MAKE_PRINT_VAR_ON_ERROR .
897.It Va .newline
898This variable is simply assigned a newline character as its value.
899This allows expansions using the
900.Cm \&:@
901modifier to put a newline between
902iterations of the loop rather than a space.
903For example, the printing of
904.Ql Va MAKE_PRINT_VAR_ON_ERROR
905could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}.
906.It Va .OBJDIR
907A path to the directory where the targets are built.
908Its value is determined by trying to
909.Xr chdir 2
910to the following directories in order and using the first match:
911.Bl -enum
912.It
913.Ev ${MAKEOBJDIRPREFIX}${.CURDIR}
914.Pp
915(Only if
916.Ql Ev MAKEOBJDIRPREFIX
917is set in the environment or on the command line.)
918.It
919.Ev ${MAKEOBJDIR}
920.Pp
921(Only if
922.Ql Ev MAKEOBJDIR
923is set in the environment or on the command line.)
924.It
925.Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE}
926.It
927.Ev ${.CURDIR} Ns Pa /obj
928.It
929.Pa /usr/obj/ Ns Ev ${.CURDIR}
930.It
931.Ev ${.CURDIR}
932.El
933.Pp
934Variable expansion is performed on the value before it's used,
935so expressions such as
936.Dl ${.CURDIR:S,^/usr/src,/var/obj,}
937may be used.
938This is especially useful with
939.Ql Ev MAKEOBJDIR .
940.Pp
941.Ql Va .OBJDIR
942may be modified in the makefile as a global variable.
943In all cases,
944.Nm
945will
946.Xr chdir 2
947to
948.Ql Va .OBJDIR
949and set
950.Ql Ev PWD
951to that directory before executing any targets.
952.
953.It Va .PARSEDIR
954A path to the directory of the current
955.Ql Pa Makefile
956being parsed.
957.It Va .PARSEFILE
958The basename of the current
959.Ql Pa Makefile
960being parsed.
961This variable and
962.Ql Va .PARSEDIR
963are both set only while the
964.Ql Pa Makefiles
965are being parsed.
966If you want to retain their current values, assign them to a variable
967using assignment with expansion:
968.Pq Ql Cm \&:= .
969.It Va .PATH
970A variable that represents the list of directories that
971.Nm
972will search for files.
973The search list should be updated using the target
974.Ql Va .PATH
975rather than the variable.
976.It Ev PWD
977Alternate path to the current directory.
978.Nm
979normally sets
980.Ql Va .CURDIR
981to the canonical path given by
982.Xr getcwd 3 .
983However, if the environment variable
984.Ql Ev PWD
985is set and gives a path to the current directory, then
986.Nm
987sets
988.Ql Va .CURDIR
989to the value of
990.Ql Ev PWD
991instead.
992This behaviour is disabled if
993.Ql Ev MAKEOBJDIRPREFIX
994is set or
995.Ql Ev MAKEOBJDIR
996contains a variable transform.
997.Ql Ev PWD
998is set to the value of
999.Ql Va .OBJDIR
1000for all programs which
1001.Nm
1002executes.
1003.It Ev .TARGETS
1004The list of targets explicitly specified on the command line, if any.
1005.It Ev VPATH
1006Colon-separated
1007.Pq Dq \&:
1008lists of directories that
1009.Nm
1010will search for files.
1011The variable is supported for compatibility with old make programs only,
1012use
1013.Ql Va .PATH
1014instead.
1015.El
1016.Ss Variable modifiers
1017Variable expansion may be modified to select or modify each word of the
1018variable (where a
1019.Dq word
1020is white-space delimited sequence of characters).
1021The general format of a variable expansion is as follows:
1022.Pp
1023.Dl ${variable[:modifier[:...]]}
1024.Pp
1025Each modifier begins with a colon,
1026which may be escaped with a backslash
1027.Pq Ql \e .
1028.Pp
1029A set of modifiers can be specified via a variable, as follows:
1030.Pp
1031.Dl modifier_variable=modifier[:...]
1032.Dl ${variable:${modifier_variable}[:...]}
1033.Pp
1034In this case the first modifier in the modifier_variable does not
1035start with a colon, since that must appear in the referencing
1036variable.
1037If any of the modifiers in the modifier_variable contain a dollar sign
1038.Pq Ql $ ,
1039these must be doubled to avoid early expansion.
1040.Pp
1041The supported modifiers are:
1042.Bl -tag -width EEE
1043.It Cm \&:E
1044Replaces each word in the variable with its suffix.
1045.It Cm \&:H
1046Replaces each word in the variable with everything but the last component.
1047.It Cm \&:M Ns Ar pattern
1048Select only those words that match
1049.Ar pattern .
1050The standard shell wildcard characters
1051.Pf ( Ql * ,
1052.Ql \&? ,
1053and
1054.Ql Oo Oc )
1055may
1056be used.
1057The wildcard characters may be escaped with a backslash
1058.Pq Ql \e .
1059.It Cm \&:N Ns Ar pattern
1060This is identical to
1061.Ql Cm \&:M ,
1062but selects all words which do not match
1063.Ar pattern .
1064.It Cm \&:O
1065Order every word in variable alphabetically.
1066To sort words in
1067reverse order use the
1068.Ql Cm \&:O:[-1..1]
1069combination of modifiers.
1070.It Cm \&:Ox
1071Randomize words in variable.
1072The results will be different each time you are referring to the
1073modified variable; use the assignment with expansion
1074.Pq Ql Cm \&:=
1075to prevent such behaviour.
1076For example,
1077.Bd -literal -offset indent
1078LIST= uno due tre quattro
1079RANDOM_LIST= ${LIST:Ox}
1080STATIC_RANDOM_LIST:= ${LIST:Ox}
1081
1082all:
1083 @echo "${RANDOM_LIST}"
1084 @echo "${RANDOM_LIST}"
1085 @echo "${STATIC_RANDOM_LIST}"
1086 @echo "${STATIC_RANDOM_LIST}"
1087.Ed
1088may produce output similar to:
1089.Bd -literal -offset indent
1090quattro due tre uno
1091tre due quattro uno
1092due uno quattro tre
1093due uno quattro tre
1094.Ed
1095.It Cm \&:Q
1096Quotes every shell meta-character in the variable, so that it can be passed
1097safely through recursive invocations of
1098.Nm .
1099.It Cm \&:R
1100Replaces each word in the variable with everything but its suffix.
1101.It Cm \&:gmtime
1102The value is a format string for
1103.Xr strftime 3 ,
1104using the current
1105.Xr gmtime 3 .
1106.It Cm \&:hash
1107Compute a 32bit hash of the value and encode it as hex digits.
1108.It Cm \&:localtime
1109The value is a format string for
1110.Xr strftime 3 ,
1111using the current
1112.Xr localtime 3 .
1113.It Cm \&:tA
1114Attempt to convert variable to an absolute path using
1115.Xr realpath 3 ,
1116if that fails, the value is unchanged.
1117.It Cm \&:tl
1118Converts variable to lower-case letters.
1119.It Cm \&:ts Ns Ar c
1120Words in the variable are normally separated by a space on expansion.
1121This modifier sets the separator to the character
1122.Ar c .
1123If
1124.Ar c
1125is omitted, then no separator is used.
1126The common escapes (including octal numeric codes), work as expected.
1127.It Cm \&:tu
1128Converts variable to upper-case letters.
1129.It Cm \&:tW
1130Causes the value to be treated as a single word
1131(possibly containing embedded white space).
1132See also
1133.Ql Cm \&:[*] .
1134.It Cm \&:tw
1135Causes the value to be treated as a sequence of
1136words delimited by white space.
1137See also
1138.Ql Cm \&:[@] .
1139.Sm off
1140.It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW
1141.Sm on
1142Modify the first occurrence of
1143.Ar old_string
1144in the variable's value, replacing it with
1145.Ar new_string .
1146If a
1147.Ql g
1148is appended to the last slash of the pattern, all occurrences
1149in each word are replaced.
1150If a
1151.Ql 1
1152is appended to the last slash of the pattern, only the first word
1153is affected.
1154If a
1155.Ql W
1156is appended to the last slash of the pattern,
1157then the value is treated as a single word
1158(possibly containing embedded white space).
1159If
1160.Ar old_string
1161begins with a caret
1162.Pq Ql ^ ,
1163.Ar old_string
1164is anchored at the beginning of each word.
1165If
1166.Ar old_string
1167ends with a dollar sign
1168.Pq Ql \&$ ,
1169it is anchored at the end of each word.
1170Inside
1171.Ar new_string ,
1172an ampersand
1173.Pq Ql \*[Am]
1174is replaced by
1175.Ar old_string
1176(without any
1177.Ql ^
1178or
1179.Ql \&$ ) .
1180Any character may be used as a delimiter for the parts of the modifier
1181string.
1182The anchoring, ampersand and delimiter characters may be escaped with a
1183backslash
1184.Pq Ql \e .
1185.Pp
1186Variable expansion occurs in the normal fashion inside both
1187.Ar old_string
1188and
1189.Ar new_string
1190with the single exception that a backslash is used to prevent the expansion
1191of a dollar sign
1192.Pq Ql \&$ ,
1193not a preceding dollar sign as is usual.
1194.Sm off
1195.It Cm \&:C No \&/ Ar pattern No \&/ Ar replacement No \&/ Op Cm 1gW
1196.Sm on
1197The
1198.Cm \&:C
1199modifier is just like the
1200.Cm \&:S
1201modifier except that the old and new strings, instead of being
1202simple strings, are a regular expression (see
1203.Xr regex 3 )
1204string
1205.Ar pattern
1206and an
1207.Xr ed 1 Ns \-style
1208string
1209.Ar replacement .
1210Normally, the first occurrence of the pattern
1211.Ar pattern
1212in each word of the value is substituted with
1213.Ar replacement .
1214The
1215.Ql 1
1216modifier causes the substitution to apply to at most one word; the
1217.Ql g
1218modifier causes the substitution to apply to as many instances of the
1219search pattern
1220.Ar pattern
1221as occur in the word or words it is found in; the
1222.Ql W
1223modifier causes the value to be treated as a single word
1224(possibly containing embedded white space).
1225Note that
1226.Ql 1
1227and
1228.Ql g
1229are orthogonal; the former specifies whether multiple words are
1230potentially affected, the latter whether multiple substitutions can
1231potentially occur within each affected word.
1232.It Cm \&:T
1233Replaces each word in the variable with its last component.
1234.It Cm \&:u
1235Remove adjacent duplicate words (like
1236.Xr uniq 1 ) .
1237.Sm off
1238.It Cm \&:\&? Ar true_string Cm \&: Ar false_string
1239.Sm on
1240If the variable name (not its value), when parsed as a .if conditional
1241expression, evaluates to true, return as its value the
1242.Ar true_string ,
1243otherwise return the
1244.Ar false_string .
1245Since the variable name is used as the expression, \&:\&? must be the
1246first modifier after the variable name itself - which will, of course,
1247usually contain variable expansions.
1248A common error is trying to use expressions like
1249.Dl ${NUMBERS:M42:?match:no}
1250which actually tests defined(NUMBERS),
1251to determine is any words match "42" you need to use something like:
1252.Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} .
1253.It Ar :old_string=new_string
1254This is the
1255.At V
1256style variable substitution.
1257It must be the last modifier specified.
1258If
1259.Ar old_string
1260or
1261.Ar new_string
1262do not contain the pattern matching character
1263.Ar %
1264then it is assumed that they are
1265anchored at the end of each word, so only suffixes or entire
1266words may be replaced.
1267Otherwise
1268.Ar %
1269is the substring of
1270.Ar old_string
1271to be replaced in
1272.Ar new_string .
1273.Pp
1274Variable expansion occurs in the normal fashion inside both
1275.Ar old_string
1276and
1277.Ar new_string
1278with the single exception that a backslash is used to prevent the
1279expansion of a dollar sign
1280.Pq Ql \&$ ,
1281not a preceding dollar sign as is usual.
1282.Sm off
1283.It Cm \&:@ Ar temp Cm @ Ar string Cm @
1284.Sm on
1285This is the loop expansion mechanism from the OSF Development
1286Environment (ODE) make.
1287Unlike
1288.Cm \&.for
1289loops expansion occurs at the time of
1290reference.
1291Assign
1292.Ar temp
1293to each word in the variable and evaluate
1294.Ar string .
1295The ODE convention is that
1296.Ar temp
1297should start and end with a period.
1298For example.
1299.Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
1300.Pp
1301However a single character varaiable is often more readable:
1302.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
1303.It Cm \&:U Ns Ar newval
1304If the variable is undefined
1305.Ar newval
1306is the value.
1307If the variable is defined, the existing value is returned.
1308This is another ODE make feature.
1309It is handy for setting per-target CFLAGS for instance:
1310.Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
1311If a value is only required if the variable is undefined, use:
1312.Dl ${VAR:D:Unewval}
1313.It Cm \&:D Ns Ar newval
1314If the variable is defined
1315.Ar newval
1316is the value.
1317.It Cm \&:L
1318The name of the variable is the value.
1319.It Cm \&:P
1320The path of the node which has the same name as the variable
1321is the value.
1322If no such node exists or its path is null, then the
1323name of the variable is used.
1324In order for this modifier to work, the name (node) must at least have
1325appeared on the rhs of a dependency.
1326.Sm off
1327.It Cm \&:\&! Ar cmd Cm \&!
1328.Sm on
1329The output of running
1330.Ar cmd
1331is the value.
1332.It Cm \&:sh
1333If the variable is non-empty it is run as a command and the output
1334becomes the new value.
1335.It Cm \&::= Ns Ar str
1336The variable is assigned the value
1337.Ar str
1338after substitution.
1339This modifier and its variations are useful in
1340obscure situations such as wanting to set a variable when shell commands
1341are being parsed.
1342These assignment modifiers always expand to
1343nothing, so if appearing in a rule line by themselves should be
1344preceded with something to keep
1345.Nm
1346happy.
1347.Pp
1348The
1349.Ql Cm \&::
1350helps avoid false matches with the
1351.At V
1352style
1353.Cm \&:=
1354modifier and since substitution always occurs the
1355.Cm \&::=
1356form is vaguely appropriate.
1357.It Cm \&::?= Ns Ar str
1358As for
1359.Cm \&::=
1360but only if the variable does not already have a value.
1361.It Cm \&::+= Ns Ar str
1362Append
1363.Ar str
1364to the variable.
1365.It Cm \&::!= Ns Ar cmd
1366Assign the output of
1367.Ar cmd
1368to the variable.
1369.It Cm \&:\&[ Ns Ar range Ns Cm \&]
1370Selects one or more words from the value,
1371or performs other operations related to the way in which the
1372value is divided into words.
1373.Pp
1374Ordinarily, a value is treated as a sequence of words
1375delimited by white space.
1376Some modifiers suppress this behaviour,
1377causing a value to be treated as a single word
1378(possibly containing embedded white space).
1379An empty value, or a value that consists entirely of white-space,
1380is treated as a single word.
1381For the purposes of the
1382.Ql Cm \&:[]
1383modifier, the words are indexed both forwards using positive integers
1384(where index 1 represents the first word),
1385and backwards using negative integers
1386(where index \-1 represents the last word).
1387.Pp
1388The
1389.Ar range
1390is subjected to variable expansion, and the expanded result is
1391then interpreted as follows:
1392.Bl -tag -width index
1393.\" :[n]
1394.It Ar index
1395Selects a single word from the value.
1396.\" :[start..end]
1397.It Ar start Ns Cm \&.. Ns Ar end
1398Selects all words from
1399.Ar start
1400to
1401.Ar end ,
1402inclusive.
1403For example,
1404.Ql Cm \&:[2..-1]
1405selects all words from the second word to the last word.
1406If
1407.Ar start
1408is greater than
1409.Ar end ,
1410then the words are output in reverse order.
1411For example,
1412.Ql Cm \&:[-1..1]
1413selects all the words from last to first.
1414.\" :[*]
1415.It Cm \&*
1416Causes subsequent modifiers to treat the value as a single word
1417(possibly containing embedded white space).
1418Analogous to the effect of
1419\&"$*\&"
1420in Bourne shell.
1421.\" :[0]
1422.It 0
1423Means the same as
1424.Ql Cm \&:[*] .
1425.\" :[*]
1426.It Cm \&@
1427Causes subsequent modifiers to treat the value as a sequence of words
1428delimited by white space.
1429Analogous to the effect of
1430\&"$@\&"
1431in Bourne shell.
1432.\" :[#]
1433.It Cm \&#
1434Returns the number of words in the value.
1435.El \" :[range]
1436.El
1437.Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1438Makefile inclusion, conditional structures and for loops reminiscent
1439of the C programming language are provided in
1440.Nm .
1441All such structures are identified by a line beginning with a single
1442dot
1443.Pq Ql \&.
1444character.
1445Files are included with either
1446.Cm \&.include Aq Ar file
1447or
1448.Cm \&.include Pf \*q Ar file Ns \*q .
1449Variables between the angle brackets or double quotes are expanded
1450to form the file name.
1451If angle brackets are used, the included makefile is expected to be in
1452the system makefile directory.
1453If double quotes are used, the including makefile's directory and any
1454directories specified using the
1455.Fl I
1456option are searched before the system
1457makefile directory.
1458For compatibility with other versions of
1459.Nm
1460.Ql include file ...
1461is also accepted.
1462If the include statement is written as
1463.Cm .-include
1464or as
1465.Cm .sinclude
1466then errors locating and/or opening include files are ignored.
1467.Pp
1468Conditional expressions are also preceded by a single dot as the first
1469character of a line.
1470The possible conditionals are as follows:
1471.Bl -tag -width Ds
1472.It Ic .error Ar message
1473The message is printed along with the name of the makefile and line number,
1474then
1475.Nm
1476will exit.
1477.It Ic .export Ar variable ...
1478Export the specified global variable.
1479If no variable list is provided, all globals are exported
1480except for internal variables (those that start with
1481.Ql \&. ) .
1482This is not affected by the
1483.Fl X
1484flag, so should be used with caution.
1485For compatibility with other
1486.Nm
1487programs
1488.Ql export variable=value
1489is also accepted.
1490.Pp
1491Appending a variable name to
1492.Va .MAKE.EXPORTED
1493is equivalent to exporting a variable.
1494.It Ic .export-env Ar variable ...
1495The same as
1496.Ql .export ,
1497except that the variable is not appended to
1498.Va .MAKE.EXPORTED .
1499This allows exporting a value to the environment which is different from that
1500used by
1501.Nm
1502internally.
1503.It Ic .info Ar message
1504The message is printed along with the name of the makefile and line number.
1505.It Ic .undef Ar variable
1506Un-define the specified global variable.
1507Only global variables may be un-defined.
1508.It Ic .unexport Ar variable ...
1509The opposite of
1510.Ql .export .
1511The specified global
1512.Va variable
1513will be removed from
1514.Va .MAKE.EXPORTED .
1515If no variable list is provided, all globals are unexported,
1516and
1517.Va .MAKE.EXPORTED
1518deleted.
1519.It Ic .unexport-env
1520Unexport all globals previously exported and
1521clear the environment inherited from the parent.
1522This operation will cause a memory leak of the original environment,
1523so should be used sparingly.
1524Testing for
1525.Va .MAKE.LEVEL
1526being 0, would make sense.
1527Also note that any variables which originated in the parent environment
1528should be explicitly preserved if desired.
1529For example:
1530.Bd -literal -offset indent
1531.Li .if ${.MAKE.LEVEL} == 0
1532PATH := ${PATH}
1533.Li .unexport-env
1534.Li .export PATH
1535.Li .endif
1536.Pp
1537.Ed
1538Would result in an environment containing only
1539.Ql Ev PATH ,
1540which is the minimal useful environment.
1541Actually
1542.Ql Ev .MAKE.LEVEL
1543will also be pushed into the new environment.
1544.It Ic .warning Ar message
1545The message prefixed by
1546.Ql Pa warning:
1547is printed along with the name of the makefile and line number.
1548.It Ic \&.if Oo \&! Oc Ns Ar expression Op Ar operator expression ...
1549Test the value of an expression.
1550.It Ic .ifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1551Test the value of a variable.
1552.It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1553Test the value of a variable.
1554.It Ic .ifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1555Test the target being built.
1556.It Ic .ifnmake Oo \&! Ns Oc Ar target Op Ar operator target ...
1557Test the target being built.
1558.It Ic .else
1559Reverse the sense of the last conditional.
1560.It Ic .elif Oo \&! Ns Oc Ar expression Op Ar operator expression ...
1561A combination of
1562.Ql Ic .else
1563followed by
1564.Ql Ic .if .
1565.It Ic .elifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1566A combination of
1567.Ql Ic .else
1568followed by
1569.Ql Ic .ifdef .
1570.It Ic .elifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1571A combination of
1572.Ql Ic .else
1573followed by
1574.Ql Ic .ifndef .
1575.It Ic .elifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1576A combination of
1577.Ql Ic .else
1578followed by
1579.Ql Ic .ifmake .
1580.It Ic .elifnmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1581A combination of
1582.Ql Ic .else
1583followed by
1584.Ql Ic .ifnmake .
1585.It Ic .endif
1586End the body of the conditional.
1587.El
1588.Pp
1589The
1590.Ar operator
1591may be any one of the following:
1592.Bl -tag -width "Cm XX"
1593.It Cm \&|\&|
1594Logical OR.
1595.It Cm \&\*[Am]\*[Am]
1596Logical
1597.Tn AND ;
1598of higher precedence than
1599.Dq \&|\&| .
1600.El
1601.Pp
1602As in C,
1603.Nm
1604will only evaluate a conditional as far as is necessary to determine
1605its value.
1606Parentheses may be used to change the order of evaluation.
1607The boolean operator
1608.Ql Ic \&!
1609may be used to logically negate an entire
1610conditional.
1611It is of higher precedence than
1612.Ql Ic \&\*[Am]\*[Am] .
1613.Pp
1614The value of
1615.Ar expression
1616may be any of the following:
1617.Bl -tag -width defined
1618.It Ic defined
1619Takes a variable name as an argument and evaluates to true if the variable
1620has been defined.
1621.It Ic make
1622Takes a target name as an argument and evaluates to true if the target
1623was specified as part of
1624.Nm Ns 's
1625command line or was declared the default target (either implicitly or
1626explicitly, see
1627.Va .MAIN )
1628before the line containing the conditional.
1629.It Ic empty
1630Takes a variable, with possible modifiers, and evaluates to true if
1631the expansion of the variable would result in an empty string.
1632.It Ic exists
1633Takes a file name as an argument and evaluates to true if the file exists.
1634The file is searched for on the system search path (see
1635.Va .PATH ) .
1636.It Ic target
1637Takes a target name as an argument and evaluates to true if the target
1638has been defined.
1639.It Ic commands
1640Takes a target name as an argument and evaluates to true if the target
1641has been defined and has commands associated with it.
1642.El
1643.Pp
1644.Ar Expression
1645may also be an arithmetic or string comparison.
1646Variable expansion is
1647performed on both sides of the comparison, after which the integral
1648values are compared.
1649A value is interpreted as hexadecimal if it is
1650preceded by 0x, otherwise it is decimal; octal numbers are not supported.
1651The standard C relational operators are all supported.
1652If after
1653variable expansion, either the left or right hand side of a
1654.Ql Ic ==
1655or
1656.Ql Ic "!="
1657operator is not an integral value, then
1658string comparison is performed between the expanded
1659variables.
1660If no relational operator is given, it is assumed that the expanded
1661variable is being compared against 0 or an empty string in the case
1662of a string comparison.
1663.Pp
1664When
1665.Nm
1666is evaluating one of these conditional expressions, and it encounters
1667a (white-space separated) word it doesn't recognize, either the
1668.Dq make
1669or
1670.Dq defined
1671expression is applied to it, depending on the form of the conditional.
1672If the form is
1673.Ql Ic .ifdef ,
1674.Ql Ic .ifndef ,
1675or
1676.Ql Ic .if
1677the
1678.Dq defined
1679expression is applied.
1680Similarly, if the form is
1681.Ql Ic .ifmake
1682or
1683.Ql Ic .ifnmake , the
1684.Dq make
1685expression is applied.
1686.Pp
1687If the conditional evaluates to true the parsing of the makefile continues
1688as before.
1689If it evaluates to false, the following lines are skipped.
1690In both cases this continues until a
1691.Ql Ic .else
1692or
1693.Ql Ic .endif
1694is found.
1695.Pp
1696For loops are typically used to apply a set of rules to a list of files.
1697The syntax of a for loop is:
1698.Pp
1699.Bl -tag -compact -width Ds
1700.It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression
1701.It Aq make-rules
1702.It Ic \&.endfor
1703.El
1704.Pp
1705After the for
1706.Ic expression
1707is evaluated, it is split into words.
1708On each iteration of the loop, one word is taken and assigned to each
1709.Ic variable ,
1710in order, and these
1711.Ic variables
1712are substituted into the
1713.Ic make-rules
1714inside the body of the for loop.
1715The number of words must come out even; that is, if there are three
1716iteration variables, the number of words provided must be a multiple
1717of three.
1718.Sh COMMENTS
1719Comments begin with a hash
1720.Pq Ql \&#
1721character, anywhere but in a shell
1722command line, and continue to the end of an unescaped new line.
1723.Sh SPECIAL SOURCES (ATTRIBUTES)
1724.Bl -tag -width .IGNOREx
1725.It Ic .EXEC
1726Target is never out of date, but always execute commands anyway.
1727.It Ic .IGNORE
1728Ignore any errors from the commands associated with this target, exactly
1729as if they all were preceded by a dash
1730.Pq Ql \- .
1731.\" .It Ic .INVISIBLE
1732.\" XXX
1733.\" .It Ic .JOIN
1734.\" XXX
1735.It Ic .MADE
1736Mark all sources of this target as being up-to-date.
1737.It Ic .MAKE
1738Execute the commands associated with this target even if the
1739.Fl n
1740or
1741.Fl t
1742options were specified.
1743Normally used to mark recursive
1744.Nm Ns 's .
1745.It Ic .META
1746Create a meta file for the target, even if it is flagged as
1747.Ic .PHONY ,
1748.Ic .MAKE ,
1749or
1750.Ic .SPECIAL .
1751Usage in conjunction with
1752.Ic .MAKE
1753is the most likely case.
1754In "meta" mode, the target is out-of-date if the meta file is missing.
1755.It Ic .NOMETA
1756Do not create a meta file for the target.
1757Meta files are also not created for
1758.Ic .PHONY ,
1759.Ic .MAKE ,
1760or
1761.Ic .SPECIAL
1762targets.
1763.It Ic .NOMETA_CMP
1764Ignore differences in commands when deciding if target is out of date.
1765This is useful if the command contains a value which always changes.
1766If the number of commands change, though, the target will still be out of date.
|
| 1767The same effect applies to any command line that uses the variable
1768.Va .OODATE ,
1769which can be used for that purpose even when not otherwise needed or desired:
1770.Bd -literal -offset indent
1771
1772skip-compare-for-some:
1773 @echo this will be compared
1774 @echo this will not ${.OODATE:M.NOMETA_CMP}
1775 @echo this will also be compared
1776
1777.Ed
1778The
1779.Cm \&:M
1780pattern suppresses any expansion of the unwanted variable.
|
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.
| 1781.It Ic .NOPATH
1782Do not search for the target in the directories specified by
1783.Ic .PATH .
1784.It Ic .NOTMAIN
1785Normally
1786.Nm
1787selects the first target it encounters as the default target to be built
1788if no target was specified.
1789This source prevents this target from being selected.
1790.It Ic .OPTIONAL
1791If a target is marked with this attribute and
1792.Nm
1793can't figure out how to create it, it will ignore this fact and assume
1794the file isn't needed or already exists.
1795.It Ic .PHONY
1796The target does not
1797correspond to an actual file; it is always considered to be out of date,
1798and will not be created with the
1799.Fl t
1800option.
1801Suffix-transformation rules are not applied to
1802.Ic .PHONY
1803targets.
1804.It Ic .PRECIOUS
1805When
1806.Nm
1807is interrupted, it normally removes any partially made targets.
1808This source prevents the target from being removed.
1809.It Ic .RECURSIVE
1810Synonym for
1811.Ic .MAKE .
1812.It Ic .SILENT
1813Do not echo any of the commands associated with this target, exactly
1814as if they all were preceded by an at sign
1815.Pq Ql @ .
1816.It Ic .USE
1817Turn the target into
1818.Nm Ns 's
1819version of a macro.
1820When the target is used as a source for another target, the other target
1821acquires the commands, sources, and attributes (except for
1822.Ic .USE )
1823of the
1824source.
1825If the target already has commands, the
1826.Ic .USE
1827target's commands are appended
1828to them.
1829.It Ic .USEBEFORE
1830Exactly like
1831.Ic .USE ,
1832but prepend the
1833.Ic .USEBEFORE
1834target commands to the target.
1835.It Ic .WAIT
1836If
1837.Ic .WAIT
1838appears in a dependency line, the sources that precede it are
1839made before the sources that succeed it in the line.
1840Since the dependents of files are not made until the file itself
1841could be made, this also stops the dependents being built unless they
1842are needed for another branch of the dependency tree.
1843So given:
1844.Bd -literal
1845x: a .WAIT b
1846 echo x
1847a:
1848 echo a
1849b: b1
1850 echo b
1851b1:
1852 echo b1
1853
1854.Ed
1855the output is always
1856.Ql a ,
1857.Ql b1 ,
1858.Ql b ,
1859.Ql x .
1860.br
1861The ordering imposed by
1862.Ic .WAIT
1863is only relevant for parallel makes.
1864.El
1865.Sh SPECIAL TARGETS
1866Special targets may not be included with other targets, i.e. they must be
1867the only target specified.
1868.Bl -tag -width .BEGINx
1869.It Ic .BEGIN
1870Any command lines attached to this target are executed before anything
1871else is done.
1872.It Ic .DEFAULT
1873This is sort of a
1874.Ic .USE
1875rule for any target (that was used only as a
1876source) that
1877.Nm
1878can't figure out any other way to create.
1879Only the shell script is used.
1880The
1881.Ic .IMPSRC
1882variable of a target that inherits
1883.Ic .DEFAULT Ns 's
1884commands is set
1885to the target's own name.
1886.It Ic .END
1887Any command lines attached to this target are executed after everything
1888else is done.
1889.It Ic .ERROR
1890Any command lines attached to this target are executed when another target fails.
1891The
1892.Ic .ERROR_TARGET
1893variable is set to the target that failed.
1894See also
1895.Ic MAKE_PRINT_VAR_ON_ERROR .
1896.It Ic .IGNORE
1897Mark each of the sources with the
1898.Ic .IGNORE
1899attribute.
1900If no sources are specified, this is the equivalent of specifying the
1901.Fl i
1902option.
1903.It Ic .INTERRUPT
1904If
1905.Nm
1906is interrupted, the commands for this target will be executed.
1907.It Ic .MAIN
1908If no target is specified when
1909.Nm
1910is invoked, this target will be built.
1911.It Ic .MAKEFLAGS
1912This target provides a way to specify flags for
1913.Nm
1914when the makefile is used.
1915The flags are as if typed to the shell, though the
1916.Fl f
1917option will have
1918no effect.
1919.\" XXX: NOT YET!!!!
1920.\" .It Ic .NOTPARALLEL
1921.\" The named targets are executed in non parallel mode.
1922.\" If no targets are
1923.\" specified, then all targets are executed in non parallel mode.
1924.It Ic .NOPATH
1925Apply the
1926.Ic .NOPATH
1927attribute to any specified sources.
1928.It Ic .NOTPARALLEL
1929Disable parallel mode.
1930.It Ic .NO_PARALLEL
1931Synonym for
1932.Ic .NOTPARALLEL ,
1933for compatibility with other pmake variants.
1934.It Ic .ORDER
1935The named targets are made in sequence.
1936This ordering does not add targets to the list of targets to be made.
1937Since the dependents of a target do not get built until the target itself
1938could be built, unless
1939.Ql a
1940is built by another part of the dependency graph,
1941the following is a dependency loop:
1942.Bd -literal
1943\&.ORDER: b a
1944b: a
1945.Ed
1946.Pp
1947The ordering imposed by
1948.Ic .ORDER
1949is only relevant for parallel makes.
1950.\" XXX: NOT YET!!!!
1951.\" .It Ic .PARALLEL
1952.\" The named targets are executed in parallel mode.
1953.\" If no targets are
1954.\" specified, then all targets are executed in parallel mode.
1955.It Ic .PATH
1956The sources are directories which are to be searched for files not
1957found in the current directory.
1958If no sources are specified, any previously specified directories are
1959deleted.
1960If the source is the special
1961.Ic .DOTLAST
1962target, then the current working
1963directory is searched last.
1964.It Ic .PHONY
1965Apply the
1966.Ic .PHONY
1967attribute to any specified sources.
1968.It Ic .PRECIOUS
1969Apply the
1970.Ic .PRECIOUS
1971attribute to any specified sources.
1972If no sources are specified, the
1973.Ic .PRECIOUS
1974attribute is applied to every
1975target in the file.
1976.It Ic .SHELL
1977Sets the shell that
1978.Nm
1979will use to execute commands.
1980The sources are a set of
1981.Ar field=value
1982pairs.
1983.Bl -tag -width hasErrCtls
1984.It Ar name
1985This is the minimal specification, used to select one of the builtin
1986shell specs;
1987.Ar sh ,
1988.Ar ksh ,
1989and
1990.Ar csh .
1991.It Ar path
1992Specifies the path to the shell.
1993.It Ar hasErrCtl
1994Indicates whether the shell supports exit on error.
1995.It Ar check
1996The command to turn on error checking.
1997.It Ar ignore
1998The command to disable error checking.
1999.It Ar echo
2000The command to turn on echoing of commands executed.
2001.It Ar quiet
2002The command to turn off echoing of commands executed.
2003.It Ar filter
2004The output to filter after issuing the
2005.Ar quiet
2006command.
2007It is typically identical to
2008.Ar quiet .
2009.It Ar errFlag
2010The flag to pass the shell to enable error checking.
2011.It Ar echoFlag
2012The flag to pass the shell to enable command echoing.
2013.It Ar newline
2014The string literal to pass the shell that results in a single newline
2015character when used outside of any quoting characters.
2016.El
2017Example:
2018.Bd -literal
2019\&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e
2020 check="set \-e" ignore="set +e" \e
2021 echo="set \-v" quiet="set +v" filter="set +v" \e
2022 echoFlag=v errFlag=e newline="'\en'"
2023.Ed
2024.It Ic .SILENT
2025Apply the
2026.Ic .SILENT
2027attribute to any specified sources.
2028If no sources are specified, the
2029.Ic .SILENT
2030attribute is applied to every
2031command in the file.
|
| 2032.It Ic .STALE
2033This target gets run when a dependency file contains stale entries, having
2034.Va .ALLSRC
2035set to the name of that dependency 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.
| 2036.It Ic .SUFFIXES
2037Each source specifies a suffix to
2038.Nm .
2039If no sources are specified, any previously specified suffixes are deleted.
2040It allows the creation of suffix-transformation rules.
2041.Pp
2042Example:
2043.Bd -literal
2044\&.SUFFIXES: .o
2045\&.c.o:
2046 cc \-o ${.TARGET} \-c ${.IMPSRC}
2047.Ed
2048.El
2049.Sh ENVIRONMENT
2050.Nm
2051uses the following environment variables, if they exist:
2052.Ev MACHINE ,
2053.Ev MACHINE_ARCH ,
2054.Ev MAKE ,
2055.Ev MAKEFLAGS ,
2056.Ev MAKEOBJDIR ,
2057.Ev MAKEOBJDIRPREFIX ,
2058.Ev MAKESYSPATH ,
2059.Ev PWD ,
2060and
2061.Ev TMPDIR .
2062.Pp
2063.Ev MAKEOBJDIRPREFIX
2064and
2065.Ev MAKEOBJDIR
2066may only be set in the environment or on the command line to
2067.Nm
2068and not as makefile variables;
2069see the description of
2070.Ql Va .OBJDIR
2071for more details.
2072.Sh FILES
2073.Bl -tag -width /usr/share/mk -compact
2074.It .depend
2075list of dependencies
2076.It Makefile
2077list of dependencies
2078.It makefile
2079list of dependencies
2080.It sys.mk
2081system makefile
2082.It /usr/share/mk
2083system makefile directory
2084.El
2085.Sh COMPATIBILITY
2086The basic make syntax is compatible between different versions of make,
2087however the special variables, variable modifiers and conditionals are not.
2088.Pp
2089The way that parallel makes are scheduled changed in
2090.Nx 4.0
2091so that .ORDER and .WAIT apply recursively to the dependent nodes.
2092The algorithms used may change again in the future.
2093.Pp
2094The way that .for loop variables are substituted changed after
2095.Nx 5.0
2096so that they still appear to be variable expansions.
2097In particular this stops them being treated as syntax, and removes some
2098obscure problems using them in .if statements.
2099.Sh SEE ALSO
2100.Xr mkdep 1
2101.Sh HISTORY
2102A
2103.Nm
2104command appeared in
2105.At v7 .
2106This
2107.Nm
2108implementation is based on Adam De Boor's pmake program which was written
2109for Sprite at Berkeley.
2110It was designed to be a parallel distributed make running jobs on different
2111machines using a daemon called
2112.Dq customs .
2113.Sh BUGS
2114The
2115.Nm
2116syntax is difficult to parse without actually acting of the data.
2117For instance finding the end of a variable use should involve scanning each
2118the modifiers using the correct terminator for each field.
2119In many places
2120.Nm
2121just counts {} and () in order to find the end of a variable expansion.
2122.Pp
2123There is no way of escaping a space character in a filename.
|