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