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