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