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