Annotation of src/usr.bin/make/make.1, Revision 1.80
1.80 ! bluhm 1: .\" $OpenBSD: make.1,v 1.79 2008/03/03 23:04:33 jmc Exp $
1.40 espie 2: .\" $OpenPackages$
1.10 millert 3: .\" $NetBSD: make.1,v 1.18 1997/03/10 21:19:53 christos Exp $
1.7 briggs 4: .\"
1.9 millert 5: .\" Copyright (c) 1990, 1993
6: .\" The Regents of the University of California. All rights reserved.
1.1 deraadt 7: .\"
8: .\" Redistribution and use in source and binary forms, with or without
9: .\" modification, are permitted provided that the following conditions
10: .\" are met:
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. Redistributions in binary form must reproduce the above copyright
14: .\" notice, this list of conditions and the following disclaimer in the
15: .\" documentation and/or other materials provided with the distribution.
1.51 millert 16: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 17: .\" may be used to endorse or promote products derived from this software
18: .\" without specific prior written permission.
19: .\"
20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30: .\" SUCH DAMAGE.
31: .\"
1.9 millert 32: .\" from: @(#)make.1 8.4 (Berkeley) 3/19/94
1.1 deraadt 33: .\"
1.80 ! bluhm 34: .Dd $Mdocdate: March 3 2008 $
1.1 deraadt 35: .Dt MAKE 1
36: .Os
37: .Sh NAME
38: .Nm make
39: .Nd maintain program dependencies
40: .Sh SYNOPSIS
1.19 aaron 41: .Nm make
1.63 jmc 42: .Op Fl BeiknPqrSst
1.1 deraadt 43: .Op Fl D Ar variable
44: .Op Fl d Ar flags
45: .Op Fl f Ar makefile
46: .Op Fl I Ar directory
47: .Op Fl j Ar max_jobs
1.5 niklas 48: .Op Fl m Ar directory
1.9 millert 49: .Op Fl V Ar variable
1.60 espie 50: .Op Ar NAME Ns = Ns Ar value
1.50 jmc 51: .Bk -words
1.1 deraadt 52: .Op Ar target ...
1.50 jmc 53: .Ek
1.1 deraadt 54: .Sh DESCRIPTION
1.19 aaron 55: .Nm
1.1 deraadt 56: is a program designed to simplify the maintenance of other programs.
57: Its input is a list of specifications as to the files upon which programs
58: and other files depend.
59: If the file
1.54 jmc 60: .Sq Pa BSDmakefile
1.12 niklas 61: exists, it is read for this list of specifications.
62: If it does not exist, the files
1.54 jmc 63: .Sq Pa makefile
1.12 niklas 64: and
1.54 jmc 65: .Sq Pa Makefile
1.12 niklas 66: are tried in order.
1.1 deraadt 67: If the file
1.54 jmc 68: .Sq Pa .depend
1.40 espie 69: exists, it is read in addition to the makefile (see
1.42 mpech 70: .Xr mkdep 1 ) .
1.1 deraadt 71: .Pp
1.43 espie 72: The handling of
1.54 jmc 73: .Sq Pa BSDmakefile
1.43 espie 74: and
1.54 jmc 75: .Sq Pa .depend
1.43 espie 76: are BSD extensions.
77: .Pp
78: Standard options are as follows:
79: .Bl -tag -width Ds
80: .It Fl e
81: Specify that environment variables override macro assignments within
82: makefiles.
83: .It Fl f Ar makefile
84: Specify a makefile to read instead of the default
1.54 jmc 85: .Sq Pa makefile
1.43 espie 86: and
1.54 jmc 87: .Sq Pa Makefile .
1.43 espie 88: If
89: .Ar makefile
90: is
91: .Ql \- ,
92: standard input is read.
93: Multiple makefiles may be specified, and are read in the order specified.
94: .It Fl i
95: Ignore non-zero exit of shell commands in the makefile.
96: Equivalent to specifying
97: .Ql \-
98: before each command line in the makefile.
99: .It Fl k
100: Continue processing after errors are encountered, but only on those targets
101: that do not depend on the target whose creation caused the error.
102: .It Fl n
103: Display the commands that would have been executed, but do not actually
104: execute them.
105: .It Fl q
1.50 jmc 106: Do not execute any commands, but exit with status 0 if the specified targets
1.43 espie 107: are up-to-date, and 1 otherwise.
108: .It Fl r
109: Do not use the built-in rules specified in the system makefile.
110: .It Fl S
111: Stop processing when an error is encountered.
112: This is the default behavior.
113: This is needed to negate the
114: .Fl k
115: option during recursive builds.
116: .It Fl s
117: Do not echo commands as they are executed.
118: Equivalent to specifying
1.54 jmc 119: .Sq Ic @
1.43 espie 120: before each command line in the makefile.
121: .It Fl t
122: Rather than re-building a target as specified in the makefile, create it
123: or update its modification time to make it appear up-to-date.
1.60 espie 124: .It Ar NAME Ns = Ns Ar value
1.43 espie 125: Set the value of the variable
1.60 espie 126: .Ar NAME
1.43 espie 127: to
128: .Ar value .
129: .El
1.1 deraadt 130: .Pp
1.43 espie 131: Extended options are as follows:
1.1 deraadt 132: .Bl -tag -width Ds
1.9 millert 133: .It Fl B
1.3 deraadt 134: Try to be backwards compatible by executing a single shell per command and
135: by executing the commands to make the sources of a dependency line in sequence.
1.15 espie 136: This is turned on by default unless
137: .Fl j
138: is used.
1.1 deraadt 139: .It Fl D Ar variable
140: Define
141: .Ar variable
1.40 espie 142: to be 1.
1.1 deraadt 143: .It Fl d Ar flags
144: Turn on debugging, and specify which portions of
1.19 aaron 145: .Nm
1.1 deraadt 146: are to print debugging information.
1.14 aaron 147: .Ar flags
1.1 deraadt 148: is one or more of the following:
149: .Bl -tag -width Ds
150: .It Ar A
151: Print all possible debugging information;
152: equivalent to specifying all of the debugging flags.
153: .It Ar a
154: Print debugging information about archive searching and caching.
155: .It Ar c
156: Print debugging information about conditional evaluation.
157: .It Ar d
158: Print debugging information about directory searching and caching.
1.15 espie 159: .It Ar f
1.40 espie 160: Print debugging information about the expansion of for loops.
1.1 deraadt 161: .It Ar "g1"
162: Print the input graph before making anything.
163: .It Ar "g2"
164: Print the input graph after making everything, or before exiting
165: on error.
1.72 jmc 166: .It Ar J
167: Print job tokens showing which output corresponds to what job.
1.1 deraadt 168: .It Ar j
169: Print debugging information about running multiple shells.
1.40 espie 170: .It Ar l
171: Print commands in Makefile targets regardless of whether or not they are
172: prefixed by @.
173: Also known as loud behavior.
1.1 deraadt 174: .It Ar m
175: Print debugging information about making targets, including modification
176: dates.
1.75 espie 177: .It Ar p
1.77 jmc 178: Help finding concurrency issues for parallel make by adding some
1.76 espie 179: randomization.
1.75 espie 180: If
181: .Va RANDOM_ORDER
182: is defined,
183: targets will be shuffled before being built.
184: If
185: .Va RANDOM_DELAY
1.76 espie 186: is defined,
1.75 espie 187: .Nm
188: will wait between 0 and ${RANDOM_DELAY} seconds at the start of each job.
189: A given random seed can be forced by setting
190: .Va RANDOM_SEED ,
191: but this does not guarantee reproductibility.
1.1 deraadt 192: .It Ar s
193: Print debugging information about suffix-transformation rules.
194: .It Ar t
195: Print debugging information about target list maintenance.
196: .It Ar v
197: Print debugging information about variable assignment.
198: .El
199: .It Fl I Ar directory
200: Specify a directory in which to search for makefiles and included makefiles.
1.5 niklas 201: The system makefile directory (or directories, see the
202: .Fl m
203: option) is automatically included as part of this list.
1.1 deraadt 204: .It Fl j Ar max_jobs
205: Specify the maximum number of jobs that
1.19 aaron 206: .Nm
1.28 aaron 207: may have running at any one time.
208: Turns compatibility mode off, unless the
1.57 jmc 209: .Fl B
1.3 deraadt 210: flag is also specified.
1.5 niklas 211: .It Fl m Ar directory
1.50 jmc 212: Specify a directory in which to search for
213: .Pa sys.mk
1.40 espie 214: and makefiles included
1.28 aaron 215: via the <...> style.
216: Multiple directories can be added to form a search path.
1.14 aaron 217: This path will override the default system include path:
218: .Pa /usr/share/mk .
219: Furthermore, the system include path will be appended to the search path used
1.5 niklas 220: for "..."-style inclusions (see the
221: .Fl I
222: option).
1.15 espie 223: .It Fl P
1.19 aaron 224: Collate the output of a given job and display it only when the job finishes,
225: instead of mixing the output of parallel jobs together.
226: This option has no effect unless
1.15 espie 227: .Fl j
228: is used too.
1.9 millert 229: .It Fl V Ar variable
230: Print
231: .Nm make Ns 's
232: idea of the value of
1.40 espie 233: .Ar variable .
1.9 millert 234: Do not build any targets.
235: Multiple instances of this option may be specified;
236: the variables will be printed one per line,
237: with a blank line for each null or undefined variable.
1.1 deraadt 238: .El
239: .Pp
240: There are seven different types of lines in a makefile: file dependency
241: specifications, shell commands, variable assignments, include statements,
242: conditional directives, for loops, and comments.
1.43 espie 243: Of these, include statements, conditional directives and for loops are
244: extensions.
1.1 deraadt 245: .Pp
246: In general, lines may be continued from one line to the next by ending
247: them with a backslash
248: .Pq Ql \e .
249: The trailing newline character and initial whitespace on the following
250: line are compressed into a single space.
251: .Sh FILE DEPENDENCY SPECIFICATIONS
252: Dependency lines consist of one or more targets, an operator, and zero
253: or more sources.
1.19 aaron 254: This creates a relationship where the targets
255: .Dq depend
256: on the sources
1.1 deraadt 257: and are usually created from them.
258: The exact relationship between the target and the source is determined
259: by the operator that separates them.
1.43 espie 260: Note that the use of several targets is merely a shorthand for duplicate
1.50 jmc 261: rules.
1.43 espie 262: Specifically,
1.57 jmc 263: .Bd -literal -offset indent
1.43 espie 264: target1 target2: depa depb
265: cmd1
266: cmd2
267: .Ed
1.57 jmc 268: .Pp
1.43 espie 269: is just a short form of
1.57 jmc 270: .Bd -literal -offset indent
1.43 espie 271: target1: depa depb
272: cmd1
273: cmd2
274: target2: depa depb
275: cmd1
276: cmd2
277: .Ed
278: .Pp
279: .Nm
280: does not support Solaris syntax for true multiple targets:
1.57 jmc 281: .Bd -literal -offset indent
1.43 espie 282: target1 + target2: depa depb
283: cmd1
284: cmd2
285: .Ed
286: .Pp
1.40 espie 287: The operators are as follows:
1.1 deraadt 288: .Bl -tag -width flag
289: .It Ic \&:
290: A target is considered out-of-date if its modification time is less than
291: those of any of its sources.
292: Sources for a target accumulate over dependency lines when this operator
293: is used.
294: The target is removed if
1.19 aaron 295: .Nm
1.1 deraadt 296: is interrupted.
297: .It Ic \&!
298: Targets are always re-created, but not until all sources have been
299: examined and re-created as necessary.
300: Sources for a target accumulate over dependency lines when this operator
301: is used.
302: The target is removed if
1.19 aaron 303: .Nm
1.1 deraadt 304: is interrupted.
305: .It Ic \&::
306: If no sources are specified, the target is always re-created.
307: Otherwise, a target is considered out-of-date if any of its sources has
308: been modified more recently than the target.
309: Sources for a target do not accumulate over dependency lines when this
310: operator is used.
311: The target will not be removed if
1.19 aaron 312: .Nm
1.1 deraadt 313: is interrupted.
314: .El
315: .Pp
1.43 espie 316: The
317: .Ic \&::
318: operator is a fairly standard extension.
319: The
1.56 jmc 320: .Ic !\&
1.43 espie 321: operator is a BSD extension.
322: .Pp
1.50 jmc 323: As an extension, targets and sources may contain the shell wildcard
1.43 espie 324: expressions
1.55 jmc 325: .Ql \&? ,
1.1 deraadt 326: .Ql * ,
327: .Ql []
328: and
329: .Ql {} .
1.15 espie 330: The expressions
1.55 jmc 331: .Ql \&? ,
1.1 deraadt 332: .Ql *
333: and
334: .Ql []
335: may only be used as part of the final
336: component of the target or source, and must be used to describe existing
337: files.
1.15 espie 338: The expression
1.1 deraadt 339: .Ql {}
340: need not necessarily be used to describe existing files.
341: Expansion is in directory order, not alphabetically as done in the shell.
1.43 espie 342: .Pp
343: For maximum portability, target names should only consist of periods,
344: underscores, digits and alphabetic characters.
1.1 deraadt 345: .Sh SHELL COMMANDS
346: Each target may have associated with it a series of shell commands, normally
347: used to create the target.
348: Each of the commands in this script
349: .Em must
350: be preceded by a tab.
351: While any target may appear on a dependency line, only one of these
352: dependencies may be followed by a creation script, unless the
1.54 jmc 353: .Sq Ic ::
1.1 deraadt 354: operator is used.
355: .Pp
1.34 espie 356: If a command line begins with a combination of the characters,
1.54 jmc 357: .Sq Ic @ ,
358: .Sq Ic \-
1.1 deraadt 359: and/or
1.54 jmc 360: .Sq Ic + ,
1.57 jmc 361: the command is treated specially:
1.33 espie 362: .Bl -tag -width `@'
1.54 jmc 363: .It Sq Ic @
1.1 deraadt 364: causes the command not to be echoed before it is executed.
1.54 jmc 365: .It Sq Ic \-
1.1 deraadt 366: causes any non-zero exit status of the command line to be ignored.
1.54 jmc 367: .It Sq Ic +
1.33 espie 368: causes the command to be executed even if
369: .Fl n
1.57 jmc 370: has been specified.
371: (This can be useful to debug recursive Makefiles.)
1.33 espie 372: .El
1.43 espie 373: .Pp
1.50 jmc 374: The command is always executed using
1.43 espie 375: .Pa /bin/sh
376: in
377: .Qq set -e
378: mode.
1.1 deraadt 379: .Sh VARIABLE ASSIGNMENTS
1.14 aaron 380: Variables in
1.19 aaron 381: .Nm
1.14 aaron 382: are much like variables in the shell, and, by tradition,
1.1 deraadt 383: consist of all upper-case letters.
1.60 espie 384: They are also called
385: .Sq macros
386: in various texts.
1.43 espie 387: For portability, only periods, underscores, digits and letters should be
388: used for variable names.
1.1 deraadt 389: The five operators that can be used to assign values to variables are as
390: follows:
391: .Bl -tag -width Ds
392: .It Ic \&=
393: Assign the value to the variable.
394: Any previous value is overridden.
1.43 espie 395: .It Ic \&:=
396: Assign with expansion, i.e., expand the value before assigning it
1.57 jmc 397: to the variable (extension).
1.1 deraadt 398: .It Ic \&+=
1.43 espie 399: Append the value to the current value of the variable (extension).
1.1 deraadt 400: .It Ic \&?=
1.43 espie 401: Assign the value to the variable if it is not already defined (BSD
402: extension).
1.1 deraadt 403: Normally, expansion is not done until the variable is referenced.
404: .It Ic \&!=
405: Expand the value and pass it to the shell for execution and assign
406: the result to the variable.
1.43 espie 407: Any newlines in the result are replaced with spaces (BSD extension).
1.1 deraadt 408: .El
409: .Pp
1.14 aaron 410: Any whitespace before the assigned
1.1 deraadt 411: .Ar value
412: is removed; if the value is being appended, a single space is inserted
413: between the previous contents of the variable and the appended value.
414: .Pp
415: Variables are expanded by surrounding the variable name with either
416: curly braces
417: .Pq Ql {}
418: or parentheses
419: .Pq Ql ()
420: and preceding it with
421: a dollar sign
422: .Pq Ql \&$ .
423: If the variable name contains only a single letter, the surrounding
424: braces or parentheses are not required.
425: This shorter form is not recommended.
426: .Pp
427: Variable substitution occurs at two distinct times, depending on where
428: the variable is being used.
429: Variables in dependency lines are expanded as the line is read.
430: Variables in shell commands are expanded when the shell command is
431: executed.
432: .Pp
433: The four different classes of variables (in order of increasing precedence)
434: are:
435: .Bl -tag -width Ds
436: .It Environment variables
437: Variables defined as part of
438: .Nm make Ns 's
439: environment.
440: .It Global variables
441: Variables defined in the makefile or in included makefiles.
442: .It Command line variables
443: Variables defined as part of the command line.
444: .It Local variables
445: Variables that are defined specific to a certain target.
1.43 espie 446: Standard local variables are as follows:
1.1 deraadt 447: .Bl -tag -width ".ARCHIVE"
1.43 espie 448: .It Va @
449: The name of the target.
450: .It Va \&%
451: The name of the archive member (only valid for library rules).
452: .It Va \&!
453: The name of the archive file (only valid for library rules).
454: .It Va \&?
455: The list of prerequisites for this target that were deemed out-of-date.
456: .It Va \&<
457: The name of the source from which this target is to be built, if a valid
458: implied rule (suffix rule) is in scope.
459: .It Va *
460: The file prefix of the file, containing only the file portion,
461: no suffix or preceding directory components.
462: .El
463: .Pp
464: The six variables
1.54 jmc 465: .Sq Va "@F" ,
466: .Sq Va "@D" ,
467: .Sq Va "<F" ,
468: .Sq Va "<D" ,
469: .Sq Va "*F" ,
1.43 espie 470: and
1.54 jmc 471: .Sq Va "*D"
1.43 espie 472: yield the
473: .Qq filename
474: and
475: .Qq directory
476: parts of the corresponding macros.
477: .Pp
478: For maximum compatibility,
1.54 jmc 479: .Sq Va \&<
1.43 espie 480: should only be used for actual implied rules.
481: It is also set when there is an implied rule that matches the current
1.54 jmc 482: dependency in scope.
483: That is, in
1.57 jmc 484: .Bd -literal -offset indent
1.65 jmc 485: \&.SUFFIXES: .c .o
1.43 espie 486: file.o: file.c
487: cmd1 $<
488:
489: \&.c.o:
490: cmd2
491: .Ed
1.57 jmc 492: .Pp
1.43 espie 493: building
494: .Pa file.o
495: will execute
496: .Qq cmd1 file.c .
497: .Pp
498: As an extension,
499: .Nm
1.47 jsyn 500: supports the following local variables:
1.43 espie 501: .Bl -tag -width ".ARCHIVE"
502: .It Va \&>
503: The list of all sources for this target.
1.1 deraadt 504: .It Va .ALLSRC
1.43 espie 505: Synonym for
1.54 jmc 506: .Sq Va \&> .
1.1 deraadt 507: .It Va .ARCHIVE
1.43 espie 508: Synonym for
1.54 jmc 509: .Sq Va \&! .
1.1 deraadt 510: .It Va .IMPSRC
1.43 espie 511: Synonym for
1.54 jmc 512: .Sq Va \&< .
1.1 deraadt 513: .It Va .MEMBER
1.43 espie 514: Synonym for
1.54 jmc 515: .Sq Va \&% .
1.1 deraadt 516: .It Va .OODATE
1.43 espie 517: Synonym for
1.54 jmc 518: .Sq Va \&? .
1.1 deraadt 519: .It Va .PREFIX
1.43 espie 520: Synonym for
1.54 jmc 521: .Sq Va * .
1.1 deraadt 522: .It Va .TARGET
1.43 espie 523: Synonym for
1.54 jmc 524: .Sq Va @ .
1.1 deraadt 525: .El
526: .Pp
1.43 espie 527: These variables may be used on the dependency half of dependency
528: lines, when they make sense.
1.15 espie 529: .El
1.1 deraadt 530: .Pp
531: In addition,
1.19 aaron 532: .Nm
533: sets or knows about the following internal variables, or environment
1.15 espie 534: variables:
1.1 deraadt 535: .Bl -tag -width MAKEFLAGS
536: .It Va \&$
537: A single dollar sign
538: .Ql \&$ ,
1.29 aaron 539: i.e.,
1.1 deraadt 540: .Ql \&$$
541: expands to a single dollar
542: sign.
543: .It Va .MAKE
544: The name that
1.19 aaron 545: .Nm
1.1 deraadt 546: was executed with
1.14 aaron 547: .Pq Va argv Ns Op 0 .
1.1 deraadt 548: .It Va .CURDIR
549: A path to the directory where
1.19 aaron 550: .Nm
1.1 deraadt 551: was executed.
552: .It Va .OBJDIR
553: A path to the directory where the targets are built.
1.8 deraadt 554: At startup,
1.19 aaron 555: .Nm
1.8 deraadt 556: searches for an alternate directory to place target files -- it
557: will attempt to change into this special directory.
1.19 aaron 558: First, if
559: .Ev MAKEOBJDIRPREFIX
560: is defined,
561: .Nm
1.18 espie 562: prepends its contents to the current directory name and tries for
1.28 aaron 563: the resulting directory.
564: If that fails,
1.19 aaron 565: .Nm
1.18 espie 566: remains in the current directory.
1.19 aaron 567: If
1.15 espie 568: .Ev MAKEOBJDIRPREFIX
1.18 espie 569: is not defined,
1.19 aaron 570: .Nm
1.18 espie 571: checks
1.19 aaron 572: .Ev MAKEOBJDIR
1.28 aaron 573: and tries to change into that directory.
574: Should that fail,
1.19 aaron 575: .Nm
1.28 aaron 576: remains in the current directory.
577: If
1.18 espie 578: .Ev MAKEOBJDIR
579: is not defined, it tries to change into the directory named
580: .Pa obj.${MACHINE}
1.19 aaron 581: (see
582: .Va MACHINE
1.28 aaron 583: variable).
584: If it still has found no special directory,
1.19 aaron 585: .Nm
1.18 espie 586: next tries the directory named
587: .Pa obj .
588: If this fails,
1.19 aaron 589: .Nm
590: tries to prepend
591: .Pa /usr/obj
592: to the current directory name.
1.18 espie 593: Finally, if none of these directories are available
1.19 aaron 594: .Nm
1.8 deraadt 595: will settle for and use the current directory.
1.15 espie 596: .It Va .MAKEFLAGS
1.1 deraadt 597: The environment variable
1.14 aaron 598: .Ev MAKEFLAGS
1.1 deraadt 599: may contain anything that
600: may be specified on
601: .Nm make Ns 's
1.28 aaron 602: command line.
603: Its contents are stored in
1.15 espie 604: .Nm make Ns 's
1.19 aaron 605: .Va .MAKEFLAGS
1.15 espie 606: variable.
1.40 espie 607: Anything specified on
1.1 deraadt 608: .Nm make Ns 's
609: command line is appended to the
1.15 espie 610: .Va .MAKEFLAGS
611: variable which is then
1.19 aaron 612: entered into the environment as
1.14 aaron 613: .Ev MAKEFLAGS
1.15 espie 614: for all programs which
1.19 aaron 615: .Nm
1.1 deraadt 616: executes.
1.15 espie 617: .It Va MFLAGS
1.19 aaron 618: A shorter synonym for
1.15 espie 619: .Va .MAKEFLAGS .
1.9 millert 620: .It Ev PWD
621: Alternate path to the current directory.
1.19 aaron 622: .Nm
1.9 millert 623: normally sets
1.54 jmc 624: .Sq Va .CURDIR
1.9 millert 625: to the canonical path given by
1.49 jmc 626: .Xr getcwd 3 .
1.9 millert 627: However, if the environment variable
1.14 aaron 628: .Ev PWD
1.9 millert 629: is set and gives a path to the current directory, then
1.19 aaron 630: .Nm
1.9 millert 631: sets
1.54 jmc 632: .Sq Va .CURDIR
1.9 millert 633: to the value of
1.14 aaron 634: .Ev PWD
1.9 millert 635: instead.
1.14 aaron 636: .Ev PWD
1.15 espie 637: is always set to the value of
1.54 jmc 638: .Sq Va .OBJDIR
1.9 millert 639: for all programs which
1.19 aaron 640: .Nm
1.9 millert 641: executes.
1.15 espie 642: .It Va .TARGETS
1.19 aaron 643: List of targets
644: .Nm
1.18 espie 645: is currently building.
1.15 espie 646: .It Va .INCLUDES
1.19 aaron 647: See
1.18 espie 648: .Ic .INCLUDES
1.57 jmc 649: special target.
1.15 espie 650: .It Va .LIBS
1.19 aaron 651: See
1.18 espie 652: .Ic .LIBS
1.57 jmc 653: special target.
1.15 espie 654: .It Va MACHINE
1.19 aaron 655: Name of the machine architecture
656: .Nm
1.18 espie 657: is running on, obtained from the
658: .Ev MACHINE
1.19 aaron 659: environment variable, or through
1.44 deraadt 660: .Xr uname 3
1.18 espie 661: if not defined.
1.15 espie 662: .It Va MACHINE_ARCH
1.18 espie 663: Name of the machine architecture
1.19 aaron 664: .Nm
1.18 espie 665: was compiled for, obtained from the
1.19 aaron 666: .Ev MACHINE_ARCH
1.18 espie 667: environment variable, or defined at compilation time.
1.80 ! bluhm 668: .It Va MAKEFILE
! 669: Possibly the file name of the last makefile that has been read.
! 670: It should not be used; see the
! 671: .Sx BUGS
! 672: section below.
1.1 deraadt 673: .El
674: .Pp
675: Variable expansion may be modified to select or modify each word of the
1.48 pvalchev 676: variable (where
1.19 aaron 677: .Dq word
1.48 pvalchev 678: is a whitespace delimited sequence of characters).
1.1 deraadt 679: The general format of a variable expansion is as follows:
680: .Pp
681: .Dl {variable[:modifier[:...]]}
682: .Pp
683: Each modifier begins with a colon and one of the following
684: special characters.
685: The colon may be escaped with a backslash
686: .Pq Ql \e .
1.54 jmc 687: .Bl -tag -width Ds
1.58 espie 688: .It Cm :E
1.1 deraadt 689: Replaces each word in the variable with its suffix.
1.58 espie 690: .It Cm :H
1.1 deraadt 691: Replaces each word in the variable with everything but the last component.
1.58 espie 692: .It Cm :L
1.20 espie 693: Replaces each word in the variable with its lower case equivalent.
1.58 espie 694: .It Cm :U
1.20 espie 695: Replaces each word in the variable with its upper case equivalent.
1.58 espie 696: .It Cm :M Ns Ar pattern
1.1 deraadt 697: Select only those words that match the rest of the modifier.
698: The standard shell wildcard characters
699: .Pf ( Ql * ,
1.55 jmc 700: .Ql \&? ,
1.1 deraadt 701: and
1.54 jmc 702: .Ql [] )
1.1 deraadt 703: may
704: be used.
705: The wildcard characters may be escaped with a backslash
706: .Pq Ql \e .
1.58 espie 707: .It Cm :N Ns Ar pattern
1.1 deraadt 708: This is identical to
1.58 espie 709: .Cm :M ,
1.1 deraadt 710: but selects all words which do not match
711: the rest of the modifier.
1.58 espie 712: .It Cm :Q
1.10 millert 713: Quotes every shell meta-character in the variable, so that it can be passed
714: safely through recursive invocations of
1.14 aaron 715: .Nm make .
1.58 espie 716: .It Cm :R
1.1 deraadt 717: Replaces each word in the variable with everything but its suffix.
718: .Sm off
1.58 espie 719: .It Cm :S No \&/ Ar old_string Xo
1.10 millert 720: .No \&/ Ar new_string
721: .No \&/ Op Cm 1g
1.1 deraadt 722: .Xc
723: .Sm on
724: Modify the first occurrence of
1.10 millert 725: .Ar old_string
726: in the variable's value, replacing it with
727: .Ar new_string .
1.1 deraadt 728: If a
729: .Ql g
730: is appended to the last slash of the pattern, all occurrences
731: in each word are replaced.
1.10 millert 732: If a
733: .Ql 1
734: is appended to the last slash of the pattern, only the first word
735: is affected.
1.1 deraadt 736: If
1.10 millert 737: .Ar old_string
738: begins with a caret
1.1 deraadt 739: .Pq Ql ^ ,
1.10 millert 740: .Ar old_string
1.1 deraadt 741: is anchored at the beginning of each word.
742: If
1.10 millert 743: .Ar old_string
1.1 deraadt 744: ends with a dollar sign
745: .Pq Ql \&$ ,
746: it is anchored at the end of each word.
747: Inside
748: .Ar new_string ,
749: an ampersand
750: .Pq Ql &
751: is replaced by
1.10 millert 752: .Ar old_string
753: (without any
754: .Ql ^
755: or
756: .Ql \&$ ) .
1.1 deraadt 757: Any character may be used as a delimiter for the parts of the modifier
758: string.
759: The anchoring, ampersand and delimiter characters may be escaped with a
760: backslash
761: .Pq Ql \e .
762: .Pp
763: Variable expansion occurs in the normal fashion inside both
764: .Ar old_string
765: and
766: .Ar new_string
767: with the single exception that a backslash is used to prevent the expansion
768: of a dollar sign
1.10 millert 769: .Pq Ql \&$ ,
1.1 deraadt 770: not a preceding dollar sign as is usual.
1.10 millert 771: .Sm off
1.58 espie 772: .It Cm :C No \&/ Ar pattern Xo
1.10 millert 773: .No \&/ Ar replacement
774: .No \&/ Op Cm 1g
775: .Xc
776: .Sm on
777: The
1.58 espie 778: .Cm :C
1.10 millert 779: modifier is just like the
1.58 espie 780: .Cm :S
1.13 deraadt 781: modifier except that the old and new strings, instead of being
1.10 millert 782: simple strings, are a regular expression (see
783: .Xr regex 3 )
784: and an
785: .Xr ed 1 Ns \-style
1.28 aaron 786: replacement string.
787: Normally, the first occurrence of the pattern in
788: each word of the value is changed.
789: The
1.10 millert 790: .Ql 1
791: modifier causes the substitution to apply to at most one word; the
792: .Ql g
793: modifier causes the substitution to apply to as many instances of the
1.28 aaron 794: search pattern as occur in the word or words it is found in.
795: Note that
1.10 millert 796: .Ql 1
797: and
798: .Ql g
799: are orthogonal; the former specifies whether multiple words are
800: potentially affected, the latter whether multiple substitutions can
801: potentially occur within each affected word.
1.58 espie 802: .It Cm :T
1.1 deraadt 803: Replaces each word in the variable with its last component.
1.59 jmc 804: .It Ar :old_string Ns = Ns Ar new_string
1.1 deraadt 805: This is the
806: .At V
807: style variable substitution.
808: It must be the last modifier specified.
1.9 millert 809: If
1.1 deraadt 810: .Ar old_string
811: or
812: .Ar new_string
813: do not contain the pattern matching character
814: .Ar %
1.9 millert 815: then it is assumed that they are
1.1 deraadt 816: anchored at the end of each word, so only suffixes or entire
1.28 aaron 817: words may be replaced.
818: Otherwise
1.1 deraadt 819: .Ar %
1.9 millert 820: is the substring of
821: .Ar old_string
1.1 deraadt 822: to be replaced in
1.53 jmc 823: .Ar new_string .
1.1 deraadt 824: .El
1.53 jmc 825: .Pp
1.50 jmc 826: All modifiers are BSD extensions, except for the standard
1.46 espie 827: .At V
828: style variable substitution.
1.1 deraadt 829: .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1.28 aaron 830: Makefile inclusion, conditional structures and for loops reminiscent
1.1 deraadt 831: of the C programming language are provided in
832: .Nm make .
833: All such structures are identified by a line beginning with a single
834: dot
835: .Pq Ql \&.
836: character.
1.46 espie 837: Whitespace characters may follow this dot, e.g.,
1.57 jmc 838: .Bd -literal -offset indent
839: \&.include <file>
1.46 espie 840: .Ed
841: and
1.57 jmc 842: .Bd -literal -offset indent -compact
843: \&. include <file>
1.46 espie 844: .Ed
1.57 jmc 845: .Pp
1.46 espie 846: are identical constructs.
1.1 deraadt 847: Files are included with either
848: .Ql .include <file>
849: or
850: .Ql .include \*qfile\*q .
851: Variables between the angle brackets or double quotes are expanded
852: to form the file name.
853: If angle brackets are used, the included makefile is expected to be in
854: the system makefile directory.
855: If double quotes are used, the including makefile's directory and any
856: directories specified using the
857: .Fl I
858: option are searched before the system
859: makefile directory.
860: .Pp
861: Conditional expressions are also preceded by a single dot as the first
862: character of a line.
863: The possible conditionals are as follows:
864: .Bl -tag -width Ds
865: .It Ic .undef Ar variable
866: Un-define the specified global variable.
867: Only global variables may be un-defined.
1.69 espie 868: .It Ic .poison Ar variable
869: Poison the specified global variable.
1.70 jmc 870: Any further reference to
1.69 espie 871: .Ar variable
872: will be flagged as an error.
1.70 jmc 873: .It Ic .poison !defined Pq Ar variable
1.69 espie 874: It is an error to try to use the value of
875: .Ar variable
1.70 jmc 876: in a context where it is not defined.
877: .It Ic .poison empty Pq Ar variable
1.69 espie 878: It is an error to try to use the value of
879: .Ar variable
1.70 jmc 880: in a context where it is not defined or empty.
1.1 deraadt 881: .It Xo
882: .Ic \&.if
883: .Oo \&! Oc Ns Ar expression
884: .Op Ar operator expression ...
885: .Xc
886: Test the value of an expression.
887: .It Xo
888: .Ic .ifdef
889: .Oo \&! Oc Ns Ar variable
890: .Op Ar operator variable ...
891: .Xc
892: Test the value of a variable.
893: .It Xo
894: .Ic .ifndef
895: .Oo \&! Oc Ns Ar variable
896: .Op Ar operator variable ...
897: .Xc
898: Test the value of a variable.
899: .It Xo
900: .Ic .ifmake
901: .Oo \&! Oc Ns Ar target
902: .Op Ar operator target ...
903: .Xc
904: Test the target being built.
905: .It Xo
906: .Ic .ifnmake
907: .Oo \&! Oc Ar target
908: .Op Ar operator target ...
909: .Xc
910: Test the target being built.
911: .It Ic .else
912: Reverse the sense of the last conditional.
913: .It Xo
914: .Ic .elif
915: .Oo \&! Oc Ar expression
916: .Op Ar operator expression ...
917: .Xc
918: A combination of
1.54 jmc 919: .Sq Ic .else
1.1 deraadt 920: followed by
1.54 jmc 921: .Sq Ic .if .
1.1 deraadt 922: .It Xo
923: .Ic .elifdef
924: .Oo \&! Oc Ns Ar variable
925: .Op Ar operator variable ...
926: .Xc
927: A combination of
1.54 jmc 928: .Sq Ic .else
1.1 deraadt 929: followed by
1.54 jmc 930: .Sq Ic .ifdef .
1.1 deraadt 931: .It Xo
932: .Ic .elifndef
933: .Oo \&! Oc Ns Ar variable
934: .Op Ar operator variable ...
935: .Xc
936: A combination of
1.54 jmc 937: .Sq Ic .else
1.1 deraadt 938: followed by
1.54 jmc 939: .Sq Ic .ifndef .
1.1 deraadt 940: .It Xo
941: .Ic .elifmake
942: .Oo \&! Oc Ns Ar target
943: .Op Ar operator target ...
944: .Xc
945: A combination of
1.54 jmc 946: .Sq Ic .else
1.1 deraadt 947: followed by
1.54 jmc 948: .Sq Ic .ifmake .
1.1 deraadt 949: .It Xo
950: .Ic .elifnmake
951: .Oo \&! Oc Ns Ar target
952: .Op Ar operator target ...
953: .Xc
954: A combination of
1.54 jmc 955: .Sq Ic .else
1.1 deraadt 956: followed by
1.54 jmc 957: .Sq Ic .ifnmake .
1.1 deraadt 958: .It Ic .endif
959: End the body of the conditional.
960: .El
961: .Pp
962: The
963: .Ar operator
964: may be any one of the following:
965: .Bl -tag -width "Cm XX"
966: .It Cm \&|\&|
967: logical OR
968: .It Cm \&&&
969: Logical
970: .Tn AND ;
971: of higher precedence than
1.46 espie 972: .Dq \&|\&| .
1.1 deraadt 973: .El
974: .Pp
975: As in C,
1.19 aaron 976: .Nm
1.1 deraadt 977: will only evaluate a conditional as far as is necessary to determine
978: its value.
1.9 millert 979: Parentheses may be used to change the order of evaluation.
1.1 deraadt 980: The boolean operator
1.54 jmc 981: .Sq Ic \&!
1.1 deraadt 982: may be used to logically negate an entire
983: conditional.
984: It is of higher precedence than
1.54 jmc 985: .Sq Ic \&&& .
1.1 deraadt 986: .Pp
987: The value of
988: .Ar expression
989: may be any of the following:
1.54 jmc 990: .Bl -tag -width defined
1.1 deraadt 991: .It Ic defined
992: Takes a variable name as an argument and evaluates to true if the variable
993: has been defined.
994: .It Ic make
995: Takes a target name as an argument and evaluates to true if the target
996: was specified as part of
997: .Nm make Ns 's
998: command line or was declared the default target (either implicitly or
999: explicitly, see
1000: .Va .MAIN )
1001: before the line containing the conditional.
1002: .It Ic empty
1003: Takes a variable, with possible modifiers, and evaluates to true if
1004: the expansion of the variable would result in an empty string.
1005: .It Ic exists
1006: Takes a file name as an argument and evaluates to true if the file exists.
1007: The file is searched for on the system search path (see
1008: .Va .PATH ) .
1009: .It Ic target
1010: Takes a target name as an argument and evaluates to true if the target
1011: has been defined.
1012: .El
1013: .Pp
1.14 aaron 1014: .Ar expression
1.28 aaron 1015: may also be an arithmetic or string comparison.
1016: Variable expansion is
1.1 deraadt 1017: performed on both sides of the comparison, after which the integral
1.28 aaron 1018: values are compared.
1019: A value is interpreted as hexadecimal if it is
1.1 deraadt 1020: preceded by 0x, otherwise it is decimal; octal numbers are not supported.
1.28 aaron 1021: The standard C relational operators are all supported.
1022: If after
1.1 deraadt 1023: variable expansion, either the left or right hand side of a
1.54 jmc 1024: .Sq Ic ==
1.1 deraadt 1025: or
1.54 jmc 1026: .Sq Ic "!="
1.1 deraadt 1027: operator is not an integral value, then
1028: string comparison is performed between the expanded
1029: variables.
1030: If no relational operator is given, it is assumed that the expanded
1031: variable is being compared against 0.
1032: .Pp
1033: When
1.19 aaron 1034: .Nm
1.14 aaron 1035: is evaluating one of these conditional expressions, and it encounters
1.19 aaron 1036: a word it doesn't recognize, either the
1037: .Dq make
1038: or
1039: .Dq defined
1.1 deraadt 1040: expression is applied to it, depending on the form of the conditional.
1041: If the form is
1.54 jmc 1042: .Sq Ic .ifdef
1.1 deraadt 1043: or
1.54 jmc 1044: .Sq Ic .ifndef ,
1.19 aaron 1045: the
1046: .Dq defined
1047: expression is applied.
1.1 deraadt 1048: Similarly, if the form is
1.54 jmc 1049: .Sq Ic .ifmake
1.1 deraadt 1050: or
1.54 jmc 1051: .Sq Ic .ifnmake ,
1.19 aaron 1052: the
1053: .Dq make
1.1 deraadt 1054: expression is applied.
1055: .Pp
1056: If the conditional evaluates to true the parsing of the makefile continues
1057: as before.
1058: If it evaluates to false, the following lines are skipped.
1059: In both cases this continues until a
1.54 jmc 1060: .Sq Ic .else
1.1 deraadt 1061: or
1.54 jmc 1062: .Sq Ic .endif
1.1 deraadt 1063: is found.
1.9 millert 1064: .Pp
1.1 deraadt 1065: For loops are typically used to apply a set of rules to a list of files.
1066: The syntax of a for loop is:
1.54 jmc 1067: .Bd -unfilled -offset indent
1068: .Xo
1069: .Ic .for Ar variable Op Ar variable ...
1.9 millert 1070: .Ic in
1.1 deraadt 1071: .Ar expression
1072: .Xc
1.54 jmc 1073: <make-rules>
1.1 deraadt 1074: .Ic \&.endfor
1.54 jmc 1075: .Ed
1076: .Pp
1.1 deraadt 1077: After the for
1.14 aaron 1078: .Ar expression
1.28 aaron 1079: is evaluated, it is split into words.
1.50 jmc 1080: On each iteration of the loop, one word is assigned to each
1.41 espie 1081: .Ar variable ,
1082: in order,
1.50 jmc 1083: and these
1084: .Ar variables
1.41 espie 1085: are substituted in the
1.9 millert 1086: .Ic make-rules
1.1 deraadt 1087: inside the body of the for loop.
1.41 espie 1088: The number of words must match the number of iteration variables;
1089: that is, if there are three iteration variables, the number of words
1.48 pvalchev 1090: must be a multiple of three.
1.45 espie 1091: .Pp
1092: Loops and conditional expressions may nest arbitrarily, but
1093: they may not cross include file boundaries.
1.1 deraadt 1094: .Sh COMMENTS
1095: Comments begin with a hash
1096: .Pq Ql \&#
1097: character, anywhere but in a shell
1098: command line, and continue to the end of the line.
1099: .Sh SPECIAL SOURCES
1.54 jmc 1100: .Bl -tag -width ".PRECIOUS"
1.1 deraadt 1101: .It Ic .IGNORE
1102: Ignore any errors from the commands associated with this target, exactly
1103: as if they all were preceded by a dash
1104: .Pq Ql \- .
1.10 millert 1105: .It Ic .MADE
1.19 aaron 1106: Mark all sources of this target as being up-to-date.
1.1 deraadt 1107: .It Ic .MAKE
1108: Execute the commands associated with this target even if the
1109: .Fl n
1110: or
1111: .Fl t
1112: options were specified.
1113: Normally used to mark recursive
1114: .Nm make Ns 's .
1115: .It Ic .NOTMAIN
1116: Normally
1.19 aaron 1117: .Nm
1.1 deraadt 1118: selects the first target it encounters as the default target to be built
1119: if no target was specified.
1120: This source prevents this target from being selected.
1121: .It Ic .OPTIONAL
1122: If a target is marked with this attribute and
1.19 aaron 1123: .Nm
1.1 deraadt 1124: can't figure out how to create it, it will ignore this fact and assume
1125: the file isn't needed or already exists.
1126: .It Ic .PRECIOUS
1127: When
1.19 aaron 1128: .Nm
1.1 deraadt 1129: is interrupted, it removes any partially made targets.
1130: This source prevents the target from being removed.
1131: .It Ic .SILENT
1132: Do not echo any of the commands associated with this target, exactly
1133: as if they all were preceded by an at sign
1134: .Pq Ql @ .
1135: .It Ic .USE
1136: Turn the target into
1.14 aaron 1137: .Nm make Ns 's
1.1 deraadt 1138: version of a macro.
1139: When the target is used as a source for another target, the other target
1140: acquires the commands, sources, and attributes (except for
1141: .Ic .USE )
1142: of the
1143: source.
1144: If the target already has commands, the
1145: .Ic .USE
1146: target's commands are appended
1147: to them.
1.4 deraadt 1148: .It Ic .WAIT
1.48 pvalchev 1149: If
1.4 deraadt 1150: .Ic .WAIT
1.48 pvalchev 1151: appears in a dependency line, the sources that precede it are
1.28 aaron 1152: made before the sources that succeed it in the line.
1.48 pvalchev 1153: Loops are not
1.4 deraadt 1154: detected and targets that form loops will be silently ignored.
1.1 deraadt 1155: .El
1156: .Sh "SPECIAL TARGETS"
1.29 aaron 1157: Special targets may not be included with other targets, i.e., they must be
1.1 deraadt 1158: the only target specified.
1.54 jmc 1159: .Bl -tag -width ".NOTPARALLEL"
1.1 deraadt 1160: .It Ic .BEGIN
1161: Any command lines attached to this target are executed before anything
1162: else is done.
1163: .It Ic .DEFAULT
1164: This is sort of a
1165: .Ic .USE
1166: rule for any target (that was used only as a
1167: source) that
1.19 aaron 1168: .Nm
1.1 deraadt 1169: can't figure out any other way to create.
1170: Only the shell script is used.
1171: The
1172: .Ic .IMPSRC
1173: variable of a target that inherits
1174: .Ic .DEFAULT Ns 's
1175: commands is set
1176: to the target's own name.
1177: .It Ic .END
1178: Any command lines attached to this target are executed after everything
1179: else is done.
1180: .It Ic .IGNORE
1181: Mark each of the sources with the
1182: .Ic .IGNORE
1183: attribute.
1184: If no sources are specified, this is the equivalent of specifying the
1185: .Fl i
1186: option.
1.18 espie 1187: .It Ic .INCLUDES
1188: A list of suffixes that indicate files that can be included in a source
1.28 aaron 1189: file.
1190: The suffix must have already been declared with
1.18 espie 1191: .Ic .SUFFIXES ,
1.48 pvalchev 1192: any suffix so declared will have the directories in its search path (see
1.18 espie 1193: .Ic .PATH )
1.19 aaron 1194: placed in the
1.18 espie 1195: .Va .INCLUDES
1.19 aaron 1196: special variable, each preceded by a
1197: .Fl I
1.18 espie 1198: flag.
1.1 deraadt 1199: .It Ic .INTERRUPT
1200: If
1.19 aaron 1201: .Nm
1.1 deraadt 1202: is interrupted, the commands for this target will be executed.
1.18 espie 1203: .It Ic .LIBS
1.19 aaron 1204: This does for libraries what
1205: .Ic .INCLUDES
1.18 espie 1206: does for include files, except that the flag used is
1207: .Fl L .
1.1 deraadt 1208: .It Ic .MAIN
1209: If no target is specified when
1.19 aaron 1210: .Nm
1.28 aaron 1211: is invoked, this target will be built.
1212: This is always set, either
1.19 aaron 1213: explicitly, or implicitly when
1214: .Nm
1.16 espie 1215: selects the default target, to give the user a way to refer to the default
1216: target on the command line.
1.1 deraadt 1217: .It Ic .MAKEFLAGS
1218: This target provides a way to specify flags for
1.19 aaron 1219: .Nm
1.1 deraadt 1220: when the makefile is used.
1221: The flags are as if typed to the shell, though the
1222: .Fl f
1223: option will have
1224: no effect.
1.4 deraadt 1225: .\" XXX: NOT YET!!!!
1226: .\" .It Ic .NOTPARALLEL
1227: .\" The named targets are executed in non parallel mode. If no targets are
1228: .\" specified, then all targets are executed in non parallel mode.
1229: .It Ic .NOTPARALLEL
1230: Disable parallel mode.
1231: .It Ic .NO_PARALLEL
1232: Same as above, for compatibility with other pmake variants.
1233: .It Ic .ORDER
1234: The named targets are made in sequence.
1235: .\" XXX: NOT YET!!!!
1236: .\" .It Ic .PARALLEL
1237: .\" The named targets are executed in parallel mode. If no targets are
1238: .\" specified, then all targets are executed in parallel mode.
1.1 deraadt 1239: .It Ic .PATH
1240: The sources are directories which are to be searched for files not
1241: found in the current directory.
1242: If no sources are specified, any previously specified directories are
1243: deleted.
1.18 espie 1244: .It Ic .PATH\fIsuffix\fR
1245: The sources are directories which are to be searched for suffixed files
1246: not found in the current directory.
1.19 aaron 1247: .Nm
1248: first searches the suffixed search path, before reverting to the default
1.18 espie 1249: path if the file is not found there.
1.6 niklas 1250: .It Ic .PHONY
1251: Apply the
1252: .Ic .PHONY
1.28 aaron 1253: attribute to any specified sources.
1254: Targets with this attribute are always
1.6 niklas 1255: considered to be out of date.
1.1 deraadt 1256: .It Ic .PRECIOUS
1257: Apply the
1258: .Ic .PRECIOUS
1259: attribute to any specified sources.
1260: If no sources are specified, the
1261: .Ic .PRECIOUS
1262: attribute is applied to every
1263: target in the file.
1264: .It Ic .SILENT
1265: Apply the
1266: .Ic .SILENT
1267: attribute to any specified sources.
1268: If no sources are specified, the
1269: .Ic .SILENT
1270: attribute is applied to every
1271: command in the file.
1272: .It Ic .SUFFIXES
1273: Each source specifies a suffix to
1274: .Nm make .
1.61 jmc 1275: If no sources are specified, any previously specified suffixes are deleted.
1.35 aaron 1276: .El
1.1 deraadt 1277: .Sh ENVIRONMENT
1.19 aaron 1278: .Nm
1.15 espie 1279: uses the following environment variables, if they exist:
1.9 millert 1280: .Ev MACHINE ,
1.15 espie 1281: .Ev MACHINE_ARCH ,
1.9 millert 1282: .Ev MAKEFLAGS ,
1283: .Ev MAKEOBJDIR ,
1.15 espie 1284: .Ev MAKEOBJDIRPREFIX ,
1.1 deraadt 1285: and
1.9 millert 1286: .Ev PWD .
1.30 espie 1287: .Nm
1.31 aaron 1288: also ignores and unsets
1.30 espie 1289: .Ev CDPATH .
1.1 deraadt 1290: .Sh FILES
1291: .Bl -tag -width /usr/share/mk -compact
1.14 aaron 1292: .It Pa .depend
1.1 deraadt 1293: list of dependencies
1.15 espie 1294: .It Pa BSDmakefile
1.66 jmc 1295: default makefile
1296: .It Pa makefile
1297: default makefile if
1298: .Pa BSDmakefile
1299: does not exist
1.14 aaron 1300: .It Pa Makefile
1.66 jmc 1301: default makefile if
1302: .Pa makefile
1303: does not exist
1.14 aaron 1304: .It Pa sys.mk
1.1 deraadt 1305: system makefile
1.14 aaron 1306: .It Pa /usr/share/mk
1.1 deraadt 1307: system makefile directory
1.62 jmc 1308: .It Pa /usr/obj
1.19 aaron 1309: default
1.52 jmc 1310: .Ev MAKEOBJDIRPREFIX
1.57 jmc 1311: directory
1.1 deraadt 1312: .El
1.37 aaron 1313: .Sh SEE ALSO
1.57 jmc 1314: .Xr ed 1 ,
1315: .Xr mkdep 1 ,
1316: .Xr sh 1 ,
1317: .Xr getcwd 3 ,
1318: .Xr regex 3 ,
1319: .Xr uname 3
1.37 aaron 1320: .Pp
1.63 jmc 1321: "Make \(em A Tutorial",
1322: .Pa /usr/share/doc/psd/12.make/ .
1.52 jmc 1323: .Sh STANDARDS
1.67 jmc 1324: The
1.43 espie 1325: .Nm
1.67 jmc 1326: utility is compliant with the
1327: .St -p1003.1-2004
1328: specification.
1329: .Pp
1330: The flags
1331: .Op Fl BDdIjmPV
1332: are extensions to that specification.
1.43 espie 1333: .Pp
1.37 aaron 1334: Older versions of
1335: .Nm
1336: used
1337: .Ev MAKE
1338: instead of
1339: .Ev MAKEFLAGS .
1340: This was removed for POSIX compatibility.
1341: The internal variable
1342: .Va MAKE
1343: is set to the same value as
1.48 pvalchev 1344: .Va .MAKE .
1345: Support for this may be removed in the future.
1.37 aaron 1346: .Pp
1347: Most of the more esoteric features of
1348: .Nm
1349: should probably be avoided for greater compatibility.
1350: .Sh HISTORY
1351: A
1352: .Nm
1353: command appeared in
1354: .At v7 .
1.17 espie 1355: .Sh BUGS
1.18 espie 1356: The determination of
1357: .Va .OBJDIR
1.19 aaron 1358: is contorted to the point of absurdity.
1.18 espie 1359: .Pp
1.50 jmc 1360: If the same target is specified several times in normal dependency rules,
1.31 aaron 1361: .Nm
1.27 espie 1362: silently ignores all commands after the first non empty set of commands,
1.31 aaron 1363: e.g., in
1.57 jmc 1364: .Bd -literal -offset indent
1.27 espie 1365: a:
1366: @echo "Executed"
1367: a:
1368: @echo "Bad luck"
1369: .Ed
1370: .Pp
1371: @echo "Bad luck" will be silently ignored.
1.18 espie 1372: .Pp
1373: .Va .TARGETS
1374: is not set to the default target when
1.19 aaron 1375: .Nm
1.18 espie 1376: is invoked without a target name and no
1.19 aaron 1377: .Ic MAIN
1.18 espie 1378: special target exists.
1379: .Pp
1.17 espie 1380: The evaluation of
1381: .Ar expression
1.28 aaron 1382: in a test is very simple-minded.
1383: Currently, the only form that works is
1.48 pvalchev 1384: .Ql .if ${VAR} op something \.
1.50 jmc 1385: For instance, tests should be written as
1.64 mbalmer 1386: .Ql .if ${VAR} == "string" ,
1.17 espie 1387: not the other way around, which doesn't work.
1388: .Pp
1389: For loops are expanded before tests, so a fragment such as:
1.57 jmc 1390: .Bd -literal -offset indent
1.17 espie 1391: \&.for TMACHINE in ${SHARED_ARCHS}
1.64 mbalmer 1392: \&.if ${TMACHINE} == ${MACHINE}
1.17 espie 1393: ...
1394: \&.endif
1.32 ericj 1395: \&.endfor
1.17 espie 1396: .Ed
1.25 espie 1397: .Pp
1.17 espie 1398: won't work, and should be rewritten the other way around.
1.21 espie 1399: .Pp
1.31 aaron 1400: When handling pre-BSD 4.4 archives,
1.21 espie 1401: .Nm
1402: may erroneously mark archive members as out of date if the archive name
1403: was truncated.
1.26 espie 1404: .Pp
1.57 jmc 1405: The handling of
1406: .Sq ;\&
1407: and other special characters in tests may be utterly bogus.
1.28 aaron 1408: For instance, in
1.57 jmc 1409: .Bd -literal -offset indent
1.25 espie 1410: \&A=abcd;c.c
1411: \&.if ${A:R} == "abcd;c"
1412: .Ed
1413: .Pp
1414: the test will never match, even though the value is correct.
1.26 espie 1415: .Pp
1.28 aaron 1416: The conditional handler is incredibly lame.
1417: Junk such as
1.57 jmc 1418: .Pp
1419: .Dl \&.if defined anything goes (A)
1.26 espie 1420: .Pp
1421: will be accepted silently.
1.25 espie 1422: .Pp
1.57 jmc 1423: In a .for loop, only the variable value is used; assignments will be
1.25 espie 1424: evaluated later, e.g., in
1.57 jmc 1425: .Bd -literal -offset indent
1.25 espie 1426: \&.for I in a b c d
1427: I:=${I:S/a/z}
1428: A+=$I
1429: \&.endfor
1430: .Ed
1.57 jmc 1431: .Pp
1432: .Sq A
1433: will evaluate to a b c d after the loop, not z b c d.
1.73 espie 1434: .Pp
1435: .Ic ORDER
1436: is only used in parallel mode, so
1.74 jmc 1437: keep dependency ordered for sequential mode!
1.78 espie 1438: .Pp
1.79 jmc 1439: Distinct target names are treated separately, even though they might
1.78 espie 1440: correspond to the same file in the file system.
1441: This can cause excessive rebuilds of some targets, and bogus
1442: races in parallel mode.
1443: This can also prevent
1444: .Nm
1445: from finding a rule to solve a dependency if the target name is not
1446: exactly the same as the dependency.
1447: .Pp
1448: In parallel mode,
1449: .Fl j Ar n
1450: only limits the number of concurrent makes it knows about.
1451: During recursive invocations, each level will multiply the number
1452: of processes by
1.79 jmc 1453: .Ar n .
1.80 ! bluhm 1454: .Pp
! 1455: The
! 1456: .Va MAKEFILE
! 1457: variable cannot be used reliably.
! 1458: It is a compatibility feature and may get set to the last makefile
! 1459: specified, as it is set by System V make.