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