Annotation of src/usr.bin/make/make.1, Revision 1.19
1.19 ! aaron 1: .\" $OpenBSD: make.1,v 1.18 1999/05/16 21:53:31 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
1.19 ! aaron 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.19 ! aaron 55: .Op Ar variable Ns No = Ns Ar value
1.1 deraadt 56: .Op Ar target ...
57: .Sh DESCRIPTION
1.19 ! aaron 58: .Nm
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.
1.18 espie 76: For a more thorough introduction to
1.19 ! aaron 77: .Nm
1.1 deraadt 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
1.19 ! aaron 95: .Nm
1.1 deraadt 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
1.19 ! aaron 140: .Ql \- ,
1.1 deraadt 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
1.19 ! aaron 151: .Ql \-
1.1 deraadt 152: before each command line in the makefile.
153: .It Fl j Ar max_jobs
154: Specify the maximum number of jobs that
1.19 ! aaron 155: .Nm
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
1.19 ! aaron 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
1.15 espie 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.
1.19 ! aaron 227: This creates a relationship where the targets
! 228: .Dq depend
! 229: on the sources
1.1 deraadt 230: and are usually created from them.
231: The exact relationship between the target and the source is determined
232: by the operator that separates them.
233: The three operators are as follows:
234: .Bl -tag -width flag
235: .It Ic \&:
236: A target is considered out-of-date if its modification time is less than
237: those of any of its sources.
238: Sources for a target accumulate over dependency lines when this operator
239: is used.
240: The target is removed if
1.19 ! aaron 241: .Nm
1.1 deraadt 242: is interrupted.
243: .It Ic \&!
244: Targets are always re-created, but not until all sources have been
245: examined and re-created as necessary.
246: Sources for a target accumulate over dependency lines when this operator
247: is used.
248: The target is removed if
1.19 ! aaron 249: .Nm
1.1 deraadt 250: is interrupted.
251: .It Ic \&::
252: If no sources are specified, the target is always re-created.
253: Otherwise, a target is considered out-of-date if any of its sources has
254: been modified more recently than the target.
255: Sources for a target do not accumulate over dependency lines when this
256: operator is used.
257: The target will not be removed if
1.19 ! aaron 258: .Nm
1.1 deraadt 259: is interrupted.
260: .El
261: .Pp
1.15 espie 262: Targets and sources may contain the shell wildcard expressions
1.1 deraadt 263: .Ql ? ,
264: .Ql * ,
265: .Ql []
266: and
267: .Ql {} .
1.15 espie 268: The expressions
1.1 deraadt 269: .Ql ? ,
270: .Ql *
271: and
272: .Ql []
273: may only be used as part of the final
274: component of the target or source, and must be used to describe existing
275: files.
1.15 espie 276: The expression
1.1 deraadt 277: .Ql {}
278: need not necessarily be used to describe existing files.
279: Expansion is in directory order, not alphabetically as done in the shell.
280: .Sh SHELL COMMANDS
281: Each target may have associated with it a series of shell commands, normally
282: used to create the target.
283: Each of the commands in this script
284: .Em must
285: be preceded by a tab.
286: While any target may appear on a dependency line, only one of these
287: dependencies may be followed by a creation script, unless the
288: .Ql Ic ::
289: operator is used.
290: .Pp
291: If the first or first two characters of the command line are
292: .Ql Ic @
293: and/or
294: .Ql Ic \- ,
295: the command is treated specially.
296: A
297: .Ql Ic @
298: causes the command not to be echoed before it is executed.
299: A
300: .Ql Ic \-
301: causes any non-zero exit status of the command line to be ignored.
302: .Sh VARIABLE ASSIGNMENTS
1.14 aaron 303: Variables in
1.19 ! aaron 304: .Nm
1.14 aaron 305: are much like variables in the shell, and, by tradition,
1.1 deraadt 306: consist of all upper-case letters.
307: The five operators that can be used to assign values to variables are as
308: follows:
309: .Bl -tag -width Ds
310: .It Ic \&=
311: Assign the value to the variable.
312: Any previous value is overridden.
313: .It Ic \&+=
314: Append the value to the current value of the variable.
315: .It Ic \&?=
316: Assign the value to the variable if it is not already defined.
317: .It Ic \&:=
318: Assign with expansion, i.e. expand the value before assigning it
319: to the variable.
320: Normally, expansion is not done until the variable is referenced.
321: .It Ic \&!=
322: Expand the value and pass it to the shell for execution and assign
323: the result to the variable.
324: Any newlines in the result are replaced with spaces.
325: .El
326: .Pp
1.14 aaron 327: Any whitespace before the assigned
1.1 deraadt 328: .Ar value
329: is removed; if the value is being appended, a single space is inserted
330: between the previous contents of the variable and the appended value.
331: .Pp
332: Variables are expanded by surrounding the variable name with either
333: curly braces
334: .Pq Ql {}
335: or parentheses
336: .Pq Ql ()
337: and preceding it with
338: a dollar sign
339: .Pq Ql \&$ .
340: If the variable name contains only a single letter, the surrounding
341: braces or parentheses are not required.
342: This shorter form is not recommended.
343: .Pp
344: Variable substitution occurs at two distinct times, depending on where
345: the variable is being used.
346: Variables in dependency lines are expanded as the line is read.
347: Variables in shell commands are expanded when the shell command is
348: executed.
349: .Pp
350: The four different classes of variables (in order of increasing precedence)
351: are:
352: .Bl -tag -width Ds
353: .It Environment variables
354: Variables defined as part of
355: .Nm make Ns 's
356: environment.
357: .It Global variables
358: Variables defined in the makefile or in included makefiles.
359: .It Command line variables
360: Variables defined as part of the command line.
361: .It Local variables
362: Variables that are defined specific to a certain target.
363: The seven local variables are as follows:
364: .Bl -tag -width ".ARCHIVE"
365: .It Va .ALLSRC
366: The list of all sources for this target; also known as
367: .Ql Va \&> .
368: .It Va .ARCHIVE
1.15 espie 369: The name of the archive file; also known as
370: .Ql Va \&! .
1.1 deraadt 371: .It Va .IMPSRC
372: The name/path of the source from which the target is to be transformed
1.19 ! aaron 373: (the
! 374: .Dq implied
! 375: source); also known as
1.1 deraadt 376: .Ql Va \&< .
377: .It Va .MEMBER
1.15 espie 378: The name of the archive member; also known as
379: .Ql Va \&% .
1.1 deraadt 380: .It Va .OODATE
381: The list of sources for this target that were deemed out-of-date; also
382: known as
383: .Ql Va \&? .
384: .It Va .PREFIX
385: The file prefix of the file, containing only the file portion, no suffix
386: or preceding directory components; also known as
387: .Ql Va * .
388: .It Va .TARGET
389: The name of the target; also known as
390: .Ql Va @ .
391: .El
392: .Pp
393: The shorter forms
394: .Ql Va @ ,
1.15 espie 395: .Ql Va ! ,
396: .Ql Va \&< ,
397: .Ql Va \&% ,
1.1 deraadt 398: .Ql Va ? ,
1.14 aaron 399: .Ql Va \&> ,
1.1 deraadt 400: and
401: .Ql Va *
402: are permitted for backward
403: compatibility with historical makefiles and are not recommended.
404: The six variables
405: .Ql Va "@F" ,
406: .Ql Va "@D" ,
407: .Ql Va "<F" ,
408: .Ql Va "<D" ,
1.14 aaron 409: .Ql Va "*F" ,
1.1 deraadt 410: and
411: .Ql Va "*D"
412: are
413: permitted for compatibility with
414: .At V
415: makefiles and are not recommended.
416: .Pp
417: Four of the local variables may be used in sources on dependency lines
418: because they expand to the proper value for each target on the line.
419: These variables are
420: .Ql Va .TARGET ,
421: .Ql Va .PREFIX ,
422: .Ql Va .ARCHIVE ,
423: and
424: .Ql Va .MEMBER .
1.15 espie 425: .El
1.1 deraadt 426: .Pp
427: In addition,
1.19 ! aaron 428: .Nm
! 429: sets or knows about the following internal variables, or environment
1.15 espie 430: variables:
1.1 deraadt 431: .Bl -tag -width MAKEFLAGS
432: .It Va \&$
433: A single dollar sign
434: .Ql \&$ ,
435: i.e.
436: .Ql \&$$
437: expands to a single dollar
438: sign.
439: .It Va .MAKE
440: The name that
1.19 ! aaron 441: .Nm
1.1 deraadt 442: was executed with
1.14 aaron 443: .Pq Va argv Ns Op 0 .
1.1 deraadt 444: .It Va .CURDIR
445: A path to the directory where
1.19 ! aaron 446: .Nm
1.1 deraadt 447: was executed.
448: .It Va .OBJDIR
449: A path to the directory where the targets are built.
1.8 deraadt 450: At startup,
1.19 ! aaron 451: .Nm
1.8 deraadt 452: searches for an alternate directory to place target files -- it
453: will attempt to change into this special directory.
1.19 ! aaron 454: First, if
! 455: .Ev MAKEOBJDIRPREFIX
! 456: is defined,
! 457: .Nm
1.18 espie 458: prepends its contents to the current directory name and tries for
459: the resulting directory. If that fails,
1.19 ! aaron 460: .Nm
1.18 espie 461: remains in the current directory.
1.19 ! aaron 462: If
1.15 espie 463: .Ev MAKEOBJDIRPREFIX
1.18 espie 464: is not defined,
1.19 ! aaron 465: .Nm
1.18 espie 466: checks
1.19 ! aaron 467: .Ev MAKEOBJDIR
! 468: and tries to change into that directory. Should that fail,
! 469: .Nm
! 470: remains in the current directory. If
1.18 espie 471: .Ev MAKEOBJDIR
472: is not defined, it tries to change into the directory named
473: .Pa obj.${MACHINE}
1.19 ! aaron 474: (see
! 475: .Va MACHINE
! 476: variable). If it still has found no special directory,
! 477: .Nm
1.18 espie 478: next tries the directory named
479: .Pa obj .
480: If this fails,
1.19 ! aaron 481: .Nm
! 482: tries to prepend
! 483: .Pa /usr/obj
! 484: to the current directory name.
1.18 espie 485: Finally, if none of these directories are available
1.19 ! aaron 486: .Nm
1.8 deraadt 487: will settle for and use the current directory.
1.15 espie 488: .It Va .MAKEFLAGS
1.1 deraadt 489: The environment variable
1.14 aaron 490: .Ev MAKEFLAGS
1.1 deraadt 491: may contain anything that
492: may be specified on
493: .Nm make Ns 's
1.19 ! aaron 494: command line. Its contents are stored in
1.15 espie 495: .Nm make Ns 's
1.19 ! aaron 496: .Va .MAKEFLAGS
1.15 espie 497: variable.
1.1 deraadt 498: Anything specified on
499: .Nm make Ns 's
500: command line is appended to the
1.15 espie 501: .Va .MAKEFLAGS
502: variable which is then
1.19 ! aaron 503: entered into the environment as
1.14 aaron 504: .Ev MAKEFLAGS
1.15 espie 505: for all programs which
1.19 ! aaron 506: .Nm
1.1 deraadt 507: executes.
1.15 espie 508: .It Va MFLAGS
1.19 ! aaron 509: A shorter synonym for
1.15 espie 510: .Va .MAKEFLAGS .
1.9 millert 511: .It Ev PWD
512: Alternate path to the current directory.
1.19 ! aaron 513: .Nm
1.9 millert 514: normally sets
515: .Ql Va .CURDIR
516: to the canonical path given by
517: .Xr getcwd 2 .
518: However, if the environment variable
1.14 aaron 519: .Ev PWD
1.9 millert 520: is set and gives a path to the current directory, then
1.19 ! aaron 521: .Nm
1.9 millert 522: sets
523: .Ql Va .CURDIR
524: to the value of
1.14 aaron 525: .Ev PWD
1.9 millert 526: instead.
1.14 aaron 527: .Ev PWD
1.15 espie 528: is always set to the value of
1.9 millert 529: .Ql Va .OBJDIR
530: for all programs which
1.19 ! aaron 531: .Nm
1.9 millert 532: executes.
1.15 espie 533: .It Va .TARGETS
1.19 ! aaron 534: List of targets
! 535: .Nm
1.18 espie 536: is currently building.
1.15 espie 537: .It Va .INCLUDES
1.19 ! aaron 538: See
1.18 espie 539: .Ic .INCLUDES
540: special target
1.15 espie 541: .It Va .LIBS
1.19 ! aaron 542: See
1.18 espie 543: .Ic .LIBS
544: special target
1.15 espie 545: .It Va MACHINE
1.19 ! aaron 546: Name of the machine architecture
! 547: .Nm
1.18 espie 548: is running on, obtained from the
549: .Ev MACHINE
1.19 ! aaron 550: environment variable, or through
1.18 espie 551: .Xr uname 2
552: if not defined.
1.15 espie 553: .It Va MACHINE_ARCH
1.18 espie 554: Name of the machine architecture
1.19 ! aaron 555: .Nm
1.18 espie 556: was compiled for, obtained from the
1.19 ! aaron 557: .Ev MACHINE_ARCH
1.18 espie 558: environment variable, or defined at compilation time.
1.1 deraadt 559: .El
560: .Pp
561: Variable expansion may be modified to select or modify each word of the
1.19 ! aaron 562: variable (where a
! 563: .Dq word
! 564: is whitespace delimited sequence of characters).
1.1 deraadt 565: The general format of a variable expansion is as follows:
566: .Pp
567: .Dl {variable[:modifier[:...]]}
568: .Pp
569: Each modifier begins with a colon and one of the following
570: special characters.
571: The colon may be escaped with a backslash
572: .Pq Ql \e .
573: .Bl -tag -width Cm E\&
574: .It Cm E
575: Replaces each word in the variable with its suffix.
576: .It Cm H
577: Replaces each word in the variable with everything but the last component.
578: .It Cm M Ns Ar pattern
579: Select only those words that match the rest of the modifier.
580: The standard shell wildcard characters
581: .Pf ( Ql * ,
582: .Ql ? ,
583: and
584: .Ql Op )
585: may
586: be used.
587: The wildcard characters may be escaped with a backslash
588: .Pq Ql \e .
589: .It Cm N Ns Ar pattern
590: This is identical to
1.14 aaron 591: .Cm M ,
1.1 deraadt 592: but selects all words which do not match
593: the rest of the modifier.
1.10 millert 594: .It Cm Q
595: Quotes every shell meta-character in the variable, so that it can be passed
596: safely through recursive invocations of
1.14 aaron 597: .Nm make .
1.1 deraadt 598: .It Cm R
599: Replaces each word in the variable with everything but its suffix.
600: .Sm off
1.10 millert 601: .It Cm S No \&/ Ar old_string Xo
602: .No \&/ Ar new_string
603: .No \&/ Op Cm 1g
1.1 deraadt 604: .Xc
605: .Sm on
606: Modify the first occurrence of
1.10 millert 607: .Ar old_string
608: in the variable's value, replacing it with
609: .Ar new_string .
1.1 deraadt 610: If a
611: .Ql g
612: is appended to the last slash of the pattern, all occurrences
613: in each word are replaced.
1.10 millert 614: If a
615: .Ql 1
616: is appended to the last slash of the pattern, only the first word
617: is affected.
1.1 deraadt 618: If
1.10 millert 619: .Ar old_string
620: begins with a caret
1.1 deraadt 621: .Pq Ql ^ ,
1.10 millert 622: .Ar old_string
1.1 deraadt 623: is anchored at the beginning of each word.
624: If
1.10 millert 625: .Ar old_string
1.1 deraadt 626: ends with a dollar sign
627: .Pq Ql \&$ ,
628: it is anchored at the end of each word.
629: Inside
630: .Ar new_string ,
631: an ampersand
632: .Pq Ql &
633: is replaced by
1.10 millert 634: .Ar old_string
635: (without any
636: .Ql ^
637: or
638: .Ql \&$ ) .
1.1 deraadt 639: Any character may be used as a delimiter for the parts of the modifier
640: string.
641: The anchoring, ampersand and delimiter characters may be escaped with a
642: backslash
643: .Pq Ql \e .
644: .Pp
645: Variable expansion occurs in the normal fashion inside both
646: .Ar old_string
647: and
648: .Ar new_string
649: with the single exception that a backslash is used to prevent the expansion
650: of a dollar sign
1.10 millert 651: .Pq Ql \&$ ,
1.1 deraadt 652: not a preceding dollar sign as is usual.
1.10 millert 653: .Sm off
654: .It Cm C No \&/ Ar pattern Xo
655: .No \&/ Ar replacement
656: .No \&/ Op Cm 1g
657: .Xc
658: .Sm on
659: The
660: .Cm C
661: modifier is just like the
662: .Cm S
1.13 deraadt 663: modifier except that the old and new strings, instead of being
1.10 millert 664: simple strings, are a regular expression (see
665: .Xr regex 3 )
666: and an
667: .Xr ed 1 Ns \-style
668: replacement string. Normally, the first occurrence of the pattern in
669: each word of the value is changed. The
670: .Ql 1
671: modifier causes the substitution to apply to at most one word; the
672: .Ql g
673: modifier causes the substitution to apply to as many instances of the
674: search pattern as occur in the word or words it is found in. Note that
675: .Ql 1
676: and
677: .Ql g
678: are orthogonal; the former specifies whether multiple words are
679: potentially affected, the latter whether multiple substitutions can
680: potentially occur within each affected word.
1.1 deraadt 681: .It Cm T
682: Replaces each word in the variable with its last component.
683: .It Ar old_string=new_string
684: This is the
685: .At V
686: style variable substitution.
687: It must be the last modifier specified.
1.9 millert 688: If
1.1 deraadt 689: .Ar old_string
690: or
691: .Ar new_string
692: do not contain the pattern matching character
693: .Ar %
1.9 millert 694: then it is assumed that they are
1.1 deraadt 695: anchored at the end of each word, so only suffixes or entire
1.9 millert 696: words may be replaced. Otherwise
1.1 deraadt 697: .Ar %
1.9 millert 698: is the substring of
699: .Ar old_string
1.1 deraadt 700: to be replaced in
701: .Ar new_string
702: .El
703: .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1.9 millert 704: Makefile inclusion, conditional structures and for loops reminiscent
1.1 deraadt 705: of the C programming language are provided in
706: .Nm make .
707: All such structures are identified by a line beginning with a single
708: dot
709: .Pq Ql \&.
710: character.
711: Files are included with either
712: .Ql .include <file>
713: or
714: .Ql .include \*qfile\*q .
715: Variables between the angle brackets or double quotes are expanded
716: to form the file name.
717: If angle brackets are used, the included makefile is expected to be in
718: the system makefile directory.
719: If double quotes are used, the including makefile's directory and any
720: directories specified using the
721: .Fl I
722: option are searched before the system
723: makefile directory.
724: .Pp
725: Conditional expressions are also preceded by a single dot as the first
726: character of a line.
727: The possible conditionals are as follows:
728: .Bl -tag -width Ds
729: .It Ic .undef Ar variable
730: Un-define the specified global variable.
731: Only global variables may be un-defined.
732: .It Xo
733: .Ic \&.if
734: .Oo \&! Oc Ns Ar expression
735: .Op Ar operator expression ...
736: .Xc
737: Test the value of an expression.
738: .It Xo
739: .Ic .ifdef
740: .Oo \&! Oc Ns Ar variable
741: .Op Ar operator variable ...
742: .Xc
743: Test the value of a variable.
744: .It Xo
745: .Ic .ifndef
746: .Oo \&! Oc Ns Ar variable
747: .Op Ar operator variable ...
748: .Xc
749: Test the value of a variable.
750: .It Xo
751: .Ic .ifmake
752: .Oo \&! Oc Ns Ar target
753: .Op Ar operator target ...
754: .Xc
755: Test the target being built.
756: .It Xo
757: .Ic .ifnmake
758: .Oo \&! Oc Ar target
759: .Op Ar operator target ...
760: .Xc
761: Test the target being built.
762: .It Ic .else
763: Reverse the sense of the last conditional.
764: .It Xo
765: .Ic .elif
766: .Oo \&! Oc Ar expression
767: .Op Ar operator expression ...
768: .Xc
769: A combination of
770: .Ql Ic .else
771: followed by
772: .Ql Ic .if .
773: .It Xo
774: .Ic .elifdef
775: .Oo \&! Oc Ns Ar variable
776: .Op Ar operator variable ...
777: .Xc
778: A combination of
779: .Ql Ic .else
780: followed by
781: .Ql Ic .ifdef .
782: .It Xo
783: .Ic .elifndef
784: .Oo \&! Oc Ns Ar variable
785: .Op Ar operator variable ...
786: .Xc
787: A combination of
788: .Ql Ic .else
789: followed by
790: .Ql Ic .ifndef .
791: .It Xo
792: .Ic .elifmake
793: .Oo \&! Oc Ns Ar target
794: .Op Ar operator target ...
795: .Xc
796: A combination of
797: .Ql Ic .else
798: followed by
799: .Ql Ic .ifmake .
800: .It Xo
801: .Ic .elifnmake
802: .Oo \&! Oc Ns Ar target
803: .Op Ar operator target ...
804: .Xc
805: A combination of
806: .Ql Ic .else
807: followed by
808: .Ql Ic .ifnmake .
809: .It Ic .endif
810: End the body of the conditional.
811: .El
812: .Pp
813: The
814: .Ar operator
815: may be any one of the following:
816: .Bl -tag -width "Cm XX"
817: .It Cm \&|\&|
818: logical OR
819: .It Cm \&&&
820: Logical
821: .Tn AND ;
822: of higher precedence than
823: .Dq .
824: .El
825: .Pp
826: As in C,
1.19 ! aaron 827: .Nm
1.1 deraadt 828: will only evaluate a conditional as far as is necessary to determine
829: its value.
1.9 millert 830: Parentheses may be used to change the order of evaluation.
1.1 deraadt 831: The boolean operator
832: .Ql Ic \&!
833: may be used to logically negate an entire
834: conditional.
835: It is of higher precedence than
836: .Ql Ic \&&& .
837: .Pp
838: The value of
839: .Ar expression
840: may be any of the following:
841: .Bl -tag -width Ic defined
842: .It Ic defined
843: Takes a variable name as an argument and evaluates to true if the variable
844: has been defined.
845: .It Ic make
846: Takes a target name as an argument and evaluates to true if the target
847: was specified as part of
848: .Nm make Ns 's
849: command line or was declared the default target (either implicitly or
850: explicitly, see
851: .Va .MAIN )
852: before the line containing the conditional.
853: .It Ic empty
854: Takes a variable, with possible modifiers, and evaluates to true if
855: the expansion of the variable would result in an empty string.
856: .It Ic exists
857: Takes a file name as an argument and evaluates to true if the file exists.
858: The file is searched for on the system search path (see
859: .Va .PATH ) .
860: .It Ic target
861: Takes a target name as an argument and evaluates to true if the target
862: has been defined.
863: .El
864: .Pp
1.14 aaron 865: .Ar expression
1.1 deraadt 866: may also be an arithmetic or string comparison. Variable expansion is
867: performed on both sides of the comparison, after which the integral
868: values are compared. A value is interpreted as hexadecimal if it is
869: preceded by 0x, otherwise it is decimal; octal numbers are not supported.
870: The standard C relational operators are all supported. If after
871: variable expansion, either the left or right hand side of a
872: .Ql Ic ==
873: or
874: .Ql Ic "!="
875: operator is not an integral value, then
876: string comparison is performed between the expanded
877: variables.
878: If no relational operator is given, it is assumed that the expanded
879: variable is being compared against 0.
880: .Pp
881: When
1.19 ! aaron 882: .Nm
1.14 aaron 883: is evaluating one of these conditional expressions, and it encounters
1.19 ! aaron 884: a word it doesn't recognize, either the
! 885: .Dq make
! 886: or
! 887: .Dq defined
1.1 deraadt 888: expression is applied to it, depending on the form of the conditional.
889: If the form is
890: .Ql Ic .ifdef
891: or
892: .Ql Ic .ifndef ,
1.19 ! aaron 893: the
! 894: .Dq defined
! 895: expression is applied.
1.1 deraadt 896: Similarly, if the form is
897: .Ql Ic .ifmake
898: or
1.14 aaron 899: .Ql Ic .ifnmake ,
1.19 ! aaron 900: the
! 901: .Dq make
1.1 deraadt 902: expression is applied.
903: .Pp
904: If the conditional evaluates to true the parsing of the makefile continues
905: as before.
906: If it evaluates to false, the following lines are skipped.
907: In both cases this continues until a
908: .Ql Ic .else
909: or
910: .Ql Ic .endif
911: is found.
1.9 millert 912: .Pp
1.1 deraadt 913: For loops are typically used to apply a set of rules to a list of files.
914: The syntax of a for loop is:
915: .Bl -tag -width Ds
916: .It Xo
917: .Ic \&.for
1.9 millert 918: .Ar variable
919: .Ic in
1.1 deraadt 920: .Ar expression
921: .Xc
922: .It Xo
923: <make-rules>
924: .Xc
925: .It Xo
926: .Ic \&.endfor
927: .Xc
928: .El
929: After the for
1.14 aaron 930: .Ar expression
1.9 millert 931: is evaluated, it is split into words. The
1.1 deraadt 932: iteration
1.14 aaron 933: .Ar variable
1.9 millert 934: is successively set to each word, and substituted in the
935: .Ic make-rules
1.1 deraadt 936: inside the body of the for loop.
937: .Sh COMMENTS
938: Comments begin with a hash
939: .Pq Ql \&#
940: character, anywhere but in a shell
941: command line, and continue to the end of the line.
942: .Sh SPECIAL SOURCES
943: .Bl -tag -width Ic .IGNORE
944: .It Ic .IGNORE
945: Ignore any errors from the commands associated with this target, exactly
946: as if they all were preceded by a dash
947: .Pq Ql \- .
1.10 millert 948: .It Ic .MADE
1.19 ! aaron 949: Mark all sources of this target as being up-to-date.
1.1 deraadt 950: .It Ic .MAKE
951: Execute the commands associated with this target even if the
952: .Fl n
953: or
954: .Fl t
955: options were specified.
956: Normally used to mark recursive
957: .Nm make Ns 's .
958: .It Ic .NOTMAIN
959: Normally
1.19 ! aaron 960: .Nm
1.1 deraadt 961: selects the first target it encounters as the default target to be built
962: if no target was specified.
963: This source prevents this target from being selected.
964: .It Ic .OPTIONAL
965: If a target is marked with this attribute and
1.19 ! aaron 966: .Nm
1.1 deraadt 967: can't figure out how to create it, it will ignore this fact and assume
968: the file isn't needed or already exists.
969: .It Ic .PRECIOUS
970: When
1.19 ! aaron 971: .Nm
1.1 deraadt 972: is interrupted, it removes any partially made targets.
973: This source prevents the target from being removed.
974: .It Ic .SILENT
975: Do not echo any of the commands associated with this target, exactly
976: as if they all were preceded by an at sign
977: .Pq Ql @ .
978: .It Ic .USE
979: Turn the target into
1.14 aaron 980: .Nm make Ns 's
1.1 deraadt 981: version of a macro.
982: When the target is used as a source for another target, the other target
983: acquires the commands, sources, and attributes (except for
984: .Ic .USE )
985: of the
986: source.
987: If the target already has commands, the
988: .Ic .USE
989: target's commands are appended
990: to them.
1.4 deraadt 991: .It Ic .WAIT
992: If special
993: .Ic .WAIT
994: source is appears in a dependency line, the sources that precede it are
995: made before the sources that succeed it in the line. Loops are not being
996: detected and targets that form loops will be silently ignored.
1.1 deraadt 997: .El
998: .Sh "SPECIAL TARGETS"
999: Special targets may not be included with other targets, i.e. they must be
1000: the only target specified.
1001: .Bl -tag -width Ic .BEGIN
1002: .It Ic .BEGIN
1003: Any command lines attached to this target are executed before anything
1004: else is done.
1005: .It Ic .DEFAULT
1006: This is sort of a
1007: .Ic .USE
1008: rule for any target (that was used only as a
1009: source) that
1.19 ! aaron 1010: .Nm
1.1 deraadt 1011: can't figure out any other way to create.
1012: Only the shell script is used.
1013: The
1014: .Ic .IMPSRC
1015: variable of a target that inherits
1016: .Ic .DEFAULT Ns 's
1017: commands is set
1018: to the target's own name.
1019: .It Ic .END
1020: Any command lines attached to this target are executed after everything
1021: else is done.
1022: .It Ic .IGNORE
1023: Mark each of the sources with the
1024: .Ic .IGNORE
1025: attribute.
1026: If no sources are specified, this is the equivalent of specifying the
1027: .Fl i
1028: option.
1.18 espie 1029: .It Ic .INCLUDES
1030: A list of suffixes that indicate files that can be included in a source
1031: file. The suffix must have already been declared with
1032: .Ic .SUFFIXES ,
1033: any suffix so declared will have the directories on its search path (see
1034: .Ic .PATH )
1.19 ! aaron 1035: placed in the
1.18 espie 1036: .Va .INCLUDES
1.19 ! aaron 1037: special variable, each preceded by a
! 1038: .Fl I
1.18 espie 1039: flag.
1.1 deraadt 1040: .It Ic .INTERRUPT
1041: If
1.19 ! aaron 1042: .Nm
1.1 deraadt 1043: is interrupted, the commands for this target will be executed.
1.18 espie 1044: .It Ic .LIBS
1.19 ! aaron 1045: This does for libraries what
! 1046: .Ic .INCLUDES
1.18 espie 1047: does for include files, except that the flag used is
1048: .Fl L .
1.1 deraadt 1049: .It Ic .MAIN
1050: If no target is specified when
1.19 ! aaron 1051: .Nm
1.16 espie 1052: is invoked, this target will be built. This is always set, either
1.19 ! aaron 1053: explicitly, or implicitly when
! 1054: .Nm
1.16 espie 1055: selects the default target, to give the user a way to refer to the default
1056: target on the command line.
1.1 deraadt 1057: .It Ic .MAKEFLAGS
1058: This target provides a way to specify flags for
1.19 ! aaron 1059: .Nm
1.1 deraadt 1060: when the makefile is used.
1061: The flags are as if typed to the shell, though the
1062: .Fl f
1063: option will have
1064: no effect.
1.4 deraadt 1065: .\" XXX: NOT YET!!!!
1066: .\" .It Ic .NOTPARALLEL
1067: .\" The named targets are executed in non parallel mode. If no targets are
1068: .\" specified, then all targets are executed in non parallel mode.
1069: .It Ic .NOTPARALLEL
1070: Disable parallel mode.
1071: .It Ic .NO_PARALLEL
1072: Same as above, for compatibility with other pmake variants.
1073: .It Ic .ORDER
1074: The named targets are made in sequence.
1075: .\" XXX: NOT YET!!!!
1076: .\" .It Ic .PARALLEL
1077: .\" The named targets are executed in parallel mode. If no targets are
1078: .\" specified, then all targets are executed in parallel mode.
1.1 deraadt 1079: .It Ic .PATH
1080: The sources are directories which are to be searched for files not
1081: found in the current directory.
1082: If no sources are specified, any previously specified directories are
1083: deleted.
1.18 espie 1084: .It Ic .PATH\fIsuffix\fR
1085: The sources are directories which are to be searched for suffixed files
1086: not found in the current directory.
1.19 ! aaron 1087: .Nm
! 1088: first searches the suffixed search path, before reverting to the default
1.18 espie 1089: path if the file is not found there.
1.6 niklas 1090: .It Ic .PHONY
1091: Apply the
1092: .Ic .PHONY
1093: attribute to any specified sources. Targets with this attribute are always
1094: considered to be out of date.
1.1 deraadt 1095: .It Ic .PRECIOUS
1096: Apply the
1097: .Ic .PRECIOUS
1098: attribute to any specified sources.
1099: If no sources are specified, the
1100: .Ic .PRECIOUS
1101: attribute is applied to every
1102: target in the file.
1103: .It Ic .SILENT
1104: Apply the
1105: .Ic .SILENT
1106: attribute to any specified sources.
1107: If no sources are specified, the
1108: .Ic .SILENT
1109: attribute is applied to every
1110: command in the file.
1111: .It Ic .SUFFIXES
1112: Each source specifies a suffix to
1113: .Nm make .
1114: If no sources are specified, any previous specified suffices are deleted.
1.15 espie 1115: .Sh COMPATIBILITY
1.19 ! aaron 1116: Older versions of
! 1117: .Nm
! 1118: used
1.15 espie 1119: .Ev MAKE
1.19 ! aaron 1120: instead of
1.15 espie 1121: .Ev MAKEFLAGS .
1122: This was removed for POSIX compatibility.
1.19 ! aaron 1123: The internal variable
1.15 espie 1124: .Va MAKE
1125: is set to the same value as
1126: .Va .MAKE ,
1127: support for this may be removed in the future.
1.18 espie 1128: .Pp
1.19 ! aaron 1129: Most of the more esoteric features of
! 1130: .Nm
1.18 espie 1131: should probably be avoided for greater compatibility.
1.1 deraadt 1132: .Sh ENVIRONMENT
1.19 ! aaron 1133: .Nm
1.15 espie 1134: uses the following environment variables, if they exist:
1.9 millert 1135: .Ev MACHINE ,
1.15 espie 1136: .Ev MACHINE_ARCH ,
1.9 millert 1137: .Ev MAKEFLAGS ,
1138: .Ev MAKEOBJDIR ,
1.15 espie 1139: .Ev MAKEOBJDIRPREFIX ,
1.1 deraadt 1140: and
1.9 millert 1141: .Ev PWD .
1.1 deraadt 1142: .Sh FILES
1143: .Bl -tag -width /usr/share/mk -compact
1.14 aaron 1144: .It Pa .depend
1.1 deraadt 1145: list of dependencies
1.15 espie 1146: .It Pa BSDmakefile
1147: list of dependencies
1.14 aaron 1148: .It Pa Makefile
1.1 deraadt 1149: list of dependencies
1.14 aaron 1150: .It Pa makefile
1.1 deraadt 1151: list of dependencies
1.14 aaron 1152: .It Pa sys.mk
1.1 deraadt 1153: system makefile
1.14 aaron 1154: .It Pa /usr/share/mk
1.1 deraadt 1155: system makefile directory
1.15 espie 1156: .IT Pa /usr/obj
1.19 ! aaron 1157: default
1.15 espie 1158: .Ev MAKEOBJDIRPREFIX directory.
1.1 deraadt 1159: .El
1.17 espie 1160: .Sh BUGS
1.18 espie 1161: The determination of
1162: .Va .OBJDIR
1.19 ! aaron 1163: is contorted to the point of absurdity.
1.18 espie 1164: .Pp
1165: In the presence of several
1166: .Ic .MAIN
1167: special targets,
1.19 ! aaron 1168: .Nm
1.18 espie 1169: silently ignores all but the first.
1170: .Pp
1171: .Va .TARGETS
1172: is not set to the default target when
1.19 ! aaron 1173: .Nm
1.18 espie 1174: is invoked without a target name and no
1.19 ! aaron 1175: .Ic MAIN
1.18 espie 1176: special target exists.
1177: .Pp
1.17 espie 1178: The evaluation of
1179: .Ar expression
1180: in a test is very simple-minded. Currently, the only form that works is
1181: .Ql .if ${VAR} op something
1182: For instance, you should write tests as
1183: .Ql .if ${VAR} = "string"
1184: not the other way around, which doesn't work.
1185: .Pp
1186: For loops are expanded before tests, so a fragment such as:
1187: .Bd -literal
1188: \&.for TMACHINE in ${SHARED_ARCHS}
1189: \&.if ${TMACHINE} = ${MACHINE}
1190: ...
1191: \&.endif
1192: \&.fi
1193: .Ed
1194: won't work, and should be rewritten the other way around.
1195:
1.1 deraadt 1196: .Sh SEE ALSO
1197: .Xr mkdep 1
1198: .Sh HISTORY
1199: A
1.19 ! aaron 1200: .Nm
1.1 deraadt 1201: command appeared in
1202: .At v7 .