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