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.\"
|
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.
|
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. |
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. |
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. |
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.
|