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