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