Annotation of src/usr.bin/make/make.1, Revision 1.45
1.45 ! sommerfe 1: .\" $NetBSD: make.1,v 1.44 2000/12/30 02:05:21 sommerfeld 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.
14: .\" 3. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
1.16 christos 34: .\" from: @(#)make.1 8.4 (Berkeley) 3/19/94
1.1 cgd 35: .\"
1.16 christos 36: .Dd March 19, 1994
1.1 cgd 37: .Dt MAKE 1
38: .Os
39: .Sh NAME
40: .Nm make
41: .Nd maintain program dependencies
42: .Sh SYNOPSIS
1.30 mycroft 43: .Nm ""
1.45 ! sommerfe 44: .Op Fl BeikNnqrst
1.30 mycroft 45: .Bk -words
1.1 cgd 46: .Op Fl D Ar variable
1.30 mycroft 47: .Ek
48: .Bk -words
1.1 cgd 49: .Op Fl d Ar flags
1.30 mycroft 50: .Ek
51: .Bk -words
1.1 cgd 52: .Op Fl f Ar makefile
1.30 mycroft 53: .Ek
54: .Bk -words
1.1 cgd 55: .Op Fl I Ar directory
1.30 mycroft 56: .Ek
1.1 cgd 57: .Bk -words
58: .Op Fl j Ar max_jobs
1.30 mycroft 59: .Ek
60: .Bk -words
1.44 sommerfe 61: .Op Fl J Ar private
62: .Ek
63: .Bk -words
1.13 christos 64: .Op Fl m Ar directory
1.1 cgd 65: .Ek
1.30 mycroft 66: .Bk -words
1.44 sommerfe 67: .Op Fl T Ar file
68: .Ek
69: .Bk -words
1.16 christos 70: .Op Fl V Ar variable
1.30 mycroft 71: .Ek
1.1 cgd 72: .Op Ar variable=value
1.30 mycroft 73: .Bk -words
1.1 cgd 74: .Op Ar target ...
1.30 mycroft 75: .Ek
1.1 cgd 76: .Sh DESCRIPTION
1.25 lukem 77: .Nm
1.1 cgd 78: is a program designed to simplify the maintenance of other programs.
79: Its input is a list of specifications as to the files upon which programs
80: and other files depend.
81: If the file
82: .Ql Pa makefile
83: exists, it is read for this list of specifications.
84: If it does not exist, the file
85: .Ql Pa Makefile
86: is read.
87: If the file
88: .Ql Pa .depend
89: exists, it is read (see
90: .Xr mkdep 1) .
91: .Pp
92: This manual page is intended as a reference document only.
93: For a more thorough description of
1.25 lukem 94: .Nm
1.1 cgd 95: and makefiles, please refer to
96: .%T "Make \- A Tutorial" .
97: .Pp
98: The options are as follows:
99: .Bl -tag -width Ds
1.16 christos 100: .It Fl B
1.10 christos 101: Try to be backwards compatible by executing a single shell per command and
102: by executing the commands to make the sources of a dependency line in sequence.
1.1 cgd 103: .It Fl D Ar variable
1.8 christos 104: Define
105: .Ar variable
1.1 cgd 106: to be 1, in the global context.
107: .It Fl d Ar flags
108: Turn on debugging, and specify which portions of
1.25 lukem 109: .Nm
1.1 cgd 110: are to print debugging information.
111: .Ar Flags
112: is one or more of the following:
113: .Bl -tag -width Ds
114: .It Ar A
115: Print all possible debugging information;
116: equivalent to specifying all of the debugging flags.
117: .It Ar a
118: Print debugging information about archive searching and caching.
119: .It Ar c
120: Print debugging information about conditional evaluation.
121: .It Ar d
122: Print debugging information about directory searching and caching.
123: .It Ar "g1"
124: Print the input graph before making anything.
125: .It Ar "g2"
126: Print the input graph after making everything, or before exiting
127: on error.
128: .It Ar j
129: Print debugging information about running multiple shells.
130: .It Ar m
131: Print debugging information about making targets, including modification
132: dates.
133: .It Ar s
134: Print debugging information about suffix-transformation rules.
135: .It Ar t
136: Print debugging information about target list maintenance.
137: .It Ar v
138: Print debugging information about variable assignment.
139: .El
140: .It Fl e
141: Specify that environmental variables override macro assignments within
142: makefiles.
143: .It Fl f Ar makefile
144: Specify a makefile to read instead of the default
145: .Ql Pa makefile
146: and
147: If
148: .Ar makefile
149: is
150: .Ql Fl ,
151: standard input is read.
152: Multiple makefile's may be specified, and are read in the order specified.
153: .It Fl I Ar directory
154: Specify a directory in which to search for makefiles and included makefiles.
1.13 christos 155: The system makefile directory (or directories, see the
156: .Fl m
157: option) is automatically included as part of this list.
1.1 cgd 158: .It Fl i
159: Ignore non-zero exit of shell commands in the makefile.
160: Equivalent to specifying
161: .Ql Fl
162: before each command line in the makefile.
1.44 sommerfe 163: .It Fl J Ar private
164: This option should
165: .Em not
166: be specified by the user.
167: .Pp
168: When the
169: .Ar j
170: option is in use in a recursive build, this option is passed by a make
171: to child makes to allow all the make processes in the build to
172: cooperate to avoid overloading the system.
1.1 cgd 173: .It Fl j Ar max_jobs
174: Specify the maximum number of jobs that
1.25 lukem 175: .Nm
1.16 christos 176: may have running at any one time. Turns compatibility mode off, unless the
1.11 christos 177: .Ar B
178: flag is also specified.
1.1 cgd 179: .It Fl k
180: Continue processing after errors are encountered, but only on those targets
181: that do not depend on the target whose creation caused the error.
1.13 christos 182: .It Fl m Ar directory
183: Specify a directory in which to search for sys.mk and makefiles included
184: via the <...> style. Multiple directories can be added to form a search path.
185: This path will override the default system include path: /usr/share/mk.
186: Furthermore the system include path will be appended to the search path used
187: for "..."-style inclusions (see the
188: .Fl I
189: option).
1.1 cgd 190: .It Fl n
1.45 ! sommerfe 191: Display the commands that would have been executed, but do not
! 192: actually execute them unless the target depends on the .MAKE special
! 193: source (see below)
! 194: .It Fl N
! 195: Display the commands which would have been executed, but do not
! 196: actually execute any of them; useful for debugging top-level makefiles
! 197: without descending into subdirectories.
1.1 cgd 198: .It Fl q
199: Do not execute any commands, but exit 0 if the specified targets are
200: up-to-date and 1, otherwise.
201: .It Fl r
202: Do not use the built-in rules specified in the system makefile.
203: .It Fl s
204: Do not echo any commands as they are executed.
205: Equivalent to specifying
206: .Ql Ic @
207: before each command line in the makefile.
1.44 sommerfe 208: .It Fl T Ar tracefile
209: When used with the
210: .Fl j
211: flag,
212: append a trace record to
213: .Ar tracefile
214: for each job started and completed.
1.1 cgd 215: .It Fl t
216: Rather than re-building a target as specified in the makefile, create it
217: or update its modification time to make it appear up-to-date.
1.16 christos 218: .It Fl V Ar variable
219: Print
1.25 lukem 220: .Nm "" Ns 's
1.16 christos 221: idea of the value of
222: .Ar variable ,
223: in the global context.
224: Do not build any targets.
225: Multiple instances of this option may be specified;
226: the variables will be printed one per line,
227: with a blank line for each null or undefined variable.
1.1 cgd 228: .It Ar variable=value
229: Set the value of the variable
230: .Ar variable
231: to
232: .Ar value .
233: .El
234: .Pp
1.6 cgd 235: There are seven different types of lines in a makefile: file dependency
1.1 cgd 236: specifications, shell commands, variable assignments, include statements,
1.6 cgd 237: conditional directives, for loops, and comments.
1.1 cgd 238: .Pp
239: In general, lines may be continued from one line to the next by ending
240: them with a backslash
241: .Pq Ql \e .
242: The trailing newline character and initial whitespace on the following
243: line are compressed into a single space.
244: .Sh FILE DEPENDENCY SPECIFICATIONS
245: Dependency lines consist of one or more targets, an operator, and zero
246: or more sources.
247: This creates a relationship where the targets ``depend'' on the sources
248: and are usually created from them.
249: The exact relationship between the target and the source is determined
250: by the operator that separates them.
251: The three operators are as follows:
252: .Bl -tag -width flag
253: .It Ic \&:
254: A target is considered out-of-date if its modification time is less than
255: those of any of its sources.
256: Sources for a target accumulate over dependency lines when this operator
257: is used.
258: The target is removed if
1.25 lukem 259: .Nm
1.1 cgd 260: is interrupted.
261: .It Ic \&!
262: Targets are always re-created, but not until all sources have been
263: examined and re-created as necessary.
264: Sources for a target accumulate over dependency lines when this operator
265: is used.
266: The target is removed if
1.25 lukem 267: .Nm
1.1 cgd 268: is interrupted.
269: .It Ic \&::
270: If no sources are specified, the target is always re-created.
271: Otherwise, a target is considered out-of-date if any of its sources has
272: been modified more recently than the target.
273: Sources for a target do not accumulate over dependency lines when this
274: operator is used.
275: The target will not be removed if
1.25 lukem 276: .Nm
1.1 cgd 277: is interrupted.
278: .El
279: .Pp
280: Targets and sources may contain the shell wildcard values
281: .Ql ? ,
282: .Ql * ,
283: .Ql []
284: and
285: .Ql {} .
286: The values
287: .Ql ? ,
288: .Ql *
289: and
290: .Ql []
291: may only be used as part of the final
292: component of the target or source, and must be used to describe existing
293: files.
294: The value
295: .Ql {}
296: need not necessarily be used to describe existing files.
297: Expansion is in directory order, not alphabetically as done in the shell.
298: .Sh SHELL COMMANDS
299: Each target may have associated with it a series of shell commands, normally
300: used to create the target.
301: Each of the commands in this script
302: .Em must
303: be preceded by a tab.
304: While any target may appear on a dependency line, only one of these
305: dependencies may be followed by a creation script, unless the
306: .Ql Ic ::
307: operator is used.
308: .Pp
309: If the first or first two characters of the command line are
310: .Ql Ic @
311: and/or
312: .Ql Ic \- ,
313: the command is treated specially.
314: A
315: .Ql Ic @
316: causes the command not to be echoed before it is executed.
317: A
318: .Ql Ic \-
319: causes any non-zero exit status of the command line to be ignored.
320: .Sh VARIABLE ASSIGNMENTS
321: Variables in make are much like variables in the shell, and, by tradition,
322: consist of all upper-case letters.
323: The five operators that can be used to assign values to variables are as
324: follows:
325: .Bl -tag -width Ds
326: .It Ic \&=
327: Assign the value to the variable.
328: Any previous value is overridden.
329: .It Ic \&+=
330: Append the value to the current value of the variable.
331: .It Ic \&?=
332: Assign the value to the variable if it is not already defined.
333: .It Ic \&:=
334: Assign with expansion, i.e. expand the value before assigning it
335: to the variable.
336: Normally, expansion is not done until the variable is referenced.
337: .It Ic \&!=
338: Expand the value and pass it to the shell for execution and assign
339: the result to the variable.
340: Any newlines in the result are replaced with spaces.
341: .El
342: .Pp
343: Any white-space before the assigned
344: .Ar value
345: is removed; if the value is being appended, a single space is inserted
346: between the previous contents of the variable and the appended value.
347: .Pp
348: Variables are expanded by surrounding the variable name with either
349: curly braces
350: .Pq Ql {}
1.7 mycroft 351: or parentheses
1.1 cgd 352: .Pq Ql ()
353: and preceding it with
354: a dollar sign
355: .Pq Ql \&$ .
356: If the variable name contains only a single letter, the surrounding
1.7 mycroft 357: braces or parentheses are not required.
1.1 cgd 358: This shorter form is not recommended.
359: .Pp
360: Variable substitution occurs at two distinct times, depending on where
361: the variable is being used.
362: Variables in dependency lines are expanded as the line is read.
363: Variables in shell commands are expanded when the shell command is
364: executed.
365: .Pp
366: The four different classes of variables (in order of increasing precedence)
367: are:
368: .Bl -tag -width Ds
369: .It Environment variables
370: Variables defined as part of
1.25 lukem 371: .Nm "" Ns 's
1.1 cgd 372: environment.
373: .It Global variables
374: Variables defined in the makefile or in included makefiles.
375: .It Command line variables
376: Variables defined as part of the command line.
377: .It Local variables
378: Variables that are defined specific to a certain target.
379: The seven local variables are as follows:
380: .Bl -tag -width ".ARCHIVE"
381: .It Va .ALLSRC
382: The list of all sources for this target; also known as
383: .Ql Va \&> .
384: .It Va .ARCHIVE
385: The name of the archive file.
386: .It Va .IMPSRC
387: The name/path of the source from which the target is to be transformed
388: (the ``implied'' source); also known as
389: .Ql Va \&< .
390: .It Va .MEMBER
391: The name of the archive member.
392: .It Va .OODATE
393: The list of sources for this target that were deemed out-of-date; also
394: known as
395: .Ql Va \&? .
396: .It Va .PREFIX
397: The file prefix of the file, containing only the file portion, no suffix
398: or preceding directory components; also known as
399: .Ql Va * .
400: .It Va .TARGET
401: The name of the target; also known as
402: .Ql Va @ .
403: .El
404: .Pp
405: The shorter forms
406: .Ql Va @ ,
407: .Ql Va ? ,
408: .Ql Va \&>
409: and
410: .Ql Va *
411: are permitted for backward
412: compatibility with historical makefiles and are not recommended.
413: The six variables
414: .Ql Va "@F" ,
415: .Ql Va "@D" ,
416: .Ql Va "<F" ,
417: .Ql Va "<D" ,
418: .Ql Va "*F"
419: and
420: .Ql Va "*D"
421: are
422: permitted for compatibility with
423: .At V
424: makefiles and are not recommended.
425: .Pp
426: Four of the local variables may be used in sources on dependency lines
427: because they expand to the proper value for each target on the line.
428: These variables are
429: .Ql Va .TARGET ,
430: .Ql Va .PREFIX ,
431: .Ql Va .ARCHIVE ,
432: and
433: .Ql Va .MEMBER .
434: .Pp
435: In addition,
1.25 lukem 436: .Nm
1.1 cgd 437: sets or knows about the following variables:
438: .Bl -tag -width MAKEFLAGS
439: .It Va \&$
440: A single dollar sign
441: .Ql \&$ ,
442: i.e.
443: .Ql \&$$
444: expands to a single dollar
445: sign.
446: .It Va .MAKE
447: The name that
1.25 lukem 448: .Nm
1.1 cgd 449: was executed with
1.22 pk 450: .Pq Va argv[0]
1.1 cgd 451: .It Va .CURDIR
452: A path to the directory where
1.25 lukem 453: .Nm
1.1 cgd 454: was executed.
1.4 pk 455: .It Va .OBJDIR
456: A path to the directory where the targets are built.
1.35 aidan 457: .It Va .PARSEDIR
458: A path to the directory of the current
459: .Ql Pa Makefile
460: being parsed.
461: .It Va .PARSEFILE
462: The basename of the current
463: .Ql Pa Makefile
464: being parsed.
465: This variable and
466: .Ql Va .PARSEFILE
467: are both set only while the
468: .Ql Pa Makefiles
469: are being parsed.
1.1 cgd 470: .It Ev MAKEFLAGS
471: The environment variable
472: .Ql Ev MAKEFLAGS
473: may contain anything that
474: may be specified on
1.25 lukem 475: .Nm "" Ns 's
1.1 cgd 476: command line.
477: Anything specified on
1.25 lukem 478: .Nm "" Ns 's
1.1 cgd 479: command line is appended to the
480: .Ql Ev MAKEFLAGS
481: variable which is then
482: entered into the environment for all programs which
1.25 lukem 483: .Nm
1.1 cgd 484: executes.
1.16 christos 485: .It Ev PWD
486: Alternate path to the current directory.
1.25 lukem 487: .Nm
1.16 christos 488: normally sets
489: .Ql Va .CURDIR
490: to the canonical path given by
491: .Xr getcwd 2 .
492: However, if the environment variable
493: .Ql Ev PWD
494: is set and gives a path to the current directory, then
1.25 lukem 495: .Nm
1.16 christos 496: sets
497: .Ql Va .CURDIR
498: to the value of
499: .Ql Ev PWD
1.40 sjg 500: instead. This behaviour is disabled if
501: .Ql Ev MAKEOBJDIRPREFIX
502: is set.
1.16 christos 503: .Ql Ev PWD
504: is set to the value of
505: .Ql Va .OBJDIR
506: for all programs which
1.25 lukem 507: .Nm
1.16 christos 508: executes.
1.1 cgd 509: .El
510: .Pp
511: Variable expansion may be modified to select or modify each word of the
512: variable (where a ``word'' is white-space delimited sequence of characters).
513: The general format of a variable expansion is as follows:
514: .Pp
515: .Dl {variable[:modifier[:...]]}
516: .Pp
517: Each modifier begins with a colon and one of the following
518: special characters.
519: The colon may be escaped with a backslash
520: .Pq Ql \e .
521: .Bl -tag -width Cm E\&
522: .It Cm E
523: Replaces each word in the variable with its suffix.
524: .It Cm H
525: Replaces each word in the variable with everything but the last component.
526: .It Cm M Ns Ar pattern
527: Select only those words that match the rest of the modifier.
528: The standard shell wildcard characters
529: .Pf ( Ql * ,
530: .Ql ? ,
531: and
532: .Ql Op )
533: may
534: be used.
535: The wildcard characters may be escaped with a backslash
536: .Pq Ql \e .
537: .It Cm N Ns Ar pattern
538: This is identical to
539: .Ql Cm M ,
540: but selects all words which do not match
541: the rest of the modifier.
1.36 christos 542: .It Cm O
543: Order every word in variable alphabetically.
1.17 christos 544: .It Cm Q
545: Quotes every shell meta-character in the variable, so that it can be passed
546: safely through recursive invocations of
1.25 lukem 547: .Nm "" .
1.1 cgd 548: .It Cm R
549: Replaces each word in the variable with everything but its suffix.
550: .Sm off
1.17 christos 551: .It Cm S No \&/ Ar old_string Xo
552: .No \&/ Ar new_string
553: .No \&/ Op Cm 1g
1.1 cgd 554: .Xc
555: .Sm on
556: Modify the first occurrence of
1.17 christos 557: .Ar old_string
558: in the variable's value, replacing it with
559: .Ar new_string .
1.1 cgd 560: If a
561: .Ql g
562: is appended to the last slash of the pattern, all occurrences
563: in each word are replaced.
1.17 christos 564: If a
565: .Ql 1
566: is appended to the last slash of the pattern, only the first word
567: is affected.
1.1 cgd 568: If
1.17 christos 569: .Ar old_string
570: begins with a caret
1.1 cgd 571: .Pq Ql ^ ,
1.17 christos 572: .Ar old_string
1.1 cgd 573: is anchored at the beginning of each word.
574: If
1.17 christos 575: .Ar old_string
1.1 cgd 576: ends with a dollar sign
577: .Pq Ql \&$ ,
578: it is anchored at the end of each word.
579: Inside
580: .Ar new_string ,
581: an ampersand
582: .Pq Ql &
583: is replaced by
1.17 christos 584: .Ar old_string
585: (without any
586: .Ql ^
587: or
588: .Ql \&$ ) .
1.1 cgd 589: Any character may be used as a delimiter for the parts of the modifier
590: string.
591: The anchoring, ampersand and delimiter characters may be escaped with a
592: backslash
593: .Pq Ql \e .
594: .Pp
595: Variable expansion occurs in the normal fashion inside both
596: .Ar old_string
597: and
598: .Ar new_string
599: with the single exception that a backslash is used to prevent the expansion
600: of a dollar sign
1.17 christos 601: .Pq Ql \&$ ,
1.1 cgd 602: not a preceding dollar sign as is usual.
1.17 christos 603: .Sm off
604: .It Cm C No \&/ Ar pattern Xo
605: .No \&/ Ar replacement
606: .No \&/ Op Cm 1g
607: .Xc
608: .Sm on
609: The
610: .Cm C
611: modifier is just like the
612: .Cm S
1.37 msaitoh 613: modifier except that the old and new strings, instead of being
1.17 christos 614: simple strings, are a regular expression (see
615: .Xr regex 3 )
616: and an
617: .Xr ed 1 Ns \-style
618: replacement string. Normally, the first occurrence of the pattern in
619: each word of the value is changed. The
620: .Ql 1
621: modifier causes the substitution to apply to at most one word; the
622: .Ql g
623: modifier causes the substitution to apply to as many instances of the
624: search pattern as occur in the word or words it is found in. Note that
625: .Ql 1
626: and
627: .Ql g
628: are orthogonal; the former specifies whether multiple words are
629: potentially affected, the latter whether multiple substitutions can
630: potentially occur within each affected word.
1.1 cgd 631: .It Cm T
632: Replaces each word in the variable with its last component.
1.43 christos 633: .It Cm u
634: Remove adjacent duplicate words (like
635: .Xr uniq 1 ).
1.40 sjg 636: .It Cm ? Ar true_string Cm : Ar false_string
1.27 christos 637: If the variable evaluates to true, return as its value the
638: .Ar true_string,
639: otherwise return the
640: .Ar false_string.
1.1 cgd 641: .It Ar old_string=new_string
642: This is the
643: .At V
644: style variable substitution.
645: It must be the last modifier specified.
1.16 christos 646: If
1.6 cgd 647: .Ar old_string
648: or
649: .Ar new_string
650: do not contain the pattern matching character
651: .Ar %
1.16 christos 652: then it is assumed that they are
1.6 cgd 653: anchored at the end of each word, so only suffixes or entire
1.16 christos 654: words may be replaced. Otherwise
1.6 cgd 655: .Ar %
1.16 christos 656: is the substring of
657: .Ar old_string
1.6 cgd 658: to be replaced in
659: .Ar new_string
1.40 sjg 660: .It Cm @ Ar temp Cm @ Xo
661: .No Ar string Cm @
662: .Xc
663: This is the loop expansion mechanism from the OSF Development
664: Environment (ODE) make. Unlike
665: .Cm \&.for
666: loops expansion occurs at the time of
667: reference. Assign
668: .Ar temp
669: to each word in the variable and evaluate
670: .Ar string .
671: The ODE convention is that
672: .Ar temp
673: should start and end with a period. For example.
674: .Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
675: .It Cm U Ar newval
676: If the variable is undefined
677: .Ar newval
678: is the value. This is another ODE make feature. It is handy for
679: setting per-target CFLAGS for instance:
680: .Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
681: .It Cm D Ar newval
682: If the variable is defined
683: .Ar newval
684: is the value.
685: .It Cm L
686: The name of the variable is the value.
687: .It Cm P
688: The path of the node which has the same name as the variable
689: is the value. If no such node exists or its path is null, then the
690: name of the variable is used.
691: .It Cm ! Ar cmd Cm !
692: The output of running
693: .Ar cmd
694: is the value.
695: .It Cm sh
696: If the variable is non-empty it is run as a command and the output
697: becomes the new value.
1.42 sjg 698: .It Cm \&:= Ar str
1.41 sjg 699: The variable is assigned the value
700: .Ar str
701: after substitution. This modifier and its variations are useful in
702: obscure situations such as wanting to apply modifiers to
703: .Cm \&.for
704: loop iteration variables which won't work due to the way
705: .Cm \&.for
706: loops are implemented. These assignment modifiers always expand to
707: nothing, so if appearing in a rule line by themselves should be
708: preceded with something to keep
709: .Nm
710: happy. As in:
711: .Bd -literal
712: use_foo: \&.USE
713: \&.for i in ${\&.TARGET} ${\&.TARGET:R}\&.gz
1.42 sjg 714: @: ${t::=$i}
1.41 sjg 715: @echo t:R:T=${t:R:T}
716: \&.endfor
717:
718: .Ed
1.42 sjg 719: The double
720: .Cm \&:
721: helps avoid false matches with the
722: .At V
723: style
724: .Cm \&=
725: modifier and since substitution always occurs the
726: .Cm \&:=
727: form is vaguely appropriate.
728: .It Cm \&:?= Ar str
1.41 sjg 729: As for
1.42 sjg 730: .Cm \&:=
1.41 sjg 731: but only if the variable does not already have a value.
1.42 sjg 732: .It Cm \&:+= Ar str
1.41 sjg 733: Append
734: .Ar str
735: to the variable.
1.42 sjg 736: .It Cm \&:!= Ar cmd
1.41 sjg 737: Assign the output of
738: .Ar cmd
739: to the variable.
1.32 erh 740: .El
1.6 cgd 741: .El
742: .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1.16 christos 743: Makefile inclusion, conditional structures and for loops reminiscent
1.6 cgd 744: of the C programming language are provided in
1.25 lukem 745: .Nm "" .
1.1 cgd 746: All such structures are identified by a line beginning with a single
747: dot
748: .Pq Ql \&.
749: character.
750: Files are included with either
1.29 ross 751: .Cm \&.include Aq Ar file
1.1 cgd 752: or
1.29 ross 753: .Cm \&.include Pf \*q Ar file Ns \*q .
1.1 cgd 754: Variables between the angle brackets or double quotes are expanded
755: to form the file name.
756: If angle brackets are used, the included makefile is expected to be in
757: the system makefile directory.
758: If double quotes are used, the including makefile's directory and any
759: directories specified using the
760: .Fl I
761: option are searched before the system
762: makefile directory.
1.28 christos 763: For compatibility with other versions of
764: .Nm
765: .Ql include file ...
1.29 ross 766: is also accepted. If the include statement is written as
767: .Cm .-include
768: or as
769: .Cm .sinclude
1.28 christos 770: then errors locating and/or opening include files are ignored.
1.1 cgd 771: .Pp
772: Conditional expressions are also preceded by a single dot as the first
1.5 jtc 773: character of a line.
1.1 cgd 774: The possible conditionals are as follows:
775: .Bl -tag -width Ds
776: .It Ic .undef Ar variable
777: Un-define the specified global variable.
778: Only global variables may be un-defined.
779: .It Xo
780: .Ic \&.if
781: .Oo \&! Oc Ns Ar expression
782: .Op Ar operator expression ...
783: .Xc
784: Test the value of an expression.
785: .It Xo
786: .Ic .ifdef
787: .Oo \&! Oc Ns Ar variable
788: .Op Ar operator variable ...
789: .Xc
1.7 mycroft 790: Test the value of a variable.
1.1 cgd 791: .It Xo
792: .Ic .ifndef
793: .Oo \&! Oc Ns Ar variable
794: .Op Ar operator variable ...
795: .Xc
1.7 mycroft 796: Test the value of a variable.
1.1 cgd 797: .It Xo
798: .Ic .ifmake
799: .Oo \&! Oc Ns Ar target
800: .Op Ar operator target ...
801: .Xc
1.7 mycroft 802: Test the target being built.
1.1 cgd 803: .It Xo
804: .Ic .ifnmake
805: .Oo \&! Oc Ar target
806: .Op Ar operator target ...
807: .Xc
808: Test the target being built.
809: .It Ic .else
810: Reverse the sense of the last conditional.
811: .It Xo
812: .Ic .elif
813: .Oo \&! Oc Ar expression
814: .Op Ar operator expression ...
815: .Xc
816: A combination of
817: .Ql Ic .else
818: followed by
819: .Ql Ic .if .
820: .It Xo
821: .Ic .elifdef
822: .Oo \&! Oc Ns Ar variable
823: .Op Ar operator variable ...
824: .Xc
825: A combination of
826: .Ql Ic .else
827: followed by
828: .Ql Ic .ifdef .
829: .It Xo
830: .Ic .elifndef
831: .Oo \&! Oc Ns Ar variable
832: .Op Ar operator variable ...
833: .Xc
834: A combination of
835: .Ql Ic .else
836: followed by
837: .Ql Ic .ifndef .
838: .It Xo
839: .Ic .elifmake
840: .Oo \&! Oc Ns Ar target
841: .Op Ar operator target ...
842: .Xc
843: A combination of
844: .Ql Ic .else
845: followed by
846: .Ql Ic .ifmake .
847: .It Xo
848: .Ic .elifnmake
849: .Oo \&! Oc Ns Ar target
850: .Op Ar operator target ...
851: .Xc
852: A combination of
853: .Ql Ic .else
854: followed by
855: .Ql Ic .ifnmake .
856: .It Ic .endif
857: End the body of the conditional.
858: .El
859: .Pp
860: The
861: .Ar operator
862: may be any one of the following:
863: .Bl -tag -width "Cm XX"
864: .It Cm \&|\&|
865: logical OR
866: .It Cm \&&&
867: Logical
868: .Tn AND ;
869: of higher precedence than
1.26 hubertf 870: .Dq \&|\&| .
1.1 cgd 871: .El
872: .Pp
873: As in C,
1.25 lukem 874: .Nm
1.1 cgd 875: will only evaluate a conditional as far as is necessary to determine
876: its value.
1.16 christos 877: Parentheses may be used to change the order of evaluation.
1.1 cgd 878: The boolean operator
879: .Ql Ic \&!
880: may be used to logically negate an entire
881: conditional.
1.5 jtc 882: It is of higher precedence than
1.1 cgd 883: .Ql Ic \&&& .
884: .Pp
885: The value of
886: .Ar expression
887: may be any of the following:
888: .Bl -tag -width Ic defined
889: .It Ic defined
890: Takes a variable name as an argument and evaluates to true if the variable
891: has been defined.
892: .It Ic make
893: Takes a target name as an argument and evaluates to true if the target
894: was specified as part of
1.25 lukem 895: .Nm "" Ns 's
1.1 cgd 896: command line or was declared the default target (either implicitly or
897: explicitly, see
898: .Va .MAIN )
899: before the line containing the conditional.
900: .It Ic empty
1.5 jtc 901: Takes a variable, with possible modifiers, and evaluates to true if
1.1 cgd 902: the expansion of the variable would result in an empty string.
903: .It Ic exists
904: Takes a file name as an argument and evaluates to true if the file exists.
905: The file is searched for on the system search path (see
906: .Va .PATH ) .
907: .It Ic target
908: Takes a target name as an argument and evaluates to true if the target
909: has been defined.
910: .El
911: .Pp
912: .Ar Expression
1.6 cgd 913: may also be an arithmetic or string comparison. Variable expansion is
914: performed on both sides of the comparison, after which the integral
915: values are compared. A value is interpreted as hexadecimal if it is
916: preceded by 0x, otherwise it is decimal; octal numbers are not supported.
917: The standard C relational operators are all supported. If after
918: variable expansion, either the left or right hand side of a
1.1 cgd 919: .Ql Ic ==
920: or
921: .Ql Ic "!="
1.6 cgd 922: operator is not an integral value, then
923: string comparison is performed between the expanded
924: variables.
1.1 cgd 925: If no relational operator is given, it is assumed that the expanded
926: variable is being compared against 0.
927: .Pp
928: When
1.25 lukem 929: .Nm
1.1 cgd 930: is evaluating one of these conditional expression, and it encounters
931: a word it doesn't recognize, either the ``make'' or ``defined''
932: expression is applied to it, depending on the form of the conditional.
933: If the form is
934: .Ql Ic .ifdef
935: or
936: .Ql Ic .ifndef ,
937: the ``defined'' expression
938: is applied.
939: Similarly, if the form is
940: .Ql Ic .ifmake
941: or
942: .Ql Ic .ifnmake , the ``make''
943: expression is applied.
944: .Pp
945: If the conditional evaluates to true the parsing of the makefile continues
946: as before.
947: If it evaluates to false, the following lines are skipped.
948: In both cases this continues until a
949: .Ql Ic .else
950: or
951: .Ql Ic .endif
952: is found.
1.16 christos 953: .Pp
1.6 cgd 954: For loops are typically used to apply a set of rules to a list of files.
955: The syntax of a for loop is:
956: .Bl -tag -width Ds
957: .It Xo
958: .Ic \&.for
1.39 christos 959: .Ar variable
960: .Op Ar variable ...
1.16 christos 961: .Ic in
1.6 cgd 962: .Ar expression
963: .Xc
964: .It Xo
965: <make-rules>
966: .Xc
967: .It Xo
968: .Ic \&.endfor
969: .Xc
970: .El
971: After the for
1.16 christos 972: .Ic expression
1.39 christos 973: is evaluated, it is split into words. On each iteration of the loop,
974: one word is taken and assigned to each
975: .Ic variable ,
976: in order, and these
977: .Ic variables
978: are substituted into the
1.16 christos 979: .Ic make-rules
1.6 cgd 980: inside the body of the for loop.
1.39 christos 981: The number of words must come out even; that is, if there are three
982: iteration variables, the number of words provided must be a multiple
983: of three.
1.1 cgd 984: .Sh COMMENTS
985: Comments begin with a hash
986: .Pq Ql \&#
987: character, anywhere but in a shell
988: command line, and continue to the end of the line.
989: .Sh SPECIAL SOURCES
990: .Bl -tag -width Ic .IGNORE
991: .It Ic .IGNORE
992: Ignore any errors from the commands associated with this target, exactly
993: as if they all were preceded by a dash
994: .Pq Ql \- .
1.18 christos 995: .It Ic .MADE
996: Mark all sources of this target as being up-to-date.
1.1 cgd 997: .It Ic .MAKE
998: Execute the commands associated with this target even if the
999: .Fl n
1000: or
1001: .Fl t
1002: options were specified.
1003: Normally used to mark recursive
1.25 lukem 1004: .Nm "" Ns 's .
1.1 cgd 1005: .It Ic .NOTMAIN
1006: Normally
1.25 lukem 1007: .Nm
1.1 cgd 1008: selects the first target it encounters as the default target to be built
1009: if no target was specified.
1010: This source prevents this target from being selected.
1011: .It Ic .OPTIONAL
1012: If a target is marked with this attribute and
1.25 lukem 1013: .Nm
1.1 cgd 1014: can't figure out how to create it, it will ignore this fact and assume
1015: the file isn't needed or already exists.
1016: .It Ic .PRECIOUS
1017: When
1.25 lukem 1018: .Nm
1.1 cgd 1019: is interrupted, it removes any partially made targets.
1020: This source prevents the target from being removed.
1021: .It Ic .SILENT
1022: Do not echo any of the commands associated with this target, exactly
1023: as if they all were preceded by an at sign
1024: .Pq Ql @ .
1025: .It Ic .USE
1026: Turn the target into
1.25 lukem 1027: .Nm "" Ns 's
1.1 cgd 1028: version of a macro.
1029: When the target is used as a source for another target, the other target
1030: acquires the commands, sources, and attributes (except for
1031: .Ic .USE )
1032: of the
1033: source.
1034: If the target already has commands, the
1035: .Ic .USE
1036: target's commands are appended
1037: to them.
1.12 christos 1038: .It Ic .WAIT
1039: If special
1040: .Ic .WAIT
1041: source is appears in a dependency line, the sources that precede it are
1042: made before the sources that succeed it in the line. Loops are not being
1043: detected and targets that form loops will be silently ignored.
1.1 cgd 1044: .El
1045: .Sh "SPECIAL TARGETS"
1046: Special targets may not be included with other targets, i.e. they must be
1047: the only target specified.
1048: .Bl -tag -width Ic .BEGIN
1049: .It Ic .BEGIN
1050: Any command lines attached to this target are executed before anything
1051: else is done.
1052: .It Ic .DEFAULT
1053: This is sort of a
1054: .Ic .USE
1055: rule for any target (that was used only as a
1056: source) that
1.25 lukem 1057: .Nm
1.1 cgd 1058: can't figure out any other way to create.
1059: Only the shell script is used.
1060: The
1061: .Ic .IMPSRC
1062: variable of a target that inherits
1063: .Ic .DEFAULT Ns 's
1064: commands is set
1065: to the target's own name.
1066: .It Ic .END
1067: Any command lines attached to this target are executed after everything
1068: else is done.
1069: .It Ic .IGNORE
1070: Mark each of the sources with the
1071: .Ic .IGNORE
1072: attribute.
1073: If no sources are specified, this is the equivalent of specifying the
1074: .Fl i
1075: option.
1076: .It Ic .INTERRUPT
1077: If
1.25 lukem 1078: .Nm
1.1 cgd 1079: is interrupted, the commands for this target will be executed.
1080: .It Ic .MAIN
1081: If no target is specified when
1.25 lukem 1082: .Nm
1.1 cgd 1083: is invoked, this target will be built.
1084: .It Ic .MAKEFLAGS
1085: This target provides a way to specify flags for
1.25 lukem 1086: .Nm
1.1 cgd 1087: when the makefile is used.
1088: The flags are as if typed to the shell, though the
1089: .Fl f
1090: option will have
1091: no effect.
1.12 christos 1092: .\" XXX: NOT YET!!!!
1093: .\" .It Ic .NOTPARALLEL
1094: .\" The named targets are executed in non parallel mode. If no targets are
1095: .\" specified, then all targets are executed in non parallel mode.
1.20 gwr 1096: .It Ic .NOPATH
1097: Apply the
1098: .Ic .NOPATH
1.21 mycroft 1099: attribute to any specified sources. Targets with this attribute are not
1100: searched for in the directories specified by
1101: .Ic .PATH .
1.12 christos 1102: .It Ic .NOTPARALLEL
1103: Disable parallel mode.
1104: .It Ic .NO_PARALLEL
1105: Same as above, for compatibility with other pmake variants.
1106: .It Ic .ORDER
1107: The named targets are made in sequence.
1108: .\" XXX: NOT YET!!!!
1109: .\" .It Ic .PARALLEL
1110: .\" The named targets are executed in parallel mode. If no targets are
1111: .\" specified, then all targets are executed in parallel mode.
1.1 cgd 1112: .It Ic .PATH
1113: The sources are directories which are to be searched for files not
1114: found in the current directory.
1115: If no sources are specified, any previously specified directories are
1116: deleted.
1.34 thorpej 1117: If the source is the special
1118: .Ic .DOTLAST
1119: target, then the current working
1.33 thorpej 1120: directory is searched last.
1.14 christos 1121: .It Ic .PHONY
1122: Apply the
1123: .Ic .PHONY
1.19 mycroft 1124: attribute to any specified sources. Targets with this attribute do not
1125: correspond to actual files; they are always considered to be out of date,
1126: and will not be created with the
1127: .Fl t
1128: option.
1.1 cgd 1129: .It Ic .PRECIOUS
1130: Apply the
1131: .Ic .PRECIOUS
1132: attribute to any specified sources.
1133: If no sources are specified, the
1134: .Ic .PRECIOUS
1135: attribute is applied to every
1136: target in the file.
1137: .It Ic .SILENT
1138: Apply the
1139: .Ic .SILENT
1140: attribute to any specified sources.
1141: If no sources are specified, the
1142: .Ic .SILENT
1143: attribute is applied to every
1144: command in the file.
1145: .It Ic .SUFFIXES
1146: Each source specifies a suffix to
1.25 lukem 1147: .Nm "" .
1.38 sjg 1148: If no sources are specified, any previous specified suffixes are deleted.
1.31 ross 1149: .El
1.1 cgd 1150: .Sh ENVIRONMENT
1.25 lukem 1151: .Nm
1.1 cgd 1152: utilizes the following environment variables, if they exist:
1.16 christos 1153: .Ev MACHINE ,
1.26 hubertf 1154: .Ev MACHINE_ARCH ,
1.1 cgd 1155: .Ev MAKE ,
1.16 christos 1156: .Ev MAKEFLAGS ,
1157: .Ev MAKEOBJDIR ,
1.38 sjg 1158: .Ev MAKEOBJDIRPREFIX ,
1.1 cgd 1159: and
1.16 christos 1160: .Ev PWD .
1.38 sjg 1161:
1162: If
1163: .Ev MAKEOBJDIRPREFIX
1164: is set, then
1165: .Nm
1166: will
1167: .Xr chdir 2
1168: to ${MAKEOBJDIRPREFIX}${.CURDIR} if it exists.
1169: Otherwise if
1170: .Ev MAKEOBJDIR
1171: and the named directory exists
1172: .Nm
1173: will
1174: .Xr chdir 2
1175: to it.
1176: These actions are taken before any makefiles are read which is why they
1177: need to be set in the environment.
1.1 cgd 1178: .Sh FILES
1179: .Bl -tag -width /usr/share/mk -compact
1180: .It .depend
1181: list of dependencies
1182: .It Makefile
1183: list of dependencies
1184: .It makefile
1185: list of dependencies
1186: .It sys.mk
1187: system makefile
1188: .It /usr/share/mk
1189: system makefile directory
1190: .El
1191: .Sh SEE ALSO
1192: .Xr mkdep 1
1193: .Sh HISTORY
1194: A
1.25 lukem 1195: .Nm
1.1 cgd 1196: command appeared in
1197: .At v7 .
CVSweb <webmaster@jp.NetBSD.org>