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