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