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