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