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