Annotation of src/usr.bin/make/make.1, Revision 1.234
1.234 ! sjg 1: .\" $NetBSD: make.1,v 1.233 2014/08/23 15:05:40 christos Exp $
1.15 thorpej 2: .\"
1.16 christos 3: .\" Copyright (c) 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.84 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
1.16 christos 30: .\" from: @(#)make.1 8.4 (Berkeley) 3/19/94
1.1 cgd 31: .\"
1.234 ! sjg 32: .Dd August 28, 2014
1.1 cgd 33: .Dt MAKE 1
34: .Os
35: .Sh NAME
36: .Nm make
37: .Nd maintain program dependencies
38: .Sh SYNOPSIS
1.74 wiz 39: .Nm
1.219 christos 40: .Op Fl BeikNnqrstWwX
1.159 sjg 41: .Op Fl C Ar directory
1.1 cgd 42: .Op Fl D Ar variable
43: .Op Fl d Ar flags
44: .Op Fl f Ar makefile
45: .Op Fl I Ar directory
1.104 wiz 46: .Op Fl J Ar private
47: .Op Fl j Ar max_jobs
1.13 christos 48: .Op Fl m Ar directory
1.44 sommerfe 49: .Op Fl T Ar file
1.16 christos 50: .Op Fl V Ar variable
1.1 cgd 51: .Op Ar variable=value
52: .Op Ar target ...
53: .Sh DESCRIPTION
1.25 lukem 54: .Nm
1.1 cgd 55: is a program designed to simplify the maintenance of other programs.
56: Its input is a list of specifications as to the files upon which programs
57: and other files depend.
1.128 dsl 58: If no
59: .Fl f Ar makefile
60: makefile option is given,
61: .Nm
62: will try to open
1.1 cgd 63: .Ql Pa makefile
1.128 dsl 64: then
1.1 cgd 65: .Ql Pa Makefile
1.128 dsl 66: in order to find the specifications.
1.1 cgd 67: If the file
68: .Ql Pa .depend
69: exists, it is read (see
1.66 wiz 70: .Xr mkdep 1 ) .
1.1 cgd 71: .Pp
72: This manual page is intended as a reference document only.
73: For a more thorough description of
1.25 lukem 74: .Nm
1.1 cgd 75: and makefiles, please refer to
1.197 dholland 76: .%T "PMake \- A Tutorial" .
1.1 cgd 77: .Pp
1.128 dsl 78: .Nm
79: will prepend the contents of the
80: .Va MAKEFLAGS
81: environment variable to the command line arguments before parsing them.
82: .Pp
1.1 cgd 83: The options are as follows:
84: .Bl -tag -width Ds
1.16 christos 85: .It Fl B
1.10 christos 86: Try to be backwards compatible by executing a single shell per command and
87: by executing the commands to make the sources of a dependency line in sequence.
1.159 sjg 88: .It Fl C Ar directory
89: Change to
90: .Ar directory
91: before reading the makefiles or doing anything else.
92: If multiple
93: .Fl C
94: options are specified, each is interpreted relative to the previous one:
95: .Fl C Pa / Fl C Pa etc
96: is equivalent to
97: .Fl C Pa /etc .
1.1 cgd 98: .It Fl D Ar variable
1.8 christos 99: Define
100: .Ar variable
1.1 cgd 101: to be 1, in the global context.
1.128 dsl 102: .It Fl d Ar [-]flags
1.1 cgd 103: Turn on debugging, and specify which portions of
1.25 lukem 104: .Nm
1.1 cgd 105: are to print debugging information.
1.128 dsl 106: Unless the flags are preceded by
1.194 sjg 107: .Ql \-
1.128 dsl 108: they are added to the
109: .Va MAKEFLAGS
110: environment variable and will be processed by any child make processes.
1.141 apb 111: By default, debugging information is printed to standard error,
1.138 apb 112: but this can be changed using the
1.140 wiz 113: .Ar F
1.138 apb 114: debugging flag.
1.139 apb 115: The debugging output is always unbuffered; in addition, if debugging
116: is enabled but debugging output is not directed to standard output,
117: then the standard output is line buffered.
1.1 cgd 118: .Ar Flags
119: is one or more of the following:
120: .Bl -tag -width Ds
121: .It Ar A
122: Print all possible debugging information;
123: equivalent to specifying all of the debugging flags.
124: .It Ar a
125: Print debugging information about archive searching and caching.
1.147 christos 126: .It Ar C
127: Print debugging information about current working directory.
1.1 cgd 128: .It Ar c
129: Print debugging information about conditional evaluation.
130: .It Ar d
131: Print debugging information about directory searching and caching.
1.88 jmmv 132: .It Ar e
133: Print debugging information about failed commands and targets.
1.138 apb 134: .It Ar F Ns Oo Sy \&+ Oc Ns Ar filename
135: Specify where debugging output is written.
136: This must be the last flag, because it consumes the remainder of
137: the argument.
138: If the character immediately after the
139: .Ql F
140: flag is
141: .Ql \&+ ,
142: then the file will be opened in append mode;
143: otherwise the file will be overwritten.
144: If the file name is
145: .Ql stdout
146: or
147: .Ql stderr
148: then debugging output will be written to the
149: standard output or standard error output file descriptors respectively
150: (and the
151: .Ql \&+
152: option has no effect).
153: Otherwise, the output will be written to the named file.
154: If the file name ends
1.128 dsl 155: .Ql .%d
156: then the
157: .Ql %d
158: is replaced by the pid.
1.87 jmmv 159: .It Ar f
160: Print debugging information about loop evaluation.
1.1 cgd 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
1.93 dsl 165: on error.
1.92 dsl 166: .It Ar "g3"
167: Print the input graph before exiting on error.
1.1 cgd 168: .It Ar j
169: Print debugging information about running multiple shells.
1.135 sjg 170: .It Ar l
171: Print commands in Makefiles regardless of whether or not they are prefixed by
1.137 wiz 172: .Ql @
1.135 sjg 173: or other "quiet" flags.
174: Also known as "loud" behavior.
1.180 sjg 175: .It Ar M
176: Print debugging information about "meta" mode decisions about targets.
1.1 cgd 177: .It Ar m
178: Print debugging information about making targets, including modification
179: dates.
1.111 jmc 180: .It Ar n
1.154 apb 181: Don't delete the temporary command scripts created when running commands.
182: These temporary scripts are created in the directory
183: referred to by the
184: .Ev TMPDIR
185: environment variable, or in
1.112 wiz 186: .Pa /tmp
1.154 apb 187: if
188: .Ev TMPDIR
189: is unset or set to the empty string.
190: The temporary scripts are created by
191: .Xr mkstemp 3 ,
1.112 wiz 192: and have names of the form
1.154 apb 193: .Pa makeXXXXXX .
1.123 wiz 194: .Em NOTE :
1.156 snj 195: This can create many files in
1.154 apb 196: .Ev TMPDIR
197: or
198: .Pa /tmp ,
1.123 wiz 199: so use with care.
1.119 dsl 200: .It Ar p
201: Print debugging information about makefile parsing.
1.1 cgd 202: .It Ar s
203: Print debugging information about suffix-transformation rules.
204: .It Ar t
205: Print debugging information about target list maintenance.
1.205 sjg 206: .It Ar V
207: Force the
208: .Fl V
1.206 wiz 209: option to print raw values of variables.
1.1 cgd 210: .It Ar v
211: Print debugging information about variable assignment.
1.49 sjg 212: .It Ar x
1.57 wiz 213: Run shell commands with
214: .Fl x
215: so the actual commands are printed as they are executed.
1.1 cgd 216: .El
217: .It Fl e
1.68 perry 218: Specify that environment variables override macro assignments within
1.1 cgd 219: makefiles.
220: .It Fl f Ar makefile
221: Specify a makefile to read instead of the default
1.103 wiz 222: .Ql Pa makefile .
1.1 cgd 223: If
224: .Ar makefile
225: is
226: .Ql Fl ,
227: standard input is read.
1.103 wiz 228: Multiple makefiles may be specified, and are read in the order specified.
1.1 cgd 229: .It Fl I Ar directory
230: Specify a directory in which to search for makefiles and included makefiles.
1.13 christos 231: The system makefile directory (or directories, see the
232: .Fl m
233: option) is automatically included as part of this list.
1.1 cgd 234: .It Fl i
235: Ignore non-zero exit of shell commands in the makefile.
236: Equivalent to specifying
237: .Ql Fl
238: before each command line in the makefile.
1.44 sommerfe 239: .It Fl J Ar private
240: This option should
241: .Em not
242: be specified by the user.
243: .Pp
244: When the
245: .Ar j
246: option is in use in a recursive build, this option is passed by a make
247: to child makes to allow all the make processes in the build to
248: cooperate to avoid overloading the system.
1.1 cgd 249: .It Fl j Ar max_jobs
250: Specify the maximum number of jobs that
1.25 lukem 251: .Nm
1.67 grant 252: may have running at any one time.
1.180 sjg 253: The value is saved in
254: .Va .MAKE.JOBS .
1.67 grant 255: Turns compatibility mode off, unless the
1.11 christos 256: .Ar B
257: flag is also specified.
1.148 christos 258: When compatibility mode is off, all commands associated with a
259: target are executed in a single shell invocation as opposed to the
260: traditional one shell invocation per line.
261: This can break traditional scripts which change directories on each
262: command invocation and then expect to start with a fresh environment
263: on the next line.
264: It is more efficient to correct the scripts rather than turn backwards
265: compatibility on.
1.1 cgd 266: .It Fl k
267: Continue processing after errors are encountered, but only on those targets
268: that do not depend on the target whose creation caused the error.
1.13 christos 269: .It Fl m Ar directory
270: Specify a directory in which to search for sys.mk and makefiles included
1.99 wiz 271: via the
272: .Ao Ar file Ac Ns -style
273: include statement.
1.98 chuck 274: The
275: .Fl m
276: option can be used multiple times to form a search path.
1.13 christos 277: This path will override the default system include path: /usr/share/mk.
278: Furthermore the system include path will be appended to the search path used
1.99 wiz 279: for
280: .Qo Ar file Qc Ns -style
281: include statements (see the
1.13 christos 282: .Fl I
283: option).
1.98 chuck 284: .Pp
285: If a file or directory name in the
286: .Fl m
1.99 wiz 287: argument (or the
288: .Ev MAKESYSPATH
289: environment variable) starts with the string
290: .Qq \&.../
291: then
292: .Nm
293: will search for the specified file or directory named in the remaining part
294: of the argument string.
295: The search starts with the current directory of
1.98 chuck 296: the Makefile and then works upward towards the root of the filesystem.
1.99 wiz 297: If the search is successful, then the resulting directory replaces the
298: .Qq \&.../
299: specification in the
1.98 chuck 300: .Fl m
1.99 wiz 301: argument.
302: If used, this feature allows
1.98 chuck 303: .Nm
304: to easily search in the current source tree for customized sys.mk files
1.99 wiz 305: (e.g., by using
306: .Qq \&.../mk/sys.mk
307: as an argument).
1.1 cgd 308: .It Fl n
1.45 sommerfe 309: Display the commands that would have been executed, but do not
310: actually execute them unless the target depends on the .MAKE special
1.64 wiz 311: source (see below).
1.45 sommerfe 312: .It Fl N
313: Display the commands which would have been executed, but do not
314: actually execute any of them; useful for debugging top-level makefiles
315: without descending into subdirectories.
1.1 cgd 316: .It Fl q
317: Do not execute any commands, but exit 0 if the specified targets are
318: up-to-date and 1, otherwise.
319: .It Fl r
320: Do not use the built-in rules specified in the system makefile.
321: .It Fl s
322: Do not echo any commands as they are executed.
323: Equivalent to specifying
324: .Ql Ic @
325: before each command line in the makefile.
1.44 sommerfe 326: .It Fl T Ar tracefile
327: When used with the
1.48 wiz 328: .Fl j
1.44 sommerfe 329: flag,
330: append a trace record to
331: .Ar tracefile
332: for each job started and completed.
1.1 cgd 333: .It Fl t
334: Rather than re-building a target as specified in the makefile, create it
335: or update its modification time to make it appear up-to-date.
1.16 christos 336: .It Fl V Ar variable
337: Print
1.74 wiz 338: .Nm Ns 's
1.16 christos 339: idea of the value of
340: .Ar variable ,
341: in the global context.
342: Do not build any targets.
343: Multiple instances of this option may be specified;
344: the variables will be printed one per line,
345: with a blank line for each null or undefined variable.
1.85 sjg 346: If
347: .Ar variable
348: contains a
349: .Ql \&$
350: then the value will be expanded before printing.
1.46 christos 351: .It Fl W
352: Treat any warnings during makefile parsing as errors.
1.234 ! sjg 353: .It Fl w
! 354: Print entering and leaving directory messages, pre and post processing.
1.75 thorpej 355: .It Fl X
356: Don't export variables passed on the command line to the environment
357: individually.
358: Variables passed on the command line are still exported
359: via the
360: .Va MAKEFLAGS
361: environment variable.
362: This option may be useful on systems which have a small limit on the
363: size of command arguments.
1.1 cgd 364: .It Ar variable=value
365: Set the value of the variable
366: .Ar variable
367: to
368: .Ar value .
1.75 thorpej 369: Normally, all values passed on the command line are also exported to
370: sub-makes in the environment.
371: The
372: .Fl X
373: flag disables this behavior.
1.101 wiz 374: Variable assignments should follow options for POSIX compatibility
1.100 ross 375: but no ordering is enforced.
1.1 cgd 376: .El
377: .Pp
1.6 cgd 378: There are seven different types of lines in a makefile: file dependency
1.1 cgd 379: specifications, shell commands, variable assignments, include statements,
1.6 cgd 380: conditional directives, for loops, and comments.
1.1 cgd 381: .Pp
382: In general, lines may be continued from one line to the next by ending
383: them with a backslash
384: .Pq Ql \e .
1.231 christos 385: For any line that is not a shell command line (i.e. it does not begin
386: with a tab), the backslash, the following newline character, and initial
387: whitespace on the following line are compressed into a single space.
388: On command lines the backslash and the newline are left intact and
389: if the following line begins with tab(s), the first one is removed.
1.1 cgd 390: .Sh FILE DEPENDENCY SPECIFICATIONS
1.233 christos 391: Dependency lines consist of one or more targets, an operator, zero
392: or more sources, and an optional semicolon followed by a command.
1.137 wiz 393: This creates a relationship where the targets
394: .Dq depend
395: on the sources
1.1 cgd 396: and are usually created from them.
1.233 christos 397: .Bd -literal -offset indent
398: target [target...]: [source...] [;command]
399: .Ed
400: .Pp
1.1 cgd 401: The exact relationship between the target and the source is determined
1.233 christos 402: by the operator, presented by a colon in the example, that separates
403: them.
404: A target may only appear on the left hand side of one type of operator
405: in a single makefile.
1.1 cgd 406: The three operators are as follows:
407: .Bl -tag -width flag
408: .It Ic \&:
409: A target is considered out-of-date if its modification time is less than
410: those of any of its sources.
411: Sources for a target accumulate over dependency lines when this operator
412: is used.
413: The target is removed if
1.25 lukem 414: .Nm
1.1 cgd 415: is interrupted.
1.233 christos 416: This is the only operator available in POSIX compatible makefiles.
1.1 cgd 417: .It Ic \&!
418: Targets are always re-created, but not until all sources have been
419: examined and re-created as necessary.
420: Sources for a target accumulate over dependency lines when this operator
421: is used.
422: The target is removed if
1.25 lukem 423: .Nm
1.1 cgd 424: is interrupted.
425: .It Ic \&::
426: If no sources are specified, the target is always re-created.
427: Otherwise, a target is considered out-of-date if any of its sources has
428: been modified more recently than the target.
429: Sources for a target do not accumulate over dependency lines when this
1.233 christos 430: operator is used, only the depencies in the first rule encountered are
431: used.
432: The commands from the rules do accumulate and are executed in the order
433: the rules were defined if the target needs to be updated.
1.1 cgd 434: The target will not be removed if
1.25 lukem 435: .Nm
1.1 cgd 436: is interrupted.
437: .El
438: .Pp
1.233 christos 439: The optional semicolon separated command in the dependency line is
440: strongly discouraged except to specify an empty rule to nullify
441: an existing suffix transformation rule (see
442: .Ic .SUFFIXES ) .
443: More information on commands is in the section
444: .Sx SHELL COMMANDS .
445: .Pp
1.1 cgd 446: Targets and sources may contain the shell wildcard values
1.80 wiz 447: .Ql \&? ,
1.1 cgd 448: .Ql * ,
1.103 wiz 449: .Ql [] ,
1.1 cgd 450: and
451: .Ql {} .
452: The values
1.80 wiz 453: .Ql \&? ,
1.103 wiz 454: .Ql * ,
1.1 cgd 455: and
456: .Ql []
457: may only be used as part of the final
458: component of the target or source, and must be used to describe existing
459: files.
460: The value
461: .Ql {}
462: need not necessarily be used to describe existing files.
463: Expansion is in directory order, not alphabetically as done in the shell.
1.233 christos 464: .Ss Suffix transformation rules
465: Suffix transformation rules allow
466: .Nm
467: to infer the commands used to bring targets up to date based on their
468: suffixes.
469: These are also known as inference rules or just suffix rules.
470: A suffix transformation rule is a rule whose dependency line has either
471: of these forms:
472: .Bd -literal -compact -offset indent
473: \&.s1.s2: [source...]
474: \&.s1: [source...]
475: .Ed
476: Additionally, both
477: .Pa .s1
478: and
479: .Pa .s2
480: need to be defined as dependencies on the special target
481: .Ic .SUFFIXES .
482: .Pp
483: A suffix transformation rule tells
484: .Nm
485: that any file named
486: .Pa file.s2 Pq the first form
487: or
488: .Pa file Pq the second form
489: can be made with the provided rules from a file named
490: .Pa file.s1 .
491: Suffix transformation rules are only tried when there is no explicit
492: rule to make a target.
493: Single suffix rules (ther second form) are only tried if the target has
494: no known suffix.
495: Suffixes are tried in the order they have been specified to the
496: .Ic .SUFFIXES
497: special target.
498: An explicit dependency line with no commands can be used to add more
499: dependencies, while still allowing for the use of the inferred commands.
500: .Pp
501: In POSIX compatible makefiles there are no sources listed in
502: a suffix transformation rule definition and only a single transformation
503: step is tried.
504: This implementation allows dependencies to be listed and handles them
505: as additional dependencies on any file that gets created with the suffix
506: transformation.
507: This can be combined with
508: .Em dynamic sources .
509: Transformations can also be chained: if
510: .Pa file.s1
511: could be made from
512: .Pa file.s2
513: but it does not exist,
514: .Nm
515: will try the suffix transformation rules which could make it from any
516: .Pa file.s3
517: and so forth.
518: The shortest path from an existing file or an explicit rule will be
519: chosen.
520: .Pp
521: Usable commands for these rules cannot be written without knowing what
522: the actual sources and targets are.
523: This information is provided with the local variables listed in the
524: section
525: .Dq Variable classes .
526: .Ss Archive member targets
527: A target or a source of the form
528: .Pa archive(member)
529: refers to file
530: .Pa member
531: in an
532: .Ic ar
533: library archive named
534: .Pa archive .
535: The modification time stored for the member in the archive is used in
536: up-to-dateness checks.
537: In POSIX compatible makefiles the member file must be an object file and
538: have the suffix
539: .Pa .o .
540: .Pp
541: Library members can also be inferred.
542: The POSIX compatible way is to define a suffix transformation rule with
543: the name
544: .Pa .s1.a ,
545: as
546: .Pa .a
547: is the traditional suffix of such archives.
548: This rule is used to update
549: .Pa member.o
550: from the file
551: .Pa member.s1
552: in any archive file,
553: regardless of any suffix the archive file may or may not have.
554: .Pp
555: As an extension, if the POSIX compatible behavior does not yield commands,
556: .Nm
557: looks if it could make the member if it were a regular file.
558: If it can, then it tries to find a transformation rule from that file
559: to the suffix of the archive for adding the file in to the archive.
1.1 cgd 560: .Sh SHELL COMMANDS
1.233 christos 561: Each target may have associated with it a series of shell commands, which
562: immediately follow the dependency line.
563: These commands are normally used to create a file corresponding to
564: the target name.
565: The first command line (or only line, if there is only one) may be on
566: the same line with the dependency information, separated by a semicolon.
567: Every command line in this script following the dependency line
1.1 cgd 568: .Em must
569: be preceded by a tab.
1.233 christos 570: Placing commands on the dependency line is not a good practice.
571:
572: A target name may appear on the left hand side of the dependency
573: operator in any number of dependency lines.
574: Only one of these dependency specifications may be followed by a creation
575: script, unless the
1.91 lukem 576: .Ql Ic \&::
1.1 cgd 577: operator is used.
1.233 christos 578: If more than one rule with commands is encountered, the last one is used.
579: Overriding rules has its use cases, but sometimes it can happen by accident.
580: A notice of each overridden rule is included in the parsing debugging
581: category.
1.1 cgd 582: .Pp
1.102 sjg 583: If the first characters of the command line are any combination of
584: .Ql Ic @ ,
1.103 wiz 585: .Ql Ic + ,
1.102 sjg 586: or
1.1 cgd 587: .Ql Ic \- ,
588: the command is treated specially.
589: A
590: .Ql Ic @
591: causes the command not to be echoed before it is executed.
592: A
1.102 sjg 593: .Ql Ic +
594: causes the command to be executed even when
595: .Fl n
596: is given.
597: This is similar to the effect of the .MAKE special source,
598: except that the effect can be limited to a single line of a script.
599: A
1.1 cgd 600: .Ql Ic \-
601: causes any non-zero exit status of the command line to be ignored.
1.210 sjg 602: .Pp
603: When
604: .Nm
605: is run in jobs mode with
606: .Fl j Ar max_jobs ,
607: the entire script for the target is fed to a
608: single instance of the shell.
609: .Pp
610: In compatibility (non-jobs) mode, each command is run in a separate process.
611: If the command contains any shell meta characters
612: .Pq Ql #=|^(){};&<>*?[]:$`\e\en
613: it will be passed to the shell, otherwise
614: .Nm
615: will attempt direct execution.
616: .Pp
617: Since
618: .Nm
619: will
620: .Xr chdir 2
621: to
622: .Ql Va .OBJDIR
623: before executing any targets, each child process
624: starts with that as its current working directory.
625: .Pp
626: Makefiles should be written so that the mode of
627: .Nm
628: operation does not change their behavior.
629: For example, any command which needs to use
630: .Dq cd
631: or
1.231 christos 632: .Dq chdir
633: without side-effects should be put in parenthesis so they are executed
634: in a subshell:
1.210 sjg 635: .Bd -literal -offset indent
636:
637: avoid-chdir-side-effects:
638: @echo Building $@ in `pwd`
1.231 christos 639: @(cd ${.CURDIR} && ${MAKE} $@)
1.210 sjg 640: @echo Back in `pwd`
641:
642: ensure-one-shell-regardless-of-mode:
643: @echo Building $@ in `pwd`; \\
1.231 christos 644: (cd ${.CURDIR} && ${MAKE} $@); \\
1.210 sjg 645: echo Back in `pwd`
646: .Ed
1.231 christos 647: .Pp
648: The backslash and the following newline are retained in the input to
649: the shell, but if the next line starts with tab(s), the first one of
650: those is removed.
651: This allows you to align the commands in the rule without introducing
652: unwanted whitespace into the command line itself.
653: What happens to the backslash-newline pair is up to the shell.
654: The standard shell,
655: .Xr sh 1 ,
656: removes them both elsewhere than in single quotes, effectively catenating
657: the two lines.
658: The following examples demonstrate escaped newlines in command lines.
1.233 christos 659: .Bl -column -offset indent " echo \*qfoo\\xxxx" "| cd dir \\xxxx"
1.231 christos 660: .It "echo-foobar:" Ta "| syntax-error:"
661: .It " echo \*qfoo\\" Ta "| for i in a b\\"
662: .It " bar\*q" Ta "| do\\"
663: .It Ta "| echo $i\\"
664: .It Ta "| done"
665: .El
666: .Pp
667: The first one is an unnecessarily contrived way of doing
668: .Bd -compact -offset indent
669: .Ic "echo \*qfoobar\*q"
670: .Ed
671: The second one demonstrates why the semicolon is required in many places
672: where in a similar looking regular shell script it wouldn't be.
673: After the shell has removed the backslash newline pairs, the result
674: would be the syntactically incorrect command
675: .Bd -compact -offset indent
676: .Ic "for i in a bdo echo $idone"
677: .Ed
1.1 cgd 678: .Sh VARIABLE ASSIGNMENTS
679: Variables in make are much like variables in the shell, and, by tradition,
680: consist of all upper-case letters.
1.91 lukem 681: .Ss Variable assignment modifiers
1.1 cgd 682: The five operators that can be used to assign values to variables are as
683: follows:
684: .Bl -tag -width Ds
685: .It Ic \&=
686: Assign the value to the variable.
687: Any previous value is overridden.
688: .It Ic \&+=
689: Append the value to the current value of the variable.
690: .It Ic \&?=
691: Assign the value to the variable if it is not already defined.
692: .It Ic \&:=
693: Assign with expansion, i.e. expand the value before assigning it
694: to the variable.
695: Normally, expansion is not done until the variable is referenced.
1.124 sjg 696: .Em NOTE :
697: References to undefined variables are
698: .Em not
1.125 wiz 699: expanded.
700: This can cause problems when variable modifiers are used.
1.1 cgd 701: .It Ic \&!=
702: Expand the value and pass it to the shell for execution and assign
703: the result to the variable.
704: Any newlines in the result are replaced with spaces.
705: .El
706: .Pp
707: Any white-space before the assigned
708: .Ar value
709: is removed; if the value is being appended, a single space is inserted
710: between the previous contents of the variable and the appended value.
711: .Pp
712: Variables are expanded by surrounding the variable name with either
713: curly braces
714: .Pq Ql {}
1.7 mycroft 715: or parentheses
1.1 cgd 716: .Pq Ql ()
717: and preceding it with
718: a dollar sign
719: .Pq Ql \&$ .
720: If the variable name contains only a single letter, the surrounding
1.7 mycroft 721: braces or parentheses are not required.
1.1 cgd 722: This shorter form is not recommended.
723: .Pp
1.149 dsl 724: If the variable name contains a dollar, then the name itself is expanded first.
725: This allows almost arbitrary variable names, however names containing dollar,
726: braces, parenthesis, or whitespace are really best avoided!
727: .Pp
728: If the result of expanding a variable contains a dollar sign
729: .Pq Ql \&$
730: the string is expanded again.
731: .Pp
1.175 christos 732: Variable substitution occurs at three distinct times, depending on where
1.1 cgd 733: the variable is being used.
1.175 christos 734: .Bl -enum
1.176 wiz 735: .It
1.1 cgd 736: Variables in dependency lines are expanded as the line is read.
1.175 christos 737: .It
1.1 cgd 738: Variables in shell commands are expanded when the shell command is
739: executed.
1.175 christos 740: .It
741: .Dq .for
1.176 wiz 742: loop index variables are expanded on each loop iteration.
743: Note that other variables are not expanded inside loops so
1.175 christos 744: the following example code:
745: .Bd -literal -offset indent
746:
747: .Dv .for i in 1 2 3
748: a+= ${i}
749: j= ${i}
750: b+= ${j}
751: .Dv .endfor
752:
753: all:
1.176 wiz 754: @echo ${a}
1.175 christos 755: @echo ${b}
756:
757: .Ed
758: will print:
759: .Bd -literal -offset indent
760: 1 2 3
761: 3 3 3
762:
763: .Ed
764: Because while ${a} contains
765: .Dq 1 2 3
766: after the loop is executed, ${b}
767: contains
768: .Dq ${j} ${j} ${j}
769: which expands to
770: .Dq 3 3 3
771: since after the loop completes ${j} contains
772: .Dq 3 .
773: .El
1.91 lukem 774: .Ss Variable classes
1.1 cgd 775: The four different classes of variables (in order of increasing precedence)
776: are:
777: .Bl -tag -width Ds
778: .It Environment variables
779: Variables defined as part of
1.74 wiz 780: .Nm Ns 's
1.1 cgd 781: environment.
782: .It Global variables
783: Variables defined in the makefile or in included makefiles.
784: .It Command line variables
785: Variables defined as part of the command line.
786: .It Local variables
1.231 christos 787: There are seven variables that are defined specific to a certain target.
788: Five of these are defined in POSIX but only in their short form.
789: The variables are as follows:
1.1 cgd 790: .Bl -tag -width ".ARCHIVE"
791: .It Va .ALLSRC
792: The list of all sources for this target; also known as
1.62 ross 793: .Ql Va \&\*[Gt] .
1.231 christos 794: This variable is a non-POSIX extension.
1.1 cgd 795: .It Va .ARCHIVE
1.231 christos 796: The name of the archive file; also known as
797: .Ql Va \&! .
798: This variable is a non-POSIX extension.
1.1 cgd 799: .It Va .IMPSRC
1.233 christos 800: In suffix-transformation rules it is the name of the source from which the
1.137 wiz 801: target is to be transformed (the
802: .Dq implied
1.233 christos 803: source).
804: In explicit rules it is the name of the first dependency from the dependency
805: line of the explicit rule or in the absence of such a prerequisite, the first
806: dependency otherwise encountered.
807: If the source was actually found via path search, it is the resulting path
808: name.
809: Also known as
1.62 ross 810: .Ql Va \&\*[Lt] .
1.1 cgd 811: .It Va .MEMBER
1.231 christos 812: The name of the archive member; also known as
813: .Ql Va % .
1.233 christos 814: It is only defined for
815: .Pa archive(member)
816: targets or in inference rules used to make such targets.
1.1 cgd 817: .It Va .OODATE
818: The list of sources for this target that were deemed out-of-date; also
819: known as
820: .Ql Va \&? .
821: .It Va .PREFIX
1.177 dholland 822: The file prefix of the target, containing only the file portion, no suffix
1.1 cgd 823: or preceding directory components; also known as
824: .Ql Va * .
1.233 christos 825: For an archive member rule it is the prefix of the member.
1.231 christos 826: .Pp
827: POSIX only requires this variable to be availabe for suffix transformation
828: rules, but this implementation makes it available for all targets.
829: If the target does not have a known suffix (see
830: .Ic .SUFFIXES ) ,
831: it is equivalent to
832: .Ql Va .TARGET .
1.1 cgd 833: .It Va .TARGET
834: The name of the target; also known as
835: .Ql Va @ .
1.233 christos 836: In an explicit rule for
837: .Pa archive(member.o)
838: or in a POSIX style
839: .Pa .s1.a
840: suffix transformation rule this is equal to
841: .Ql Va .ARCHIVE .
1.1 cgd 842: .El
843: .Pp
1.231 christos 844: To increase readability, the shorter forms
845: .Ql ( Va @ ,
846: .Ql Va \&! ,
847: .Ql Va % ,
1.80 wiz 848: .Ql Va \&? ,
1.231 christos 849: .Ql Va \*[Lt] ,
850: .Ql Va \*[Gt] ,
1.1 cgd 851: and
1.231 christos 852: .Ql Va * )
853: should only be used when compatibility with POSIX or other implementations
854: is desired.
855: For compatibility with POSIX, all of the short forms may also be written
856: with an appended uppercase
857: .Ql D
858: or
859: .Ql F ,
860: e.g.\&
861: .Ql @D
862: or
863: .Ql *F .
864: These modified versions replace each word in the expansion with their
865: .Em directory part ( Ql D )
866: or
867: .Em filename part ( Ql F ) ,
868: and are exactly equivalent to the
869: .Cm \&:H
1.1 cgd 870: and
1.231 christos 871: .Cm \&:T
872: variable modifiers, respectively.
1.1 cgd 873: .Pp
874: Four of the local variables may be used in sources on dependency lines
875: because they expand to the proper value for each target on the line.
876: These variables are
877: .Ql Va .TARGET ,
878: .Ql Va .PREFIX ,
879: .Ql Va .ARCHIVE ,
880: and
881: .Ql Va .MEMBER .
1.233 christos 882: Dependencies based on these variables are called
883: .Em dynamic sources
884: and they are not POSIX compatible.
1.59 bgrayson 885: .El
1.145 christos 886: .Ss Additional built-in variables
1.1 cgd 887: In addition,
1.25 lukem 888: .Nm
1.1 cgd 889: sets or knows about the following variables:
1.50 sjg 890: .Bl -tag -width .MAKEOVERRIDES
1.1 cgd 891: .It Va \&$
892: A single dollar sign
893: .Ql \&$ ,
894: i.e.
895: .Ql \&$$
896: expands to a single dollar
897: sign.
1.56 tv 898: .It Va .ALLTARGETS
1.67 grant 899: The list of all targets encountered in the Makefile.
900: If evaluated during
1.56 tv 901: Makefile parsing, lists only those targets encountered thus far.
1.1 cgd 902: .It Va .CURDIR
903: A path to the directory where
1.25 lukem 904: .Nm
1.1 cgd 905: was executed.
1.117 lukem 906: Refer to the description of
907: .Ql Ev PWD
908: for more details.
1.230 sjg 909: .It Va .INCLUDEDFROMDIR
910: The directory of the file this Makefile was included from.
911: .It Va .INCLUDEDFROMFILE
912: The filename of the file this Makefile was included from.
1.78 christos 913: .It Ev MAKE
1.55 tv 914: The name that
915: .Nm
1.89 sjg 916: was executed with
917: .Pq Va argv[0] .
1.126 reed 918: For compatibility
1.78 christos 919: .Nm
920: also sets
921: .Va .MAKE
922: with the same value.
1.97 lukem 923: The preferred variable to use is the environment variable
1.78 christos 924: .Ev MAKE
925: because it is more compatible with other versions of
926: .Nm
927: and cannot be confused with the special target with the same name.
1.168 sjg 928: .It Va .MAKE.DEPENDFILE
1.169 wiz 929: Names the makefile (default
1.168 sjg 930: .Ql Pa .depend )
931: from which generated dependencies are read.
1.205 sjg 932: .It Va .MAKE.EXPAND_VARIABLES
933: A boolean that controls the default behavior of the
934: .Fl V
935: option.
1.134 sjg 936: .It Va .MAKE.EXPORTED
937: The list of variables exported by
938: .Nm .
1.171 sjg 939: .It Va .MAKE.JOBS
1.172 joerg 940: The argument to the
1.171 sjg 941: .Fl j
942: option.
1.132 sjg 943: .It Va .MAKE.JOB.PREFIX
1.137 wiz 944: If
1.132 sjg 945: .Nm
946: is run with
947: .Ar j
1.137 wiz 948: then output for each target is prefixed with a token
1.132 sjg 949: .Ql --- target ---
950: the first part of which can be controlled via
951: .Va .MAKE.JOB.PREFIX .
1.225 wiz 952: If
1.220 sjg 953: .Va .MAKE.JOB.PREFIX
954: is empty, no token is printed.
1.132 sjg 955: .br
1.137 wiz 956: For example:
1.132 sjg 957: .Li .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}]
958: would produce tokens like
959: .Ql ---make[1234] target ---
960: making it easier to track the degree of parallelism being achieved.
1.1 cgd 961: .It Ev MAKEFLAGS
962: The environment variable
963: .Ql Ev MAKEFLAGS
964: may contain anything that
965: may be specified on
1.74 wiz 966: .Nm Ns 's
1.1 cgd 967: command line.
968: Anything specified on
1.74 wiz 969: .Nm Ns 's
1.1 cgd 970: command line is appended to the
971: .Ql Ev MAKEFLAGS
972: variable which is then
973: entered into the environment for all programs which
1.25 lukem 974: .Nm
1.1 cgd 975: executes.
1.169 wiz 976: .It Va .MAKE.LEVEL
977: The recursion depth of
978: .Nm .
979: The initial instance of
980: .Nm
981: will be 0, and an incremented value is put into the environment
982: to be seen by the next generation.
983: This allows tests like:
984: .Li .if ${.MAKE.LEVEL} == 0
985: to protect things which should only be evaluated in the initial instance of
986: .Nm .
987: .It Va .MAKE.MAKEFILE_PREFERENCE
988: The ordered list of makefile names
989: (default
990: .Ql Pa makefile ,
991: .Ql Pa Makefile )
992: that
993: .Nm
994: will look for.
995: .It Va .MAKE.MAKEFILES
996: The list of makefiles read by
997: .Nm ,
998: which is useful for tracking dependencies.
1.204 sjg 999: Each makefile is recorded only once, regardless of the number of times read.
1.169 wiz 1000: .It Va .MAKE.MODE
1001: Processed after reading all makefiles.
1002: Can affect the mode that
1003: .Nm
1004: runs in.
1.180 sjg 1005: It can contain a number of keywords:
1006: .Bl -hang -width ignore-cmd
1007: .It Pa compat
1.182 wiz 1008: Like
1.184 sjg 1009: .Fl B ,
1.182 wiz 1010: puts
1.180 sjg 1011: .Nm
1012: into "compat" mode.
1013: .It Pa meta
1014: Puts
1015: .Nm
1.182 wiz 1016: into "meta" mode, where meta files are created for each target
1.180 sjg 1017: to capture the command run, the output generated and if
1018: .Xr filemon 4
1019: is available, the system calls which are of interest to
1020: .Nm .
1021: The captured output can be very useful when diagnosing errors.
1.185 sjg 1022: .It Pa curdirOk= Ar bf
1.184 sjg 1023: Normally
1024: .Nm
1025: will not create .meta files in
1026: .Ql Va .CURDIR .
1027: This can be overridden by setting
1.188 wiz 1028: .Va bf
1.184 sjg 1029: to a value which represents True.
1.200 sjg 1030: .It Pa env
1031: For debugging, it can be useful to inlcude the environment
1032: in the .meta file.
1.180 sjg 1033: .It Pa verbose
1034: If in "meta" mode, print a clue about the target being built.
1035: This is useful if the build is otherwise running silently.
1036: The message printed the value of:
1037: .Va .MAKE.META.PREFIX .
1038: .It Pa ignore-cmd
1039: Some makefiles have commands which are simply not stable.
1.182 wiz 1040: This keyword causes them to be ignored for
1.180 sjg 1041: determining whether a target is out of date in "meta" mode.
1042: See also
1043: .Ic .NOMETA_CMP .
1.195 sjg 1044: .It Pa silent= Ar bf
1045: If
1046: .Va bf
1047: is True, when a .meta file is created, mark the target
1.200 sjg 1048: .Ic .SILENT .
1.180 sjg 1049: .El
1.189 sjg 1050: .It Va .MAKE.META.BAILIWICK
1051: In "meta" mode, provides a list of prefixes which
1052: match the directories controlled by
1053: .Nm .
1054: If a file that was generated outside of
1055: .Va .OBJDIR
1056: but within said bailiwick is missing,
1057: the current target is considered out-of-date.
1.180 sjg 1058: .It Va .MAKE.META.CREATED
1059: In "meta" mode, this variable contains a list of all the meta files
1060: updated.
1061: If not empty, it can be used to trigger processing of
1062: .Va .MAKE.META.FILES .
1063: .It Va .MAKE.META.FILES
1064: In "meta" mode, this variable contains a list of all the meta files
1065: used (updated or not).
1.182 wiz 1066: This list can be used to process the meta files to extract dependency
1.180 sjg 1067: information.
1.216 sjg 1068: .It Va .MAKE.META.IGNORE_PATHS
1069: Provides a list of path prefixes that should be ignored;
1070: because the contents are expected to change over time.
1071: The default list includes:
1072: .Ql Pa /dev /etc /proc /tmp /var/run /var/tmp
1.180 sjg 1073: .It Va .MAKE.META.PREFIX
1074: Defines the message printed for each meta file updated in "meta verbose" mode.
1075: The default value is:
1076: .Dl Building ${.TARGET:H:tA}/${.TARGET:T}
1.50 sjg 1077: .It Va .MAKEOVERRIDES
1.57 wiz 1078: This variable is used to record the names of variables assigned to
1079: on the command line, so that they may be exported as part of
1.50 sjg 1080: .Ql Ev MAKEFLAGS .
1.57 wiz 1081: This behaviour can be disabled by assigning an empty value to
1.50 sjg 1082: .Ql Va .MAKEOVERRIDES
1.67 grant 1083: within a makefile.
1084: Extra variables can be exported from a makefile
1.57 wiz 1085: by appending their names to
1.51 sjg 1086: .Ql Va .MAKEOVERRIDES .
1087: .Ql Ev MAKEFLAGS
1.57 wiz 1088: is re-exported whenever
1.51 sjg 1089: .Ql Va .MAKEOVERRIDES
1090: is modified.
1.212 sjg 1091: .It Va .MAKE.PATH_FILEMON
1092: If
1093: .Nm
1.217 wiz 1094: was built with
1.212 sjg 1095: .Xr filemon 4
1096: support, this is set to the path of the device node.
1097: This allows makefiles to test for this support.
1.169 wiz 1098: .It Va .MAKE.PID
1099: The process-id of
1100: .Nm .
1101: .It Va .MAKE.PPID
1102: The parent process-id of
1103: .Nm .
1.55 tv 1104: .It Va MAKE_PRINT_VAR_ON_ERROR
1.57 wiz 1105: When
1.55 tv 1106: .Nm
1107: stops due to an error, it prints its name and the value of
1108: .Ql Va .CURDIR
1.57 wiz 1109: as well as the value of any variables named in
1.55 tv 1110: .Ql Va MAKE_PRINT_VAR_ON_ERROR .
1111: .It Va .newline
1112: This variable is simply assigned a newline character as its value.
1.91 lukem 1113: This allows expansions using the
1114: .Cm \&:@
1115: modifier to put a newline between
1.67 grant 1116: iterations of the loop rather than a space.
1117: For example, the printing of
1.55 tv 1118: .Ql Va MAKE_PRINT_VAR_ON_ERROR
1119: could be done as ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}.
1120: .It Va .OBJDIR
1121: A path to the directory where the targets are built.
1.117 lukem 1122: Its value is determined by trying to
1123: .Xr chdir 2
1124: to the following directories in order and using the first match:
1125: .Bl -enum
1126: .It
1.118 wiz 1127: .Ev ${MAKEOBJDIRPREFIX}${.CURDIR}
1128: .Pp
1.117 lukem 1129: (Only if
1130: .Ql Ev MAKEOBJDIRPREFIX
1131: is set in the environment or on the command line.)
1132: .It
1.118 wiz 1133: .Ev ${MAKEOBJDIR}
1134: .Pp
1.117 lukem 1135: (Only if
1136: .Ql Ev MAKEOBJDIR
1137: is set in the environment or on the command line.)
1138: .It
1139: .Ev ${.CURDIR} Ns Pa /obj. Ns Ev ${MACHINE}
1140: .It
1141: .Ev ${.CURDIR} Ns Pa /obj
1142: .It
1143: .Pa /usr/obj/ Ns Ev ${.CURDIR}
1144: .It
1145: .Ev ${.CURDIR}
1146: .El
1147: .Pp
1148: Variable expansion is performed on the value before it's used,
1149: so expressions such as
1.173 sjg 1150: .Dl ${.CURDIR:S,^/usr/src,/var/obj,}
1.117 lukem 1151: may be used.
1.173 sjg 1152: This is especially useful with
1153: .Ql Ev MAKEOBJDIR .
1.117 lukem 1154: .Pp
1155: .Ql Va .OBJDIR
1156: may be modified in the makefile as a global variable.
1.137 wiz 1157: In all cases,
1.117 lukem 1158: .Nm
1159: will
1160: .Xr chdir 2
1161: to
1162: .Ql Va .OBJDIR
1163: and set
1164: .Ql Ev PWD
1165: to that directory before executing any targets.
1166: .
1.55 tv 1167: .It Va .PARSEDIR
1168: A path to the directory of the current
1169: .Ql Pa Makefile
1170: being parsed.
1171: .It Va .PARSEFILE
1172: The basename of the current
1173: .Ql Pa Makefile
1174: being parsed.
1175: This variable and
1176: .Ql Va .PARSEDIR
1177: are both set only while the
1178: .Ql Pa Makefiles
1179: are being parsed.
1.196 christos 1180: If you want to retain their current values, assign them to a variable
1181: using assignment with expansion:
1182: .Pq Ql Cm \&:= .
1.69 sjg 1183: .It Va .PATH
1.82 wiz 1184: A variable that represents the list of directories that
1.69 sjg 1185: .Nm
1.70 wiz 1186: will search for files.
1187: The search list should be updated using the target
1.69 sjg 1188: .Ql Va .PATH
1189: rather than the variable.
1.16 christos 1190: .It Ev PWD
1191: Alternate path to the current directory.
1.25 lukem 1192: .Nm
1.16 christos 1193: normally sets
1194: .Ql Va .CURDIR
1195: to the canonical path given by
1.48 wiz 1196: .Xr getcwd 3 .
1.16 christos 1197: However, if the environment variable
1198: .Ql Ev PWD
1199: is set and gives a path to the current directory, then
1.25 lukem 1200: .Nm
1.16 christos 1201: sets
1202: .Ql Va .CURDIR
1203: to the value of
1204: .Ql Ev PWD
1.67 grant 1205: instead.
1206: This behaviour is disabled if
1.40 sjg 1207: .Ql Ev MAKEOBJDIRPREFIX
1.117 lukem 1208: is set or
1209: .Ql Ev MAKEOBJDIR
1210: contains a variable transform.
1.16 christos 1211: .Ql Ev PWD
1212: is set to the value of
1213: .Ql Va .OBJDIR
1214: for all programs which
1.25 lukem 1215: .Nm
1.16 christos 1216: executes.
1.179 dholland 1217: .It Ev .TARGETS
1218: The list of targets explicitly specified on the command line, if any.
1.145 christos 1219: .It Ev VPATH
1.146 wiz 1220: Colon-separated
1221: .Pq Dq \&:
1222: lists of directories that
1223: .Nm
1224: will search for files.
1.145 christos 1225: The variable is supported for compatibility with old make programs only,
1226: use
1227: .Ql Va .PATH
1228: instead.
1.1 cgd 1229: .El
1.91 lukem 1230: .Ss Variable modifiers
1.1 cgd 1231: Variable expansion may be modified to select or modify each word of the
1.137 wiz 1232: variable (where a
1233: .Dq word
1234: is white-space delimited sequence of characters).
1.1 cgd 1235: The general format of a variable expansion is as follows:
1236: .Pp
1.120 sjg 1237: .Dl ${variable[:modifier[:...]]}
1.1 cgd 1238: .Pp
1.97 lukem 1239: Each modifier begins with a colon,
1240: which may be escaped with a backslash
1.1 cgd 1241: .Pq Ql \e .
1.120 sjg 1242: .Pp
1243: A set of modifiers can be specified via a variable, as follows:
1244: .Pp
1245: .Dl modifier_variable=modifier[:...]
1246: .Dl ${variable:${modifier_variable}[:...]}
1247: .Pp
1248: In this case the first modifier in the modifier_variable does not
1249: start with a colon, since that must appear in the referencing
1250: variable.
1251: If any of the modifiers in the modifier_variable contain a dollar sign
1252: .Pq Ql $ ,
1253: these must be doubled to avoid early expansion.
1254: .Pp
1.231 christos 1255: Variable modifiers are not POSIX compatible except for
1256: .Ql Cm :old_string=new_string ,
1257: .Ql Cm \&:H
1258: and
1259: .Ql Cm \&:T .
1260: Even these have notable caveats, see their individual descriptions.
1261: .Pp
1.97 lukem 1262: The supported modifiers are:
1.61 ross 1263: .Bl -tag -width EEE
1.91 lukem 1264: .It Cm \&:E
1.1 cgd 1265: Replaces each word in the variable with its suffix.
1.91 lukem 1266: .It Cm \&:H
1.231 christos 1267: Replaces each word in the variable with everything but the last component
1268: .Ql ( "head only" ) .
1269: In POSIX compatible makefiles this modification is only available for local
1270: variables and with different syntax.
1271: It is achieved by writing the variable with an appended
1272: .Ql D ,
1273: e.g.\&
1274: .Ql Va @D .
1.91 lukem 1275: .It Cm \&:M Ns Ar pattern
1.72 uebayasi 1276: Select only those words that match
1277: .Ar pattern .
1.1 cgd 1278: The standard shell wildcard characters
1279: .Pf ( Ql * ,
1.80 wiz 1280: .Ql \&? ,
1.1 cgd 1281: and
1.172 joerg 1282: .Ql Oo Oc )
1.1 cgd 1283: may
1284: be used.
1285: The wildcard characters may be escaped with a backslash
1286: .Pq Ql \e .
1.224 apb 1287: As a consequence of the way values are split into words, matched,
1288: and then joined, a construct like
1289: .Dl ${VAR:M*}
1290: will normalise the inter-word spacing, removing all leading and
1291: trailing space, and converting multiple consecutive spaces
1292: to single spaces.
1293: .
1.91 lukem 1294: .It Cm \&:N Ns Ar pattern
1.1 cgd 1295: This is identical to
1.91 lukem 1296: .Ql Cm \&:M ,
1.1 cgd 1297: but selects all words which do not match
1.72 uebayasi 1298: .Ar pattern .
1.91 lukem 1299: .It Cm \&:O
1.109 wiz 1300: Order every word in variable alphabetically.
1301: To sort words in
1302: reverse order use the
1.108 sjg 1303: .Ql Cm \&:O:[-1..1]
1304: combination of modifiers.
1305: .It Cm \&:Ox
1.109 wiz 1306: Randomize words in variable.
1307: The results will be different each time you are referring to the
1308: modified variable; use the assignment with expansion
1.108 sjg 1309: .Pq Ql Cm \&:=
1.109 wiz 1310: to prevent such behaviour.
1311: For example,
1.108 sjg 1312: .Bd -literal -offset indent
1313: LIST= uno due tre quattro
1314: RANDOM_LIST= ${LIST:Ox}
1315: STATIC_RANDOM_LIST:= ${LIST:Ox}
1316:
1317: all:
1318: @echo "${RANDOM_LIST}"
1319: @echo "${RANDOM_LIST}"
1320: @echo "${STATIC_RANDOM_LIST}"
1321: @echo "${STATIC_RANDOM_LIST}"
1322: .Ed
1.109 wiz 1323: may produce output similar to:
1.108 sjg 1324: .Bd -literal -offset indent
1325: quattro due tre uno
1326: tre due quattro uno
1327: due uno quattro tre
1328: due uno quattro tre
1329: .Ed
1.91 lukem 1330: .It Cm \&:Q
1.17 christos 1331: Quotes every shell meta-character in the variable, so that it can be passed
1332: safely through recursive invocations of
1.74 wiz 1333: .Nm .
1.91 lukem 1334: .It Cm \&:R
1.1 cgd 1335: Replaces each word in the variable with everything but its suffix.
1.187 sjg 1336: .It Cm \&:gmtime
1.188 wiz 1337: The value is a format string for
1.187 sjg 1338: .Xr strftime 3 ,
1.188 wiz 1339: using the current
1.187 sjg 1340: .Xr gmtime 3 .
1.186 joerg 1341: .It Cm \&:hash
1342: Compute a 32bit hash of the value and encode it as hex digits.
1.187 sjg 1343: .It Cm \&:localtime
1.188 wiz 1344: The value is a format string for
1.187 sjg 1345: .Xr strftime 3 ,
1.188 wiz 1346: using the current
1.187 sjg 1347: .Xr localtime 3 .
1.170 sjg 1348: .It Cm \&:tA
1349: Attempt to convert variable to an absolute path using
1350: .Xr realpath 3 ,
1351: if that fails, the value is unchanged.
1.91 lukem 1352: .It Cm \&:tl
1.60 pk 1353: Converts variable to lower-case letters.
1.91 lukem 1354: .It Cm \&:ts Ns Ar c
1.81 sjg 1355: Words in the variable are normally separated by a space on expansion.
1356: This modifier sets the separator to the character
1357: .Ar c .
1358: If
1359: .Ar c
1360: is omitted, then no separator is used.
1.170 sjg 1361: The common escapes (including octal numeric codes), work as expected.
1.91 lukem 1362: .It Cm \&:tu
1.82 wiz 1363: Converts variable to upper-case letters.
1.91 lukem 1364: .It Cm \&:tW
1.89 sjg 1365: Causes the value to be treated as a single word
1366: (possibly containing embedded white space).
1367: See also
1.91 lukem 1368: .Ql Cm \&:[*] .
1369: .It Cm \&:tw
1.89 sjg 1370: Causes the value to be treated as a sequence of
1371: words delimited by white space.
1372: See also
1.91 lukem 1373: .Ql Cm \&:[@] .
1.1 cgd 1374: .Sm off
1.164 joerg 1375: .It Cm \&:S No \&/ Ar old_string No \&/ Ar new_string No \&/ Op Cm 1gW
1.1 cgd 1376: .Sm on
1377: Modify the first occurrence of
1.17 christos 1378: .Ar old_string
1379: in the variable's value, replacing it with
1380: .Ar new_string .
1.1 cgd 1381: If a
1382: .Ql g
1383: is appended to the last slash of the pattern, all occurrences
1384: in each word are replaced.
1.17 christos 1385: If a
1386: .Ql 1
1387: is appended to the last slash of the pattern, only the first word
1388: is affected.
1.89 sjg 1389: If a
1390: .Ql W
1391: is appended to the last slash of the pattern,
1392: then the value is treated as a single word
1393: (possibly containing embedded white space).
1.1 cgd 1394: If
1.17 christos 1395: .Ar old_string
1396: begins with a caret
1.1 cgd 1397: .Pq Ql ^ ,
1.17 christos 1398: .Ar old_string
1.1 cgd 1399: is anchored at the beginning of each word.
1400: If
1.17 christos 1401: .Ar old_string
1.1 cgd 1402: ends with a dollar sign
1403: .Pq Ql \&$ ,
1404: it is anchored at the end of each word.
1405: Inside
1406: .Ar new_string ,
1407: an ampersand
1.62 ross 1408: .Pq Ql \*[Am]
1.1 cgd 1409: is replaced by
1.17 christos 1410: .Ar old_string
1411: (without any
1412: .Ql ^
1413: or
1414: .Ql \&$ ) .
1.1 cgd 1415: Any character may be used as a delimiter for the parts of the modifier
1416: string.
1417: The anchoring, ampersand and delimiter characters may be escaped with a
1418: backslash
1419: .Pq Ql \e .
1420: .Pp
1421: Variable expansion occurs in the normal fashion inside both
1422: .Ar old_string
1423: and
1424: .Ar new_string
1425: with the single exception that a backslash is used to prevent the expansion
1426: of a dollar sign
1.17 christos 1427: .Pq Ql \&$ ,
1.1 cgd 1428: not a preceding dollar sign as is usual.
1.17 christos 1429: .Sm off
1.164 joerg 1430: .It Cm \&:C No \&/ Ar pattern No \&/ Ar replacement No \&/ Op Cm 1gW
1.17 christos 1431: .Sm on
1432: The
1.91 lukem 1433: .Cm \&:C
1.17 christos 1434: modifier is just like the
1.91 lukem 1435: .Cm \&:S
1.37 msaitoh 1436: modifier except that the old and new strings, instead of being
1.223 apb 1437: simple strings, are an extended regular expression (see
1.17 christos 1438: .Xr regex 3 )
1.72 uebayasi 1439: string
1440: .Ar pattern
1.17 christos 1441: and an
1442: .Xr ed 1 Ns \-style
1.72 uebayasi 1443: string
1444: .Ar replacement .
1445: Normally, the first occurrence of the pattern
1446: .Ar pattern
1447: in each word of the value is substituted with
1448: .Ar replacement .
1.67 grant 1449: The
1.17 christos 1450: .Ql 1
1451: modifier causes the substitution to apply to at most one word; the
1452: .Ql g
1453: modifier causes the substitution to apply to as many instances of the
1.72 uebayasi 1454: search pattern
1455: .Ar pattern
1.89 sjg 1456: as occur in the word or words it is found in; the
1457: .Ql W
1458: modifier causes the value to be treated as a single word
1459: (possibly containing embedded white space).
1.67 grant 1460: Note that
1.17 christos 1461: .Ql 1
1462: and
1463: .Ql g
1464: are orthogonal; the former specifies whether multiple words are
1465: potentially affected, the latter whether multiple substitutions can
1466: potentially occur within each affected word.
1.229 apb 1467: .Pp
1468: As for the
1469: .Cm \&:S
1470: modifier, the
1471: .Ar pattern
1472: and
1473: .Ar replacement
1474: are subjected to variable expansion before being parsed as
1475: regular expressions.
1.91 lukem 1476: .It Cm \&:T
1.231 christos 1477: Replaces each word in the variable with its last component
1478: .Ql ( "tail only" ) .
1479: In POSIX compatible makefiles this modification is only available for local
1480: variables and with different syntax.
1481: It is achieved by writing the variable with an appended
1482: .Ql F ,
1483: e.g.\&
1484: .Ql Va @F .
1.91 lukem 1485: .It Cm \&:u
1.43 christos 1486: Remove adjacent duplicate words (like
1.57 wiz 1487: .Xr uniq 1 ) .
1.91 lukem 1488: .Sm off
1489: .It Cm \&:\&? Ar true_string Cm \&: Ar false_string
1490: .Sm on
1.152 dsl 1491: If the variable name (not its value), when parsed as a .if conditional
1492: expression, evaluates to true, return as its value the
1.57 wiz 1493: .Ar true_string ,
1.27 christos 1494: otherwise return the
1.57 wiz 1495: .Ar false_string .
1.152 dsl 1496: Since the variable name is used as the expression, \&:\&? must be the
1497: first modifier after the variable name itself - which will, of course,
1498: usually contain variable expansions.
1.162 dsl 1499: A common error is trying to use expressions like
1500: .Dl ${NUMBERS:M42:?match:no}
1501: which actually tests defined(NUMBERS),
1502: to determine is any words match "42" you need to use something like:
1.183 sjg 1503: .Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} .
1.91 lukem 1504: .It Ar :old_string=new_string
1.1 cgd 1505: This is the
1506: .At V
1.231 christos 1507: style variable substitution, later standardized in POSIX.
1.1 cgd 1508: It must be the last modifier specified.
1.16 christos 1509: If
1.6 cgd 1510: .Ar old_string
1511: or
1512: .Ar new_string
1513: do not contain the pattern matching character
1514: .Ar %
1.16 christos 1515: then it is assumed that they are
1.6 cgd 1516: anchored at the end of each word, so only suffixes or entire
1.67 grant 1517: words may be replaced.
1518: Otherwise
1.6 cgd 1519: .Ar %
1.16 christos 1520: is the substring of
1521: .Ar old_string
1.6 cgd 1522: to be replaced in
1.64 wiz 1523: .Ar new_string .
1.231 christos 1524: The special meaning of
1525: .Ar %
1526: is not POSIX compatible.
1.95 jmc 1527: .Pp
1528: Variable expansion occurs in the normal fashion inside both
1529: .Ar old_string
1530: and
1531: .Ar new_string
1.96 wiz 1532: with the single exception that a backslash is used to prevent the
1533: expansion of a dollar sign
1534: .Pq Ql \&$ ,
1535: not a preceding dollar sign as is usual.
1.91 lukem 1536: .Sm off
1.164 joerg 1537: .It Cm \&:@ Ar temp Cm @ Ar string Cm @
1.91 lukem 1538: .Sm on
1.40 sjg 1539: This is the loop expansion mechanism from the OSF Development
1.67 grant 1540: Environment (ODE) make.
1541: Unlike
1.48 wiz 1542: .Cm \&.for
1.40 sjg 1543: loops expansion occurs at the time of
1.67 grant 1544: reference.
1545: Assign
1.40 sjg 1546: .Ar temp
1547: to each word in the variable and evaluate
1548: .Ar string .
1.48 wiz 1549: The ODE convention is that
1.40 sjg 1550: .Ar temp
1.67 grant 1551: should start and end with a period.
1552: For example.
1.40 sjg 1553: .Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
1.198 sjg 1554: .Pp
1.218 agc 1555: However a single character variable is often more readable:
1.198 sjg 1556: .Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
1.91 lukem 1557: .It Cm \&:U Ns Ar newval
1.40 sjg 1558: If the variable is undefined
1559: .Ar newval
1.63 lukem 1560: is the value.
1561: If the variable is defined, the existing value is returned.
1.67 grant 1562: This is another ODE make feature.
1563: It is handy for setting per-target CFLAGS for instance:
1.40 sjg 1564: .Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
1.63 lukem 1565: If a value is only required if the variable is undefined, use:
1566: .Dl ${VAR:D:Unewval}
1.91 lukem 1567: .It Cm \&:D Ns Ar newval
1.40 sjg 1568: If the variable is defined
1569: .Ar newval
1570: is the value.
1.91 lukem 1571: .It Cm \&:L
1.40 sjg 1572: The name of the variable is the value.
1.91 lukem 1573: .It Cm \&:P
1.40 sjg 1574: The path of the node which has the same name as the variable
1.67 grant 1575: is the value.
1576: If no such node exists or its path is null, then the
1.40 sjg 1577: name of the variable is used.
1.217 wiz 1578: In order for this modifier to work, the name (node) must at least have
1.199 sjg 1579: appeared on the rhs of a dependency.
1.91 lukem 1580: .Sm off
1581: .It Cm \&:\&! Ar cmd Cm \&!
1582: .Sm on
1.40 sjg 1583: The output of running
1584: .Ar cmd
1585: is the value.
1.91 lukem 1586: .It Cm \&:sh
1.40 sjg 1587: If the variable is non-empty it is run as a command and the output
1588: becomes the new value.
1.91 lukem 1589: .It Cm \&::= Ns Ar str
1.48 wiz 1590: The variable is assigned the value
1.41 sjg 1591: .Ar str
1.67 grant 1592: after substitution.
1593: This modifier and its variations are useful in
1.149 dsl 1594: obscure situations such as wanting to set a variable when shell commands
1595: are being parsed.
1.67 grant 1596: These assignment modifiers always expand to
1.41 sjg 1597: nothing, so if appearing in a rule line by themselves should be
1.48 wiz 1598: preceded with something to keep
1.41 sjg 1599: .Nm
1.67 grant 1600: happy.
1.149 dsl 1601: .Pp
1.91 lukem 1602: The
1603: .Ql Cm \&::
1.42 sjg 1604: helps avoid false matches with the
1605: .At V
1.48 wiz 1606: style
1.91 lukem 1607: .Cm \&:=
1.48 wiz 1608: modifier and since substitution always occurs the
1.91 lukem 1609: .Cm \&::=
1.42 sjg 1610: form is vaguely appropriate.
1.91 lukem 1611: .It Cm \&::?= Ns Ar str
1.41 sjg 1612: As for
1.91 lukem 1613: .Cm \&::=
1.41 sjg 1614: but only if the variable does not already have a value.
1.91 lukem 1615: .It Cm \&::+= Ns Ar str
1.48 wiz 1616: Append
1.41 sjg 1617: .Ar str
1618: to the variable.
1.91 lukem 1619: .It Cm \&::!= Ns Ar cmd
1.48 wiz 1620: Assign the output of
1.41 sjg 1621: .Ar cmd
1622: to the variable.
1.91 lukem 1623: .It Cm \&:\&[ Ns Ar range Ns Cm \&]
1.89 sjg 1624: Selects one or more words from the value,
1625: or performs other operations related to the way in which the
1626: value is divided into words.
1627: .Pp
1628: Ordinarily, a value is treated as a sequence of words
1629: delimited by white space.
1630: Some modifiers suppress this behaviour,
1631: causing a value to be treated as a single word
1632: (possibly containing embedded white space).
1633: An empty value, or a value that consists entirely of white-space,
1634: is treated as a single word.
1635: For the purposes of the
1.91 lukem 1636: .Ql Cm \&:[]
1.89 sjg 1637: modifier, the words are indexed both forwards using positive integers
1638: (where index 1 represents the first word),
1639: and backwards using negative integers
1.194 sjg 1640: (where index \-1 represents the last word).
1.89 sjg 1641: .Pp
1642: The
1643: .Ar range
1644: is subjected to variable expansion, and the expanded result is
1645: then interpreted as follows:
1646: .Bl -tag -width index
1.90 jdolecek 1647: .\" :[n]
1.89 sjg 1648: .It Ar index
1649: Selects a single word from the value.
1.90 jdolecek 1650: .\" :[start..end]
1.89 sjg 1651: .It Ar start Ns Cm \&.. Ns Ar end
1652: Selects all words from
1653: .Ar start
1654: to
1655: .Ar end ,
1656: inclusive.
1657: For example,
1.91 lukem 1658: .Ql Cm \&:[2..-1]
1.89 sjg 1659: selects all words from the second word to the last word.
1660: If
1661: .Ar start
1662: is greater than
1663: .Ar end ,
1.91 lukem 1664: then the words are output in reverse order.
1665: For example,
1666: .Ql Cm \&:[-1..1]
1.89 sjg 1667: selects all the words from last to first.
1.90 jdolecek 1668: .\" :[*]
1.89 sjg 1669: .It Cm \&*
1670: Causes subsequent modifiers to treat the value as a single word
1.109 wiz 1671: (possibly containing embedded white space).
1672: Analogous to the effect of
1.94 wiz 1673: \&"$*\&"
1.89 sjg 1674: in Bourne shell.
1.90 jdolecek 1675: .\" :[0]
1.89 sjg 1676: .It 0
1677: Means the same as
1.91 lukem 1678: .Ql Cm \&:[*] .
1.90 jdolecek 1679: .\" :[*]
1.89 sjg 1680: .It Cm \&@
1681: Causes subsequent modifiers to treat the value as a sequence of words
1.109 wiz 1682: delimited by white space.
1683: Analogous to the effect of
1.94 wiz 1684: \&"$@\&"
1.89 sjg 1685: in Bourne shell.
1.90 jdolecek 1686: .\" :[#]
1.89 sjg 1687: .It Cm \&#
1688: Returns the number of words in the value.
1689: .El \" :[range]
1.6 cgd 1690: .El
1691: .Sh INCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS
1.16 christos 1692: Makefile inclusion, conditional structures and for loops reminiscent
1.6 cgd 1693: of the C programming language are provided in
1.74 wiz 1694: .Nm .
1.1 cgd 1695: All such structures are identified by a line beginning with a single
1696: dot
1697: .Pq Ql \&.
1698: character.
1699: Files are included with either
1.29 ross 1700: .Cm \&.include Aq Ar file
1.1 cgd 1701: or
1.29 ross 1702: .Cm \&.include Pf \*q Ar file Ns \*q .
1.1 cgd 1703: Variables between the angle brackets or double quotes are expanded
1704: to form the file name.
1705: If angle brackets are used, the included makefile is expected to be in
1706: the system makefile directory.
1707: If double quotes are used, the including makefile's directory and any
1708: directories specified using the
1709: .Fl I
1710: option are searched before the system
1711: makefile directory.
1.28 christos 1712: For compatibility with other versions of
1713: .Nm
1714: .Ql include file ...
1.67 grant 1715: is also accepted.
1716: If the include statement is written as
1.29 ross 1717: .Cm .-include
1718: or as
1719: .Cm .sinclude
1.28 christos 1720: then errors locating and/or opening include files are ignored.
1.1 cgd 1721: .Pp
1722: Conditional expressions are also preceded by a single dot as the first
1.5 jtc 1723: character of a line.
1.1 cgd 1724: The possible conditionals are as follows:
1725: .Bl -tag -width Ds
1.168 sjg 1726: .It Ic .error Ar message
1727: The message is printed along with the name of the makefile and line number,
1728: then
1729: .Nm
1730: will exit.
1.165 sjg 1731: .It Ic .export Ar variable ...
1.133 sjg 1732: Export the specified global variable.
1.165 sjg 1733: If no variable list is provided, all globals are exported
1.133 sjg 1734: except for internal variables (those that start with
1.157 wiz 1735: .Ql \&. ) .
1.133 sjg 1736: This is not affected by the
1737: .Fl X
1738: flag, so should be used with caution.
1.201 christos 1739: For compatibility with other
1740: .Nm
1741: programs
1742: .Ql export variable=value
1743: is also accepted.
1.165 sjg 1744: .Pp
1.133 sjg 1745: Appending a variable name to
1746: .Va .MAKE.EXPORTED
1747: is equivalent to exporting a variable.
1.173 sjg 1748: .It Ic .export-env Ar variable ...
1.176 wiz 1749: The same as
1.173 sjg 1750: .Ql .export ,
1.176 wiz 1751: except that the variable is not appended to
1.173 sjg 1752: .Va .MAKE.EXPORTED .
1.176 wiz 1753: This allows exporting a value to the environment which is different from that
1754: used by
1.173 sjg 1755: .Nm
1756: internally.
1.168 sjg 1757: .It Ic .info Ar message
1758: The message is printed along with the name of the makefile and line number.
1.169 wiz 1759: .It Ic .undef Ar variable
1760: Un-define the specified global variable.
1761: Only global variables may be un-defined.
1.165 sjg 1762: .It Ic .unexport Ar variable ...
1763: The opposite of
1764: .Ql .export .
1765: The specified global
1.166 wiz 1766: .Va variable
1767: will be removed from
1.165 sjg 1768: .Va .MAKE.EXPORTED .
1769: If no variable list is provided, all globals are unexported,
1770: and
1.166 wiz 1771: .Va .MAKE.EXPORTED
1.165 sjg 1772: deleted.
1773: .It Ic .unexport-env
1774: Unexport all globals previously exported and
1775: clear the environment inherited from the parent.
1.166 wiz 1776: This operation will cause a memory leak of the original environment,
1777: so should be used sparingly.
1778: Testing for
1.165 sjg 1779: .Va .MAKE.LEVEL
1780: being 0, would make sense.
1.166 wiz 1781: Also note that any variables which originated in the parent environment
1.165 sjg 1782: should be explicitly preserved if desired.
1783: For example:
1784: .Bd -literal -offset indent
1785: .Li .if ${.MAKE.LEVEL} == 0
1786: PATH := ${PATH}
1787: .Li .unexport-env
1788: .Li .export PATH
1789: .Li .endif
1790: .Pp
1791: .Ed
1.166 wiz 1792: Would result in an environment containing only
1.165 sjg 1793: .Ql Ev PATH ,
1794: which is the minimal useful environment.
1795: Actually
1.166 wiz 1796: .Ql Ev .MAKE.LEVEL
1.165 sjg 1797: will also be pushed into the new environment.
1.168 sjg 1798: .It Ic .warning Ar message
1799: The message prefixed by
1800: .Ql Pa warning:
1801: is printed along with the name of the makefile and line number.
1.164 joerg 1802: .It Ic \&.if Oo \&! Oc Ns Ar expression Op Ar operator expression ...
1.1 cgd 1803: Test the value of an expression.
1.164 joerg 1804: .It Ic .ifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.7 mycroft 1805: Test the value of a variable.
1.164 joerg 1806: .It Ic .ifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.7 mycroft 1807: Test the value of a variable.
1.164 joerg 1808: .It Ic .ifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.7 mycroft 1809: Test the target being built.
1.164 joerg 1810: .It Ic .ifnmake Oo \&! Ns Oc Ar target Op Ar operator target ...
1.1 cgd 1811: Test the target being built.
1812: .It Ic .else
1813: Reverse the sense of the last conditional.
1.164 joerg 1814: .It Ic .elif Oo \&! Ns Oc Ar expression Op Ar operator expression ...
1.1 cgd 1815: A combination of
1816: .Ql Ic .else
1817: followed by
1818: .Ql Ic .if .
1.164 joerg 1819: .It Ic .elifdef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.1 cgd 1820: A combination of
1821: .Ql Ic .else
1822: followed by
1823: .Ql Ic .ifdef .
1.164 joerg 1824: .It Ic .elifndef Oo \&! Oc Ns Ar variable Op Ar operator variable ...
1.1 cgd 1825: A combination of
1826: .Ql Ic .else
1827: followed by
1828: .Ql Ic .ifndef .
1.164 joerg 1829: .It Ic .elifmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.1 cgd 1830: A combination of
1831: .Ql Ic .else
1832: followed by
1833: .Ql Ic .ifmake .
1.164 joerg 1834: .It Ic .elifnmake Oo \&! Oc Ns Ar target Op Ar operator target ...
1.1 cgd 1835: A combination of
1836: .Ql Ic .else
1837: followed by
1838: .Ql Ic .ifnmake .
1839: .It Ic .endif
1840: End the body of the conditional.
1841: .El
1842: .Pp
1843: The
1844: .Ar operator
1845: may be any one of the following:
1846: .Bl -tag -width "Cm XX"
1847: .It Cm \&|\&|
1.64 wiz 1848: Logical OR.
1.62 ross 1849: .It Cm \&\*[Am]\*[Am]
1.1 cgd 1850: Logical
1851: .Tn AND ;
1852: of higher precedence than
1.26 hubertf 1853: .Dq \&|\&| .
1.1 cgd 1854: .El
1855: .Pp
1856: As in C,
1.25 lukem 1857: .Nm
1.1 cgd 1858: will only evaluate a conditional as far as is necessary to determine
1859: its value.
1.16 christos 1860: Parentheses may be used to change the order of evaluation.
1.1 cgd 1861: The boolean operator
1862: .Ql Ic \&!
1863: may be used to logically negate an entire
1864: conditional.
1.5 jtc 1865: It is of higher precedence than
1.62 ross 1866: .Ql Ic \&\*[Am]\*[Am] .
1.1 cgd 1867: .Pp
1868: The value of
1869: .Ar expression
1870: may be any of the following:
1.61 ross 1871: .Bl -tag -width defined
1.1 cgd 1872: .It Ic defined
1873: Takes a variable name as an argument and evaluates to true if the variable
1874: has been defined.
1875: .It Ic make
1876: Takes a target name as an argument and evaluates to true if the target
1877: was specified as part of
1.74 wiz 1878: .Nm Ns 's
1.1 cgd 1879: command line or was declared the default target (either implicitly or
1880: explicitly, see
1881: .Va .MAIN )
1882: before the line containing the conditional.
1883: .It Ic empty
1.5 jtc 1884: Takes a variable, with possible modifiers, and evaluates to true if
1.1 cgd 1885: the expansion of the variable would result in an empty string.
1886: .It Ic exists
1887: Takes a file name as an argument and evaluates to true if the file exists.
1888: The file is searched for on the system search path (see
1889: .Va .PATH ) .
1890: .It Ic target
1891: Takes a target name as an argument and evaluates to true if the target
1892: has been defined.
1.47 christos 1893: .It Ic commands
1894: Takes a target name as an argument and evaluates to true if the target
1895: has been defined and has commands associated with it.
1.1 cgd 1896: .El
1897: .Pp
1898: .Ar Expression
1.67 grant 1899: may also be an arithmetic or string comparison.
1900: Variable expansion is
1.6 cgd 1901: performed on both sides of the comparison, after which the integral
1.67 grant 1902: values are compared.
1903: A value is interpreted as hexadecimal if it is
1.6 cgd 1904: preceded by 0x, otherwise it is decimal; octal numbers are not supported.
1.67 grant 1905: The standard C relational operators are all supported.
1906: If after
1.6 cgd 1907: variable expansion, either the left or right hand side of a
1.1 cgd 1908: .Ql Ic ==
1909: or
1910: .Ql Ic "!="
1.6 cgd 1911: operator is not an integral value, then
1912: string comparison is performed between the expanded
1913: variables.
1.1 cgd 1914: If no relational operator is given, it is assumed that the expanded
1.102 sjg 1915: variable is being compared against 0 or an empty string in the case
1916: of a string comparison.
1.1 cgd 1917: .Pp
1918: When
1.25 lukem 1919: .Nm
1.150 dsl 1920: is evaluating one of these conditional expressions, and it encounters
1921: a (white-space separated) word it doesn't recognize, either the
1.137 wiz 1922: .Dq make
1923: or
1924: .Dq defined
1.1 cgd 1925: expression is applied to it, depending on the form of the conditional.
1926: If the form is
1.150 dsl 1927: .Ql Ic .ifdef ,
1928: .Ql Ic .ifndef ,
1.1 cgd 1929: or
1.150 dsl 1930: .Ql Ic .if
1.137 wiz 1931: the
1932: .Dq defined
1933: expression is applied.
1.1 cgd 1934: Similarly, if the form is
1935: .Ql Ic .ifmake
1936: or
1.233 christos 1937: .Ql Ic .ifnmake ,
1938: the
1.137 wiz 1939: .Dq make
1.1 cgd 1940: expression is applied.
1941: .Pp
1942: If the conditional evaluates to true the parsing of the makefile continues
1943: as before.
1944: If it evaluates to false, the following lines are skipped.
1945: In both cases this continues until a
1946: .Ql Ic .else
1947: or
1948: .Ql Ic .endif
1949: is found.
1.16 christos 1950: .Pp
1.6 cgd 1951: For loops are typically used to apply a set of rules to a list of files.
1952: The syntax of a for loop is:
1.59 bgrayson 1953: .Pp
1954: .Bl -tag -compact -width Ds
1.164 joerg 1955: .It Ic \&.for Ar variable Oo Ar variable ... Oc Ic in Ar expression
1.80 wiz 1956: .It Aq make-rules
1957: .It Ic \&.endfor
1.6 cgd 1958: .El
1.59 bgrayson 1959: .Pp
1.6 cgd 1960: After the for
1.16 christos 1961: .Ic expression
1.67 grant 1962: is evaluated, it is split into words.
1963: On each iteration of the loop, one word is taken and assigned to each
1.39 christos 1964: .Ic variable ,
1965: in order, and these
1966: .Ic variables
1967: are substituted into the
1.16 christos 1968: .Ic make-rules
1.6 cgd 1969: inside the body of the for loop.
1.39 christos 1970: The number of words must come out even; that is, if there are three
1971: iteration variables, the number of words provided must be a multiple
1972: of three.
1.1 cgd 1973: .Sh COMMENTS
1974: Comments begin with a hash
1975: .Pq Ql \&#
1976: character, anywhere but in a shell
1.231 christos 1977: command line, and continue to the end of an
1978: .Em unescaped
1979: new line.
1980: This can be used to a great effect to comment out continued sections of
1981: a makefile but it can also lead to very subtle, and possibly difficult
1982: to spot, errors for that same reason.
1983: Please observe some actually encountered problems:
1984: .Bl -column -offset indent "| target: source" "| target: source" \
1985: "| target: source"
1986: .It "#OLD_NAME =\\" Ta "| VAR =\\" Ta "| #VAR2 =\\"
1987: .It "NEW_NAME =\\" Ta "| foo\\" Ta "| # foo\\"
1988: .It "foo\\" Ta "| # bar\\" Ta "| # bar\\"
1989: .It "bar" Ta "| baz" Ta "| target: source"
1990: .El
1.97 lukem 1991: .Sh SPECIAL SOURCES (ATTRIBUTES)
1.61 ross 1992: .Bl -tag -width .IGNOREx
1.97 lukem 1993: .It Ic .EXEC
1994: Target is never out of date, but always execute commands anyway.
1.1 cgd 1995: .It Ic .IGNORE
1996: Ignore any errors from the commands associated with this target, exactly
1997: as if they all were preceded by a dash
1998: .Pq Ql \- .
1.97 lukem 1999: .\" .It Ic .INVISIBLE
2000: .\" XXX
2001: .\" .It Ic .JOIN
2002: .\" XXX
1.18 christos 2003: .It Ic .MADE
1.48 wiz 2004: Mark all sources of this target as being up-to-date.
1.1 cgd 2005: .It Ic .MAKE
2006: Execute the commands associated with this target even if the
2007: .Fl n
2008: or
2009: .Fl t
2010: options were specified.
2011: Normally used to mark recursive
1.226 dholland 2012: .Nm Ns s .
1.233 christos 2013: Single lines from rule's commands may be marked for similar treatment
2014: by prepending them with
2015: .Sq + .
1.180 sjg 2016: .It Ic .META
2017: Create a meta file for the target, even if it is flagged as
2018: .Ic .PHONY ,
1.182 wiz 2019: .Ic .MAKE ,
1.180 sjg 2020: or
2021: .Ic .SPECIAL .
2022: Usage in conjunction with
2023: .Ic .MAKE
2024: is the most likely case.
1.194 sjg 2025: In "meta" mode, the target is out-of-date if the meta file is missing.
1.180 sjg 2026: .It Ic .NOMETA
2027: Do not create a meta file for the target.
2028: Meta files are also not created for
2029: .Ic .PHONY ,
1.182 wiz 2030: .Ic .MAKE ,
1.180 sjg 2031: or
2032: .Ic .SPECIAL
2033: targets.
2034: .It Ic .NOMETA_CMP
2035: Ignore differences in commands when deciding if target is out of date.
2036: This is useful if the command contains a value which always changes.
1.182 wiz 2037: If the number of commands change, though, the target will still be out of date.
1.213 sjg 2038: The same effect applies to any command line that uses the variable
2039: .Va .OODATE ,
2040: which can be used for that purpose even when not otherwise needed or desired:
2041: .Bd -literal -offset indent
2042:
2043: skip-compare-for-some:
2044: @echo this will be compared
2045: @echo this will not ${.OODATE:M.NOMETA_CMP}
2046: @echo this will also be compared
2047:
2048: .Ed
2049: The
2050: .Cm \&:M
2051: pattern suppresses any expansion of the unwanted variable.
1.97 lukem 2052: .It Ic .NOPATH
2053: Do not search for the target in the directories specified by
2054: .Ic .PATH .
1.1 cgd 2055: .It Ic .NOTMAIN
2056: Normally
1.25 lukem 2057: .Nm
1.1 cgd 2058: selects the first target it encounters as the default target to be built
2059: if no target was specified.
2060: This source prevents this target from being selected.
2061: .It Ic .OPTIONAL
2062: If a target is marked with this attribute and
1.25 lukem 2063: .Nm
1.1 cgd 2064: can't figure out how to create it, it will ignore this fact and assume
2065: the file isn't needed or already exists.
1.97 lukem 2066: .It Ic .PHONY
2067: The target does not
2068: correspond to an actual file; it is always considered to be out of date,
2069: and will not be created with the
2070: .Fl t
2071: option.
1.179 dholland 2072: Suffix-transformation rules are not applied to
2073: .Ic .PHONY
2074: targets.
1.233 christos 2075: .Pp
2076: As a note of historical interest, a dependency on a target called
2077: .Dq FORCE
2078: or
2079: .Dq FRC
2080: has been used to force
2081: .Nm
2082: always run the commands of a target, instead of the in all ways superior
2083: .Ic .PHONY .
2084: This dependency will then itself defined without dependencies or
2085: commands.
2086: As long as a file by that name does not exist, the target will always be
2087: considered to be out of date and force targets depending on it to be
2088: re-made.
1.1 cgd 2089: .It Ic .PRECIOUS
2090: When
1.25 lukem 2091: .Nm
1.131 rillig 2092: is interrupted, it normally removes any partially made targets.
1.1 cgd 2093: This source prevents the target from being removed.
1.97 lukem 2094: .It Ic .RECURSIVE
2095: Synonym for
2096: .Ic .MAKE .
1.1 cgd 2097: .It Ic .SILENT
2098: Do not echo any of the commands associated with this target, exactly
2099: as if they all were preceded by an at sign
2100: .Pq Ql @ .
2101: .It Ic .USE
2102: Turn the target into
1.74 wiz 2103: .Nm Ns 's
1.1 cgd 2104: version of a macro.
2105: When the target is used as a source for another target, the other target
2106: acquires the commands, sources, and attributes (except for
2107: .Ic .USE )
2108: of the
2109: source.
2110: If the target already has commands, the
2111: .Ic .USE
2112: target's commands are appended
2113: to them.
1.52 christos 2114: .It Ic .USEBEFORE
2115: Exactly like
2116: .Ic .USE ,
1.57 wiz 2117: but prepend the
1.52 christos 2118: .Ic .USEBEFORE
2119: target commands to the target.
1.12 christos 2120: .It Ic .WAIT
1.71 mjl 2121: If
1.12 christos 2122: .Ic .WAIT
1.71 mjl 2123: appears in a dependency line, the sources that precede it are
1.67 grant 2124: made before the sources that succeed it in the line.
1.128 dsl 2125: Since the dependents of files are not made until the file itself
2126: could be made, this also stops the dependents being built unless they
2127: are needed for another branch of the dependency tree.
2128: So given:
2129: .Bd -literal
2130: x: a .WAIT b
2131: echo x
2132: a:
2133: echo a
2134: b: b1
2135: echo b
2136: b1:
2137: echo b1
2138:
2139: .Ed
2140: the output is always
1.151 dholland 2141: .Ql a ,
1.128 dsl 2142: .Ql b1 ,
2143: .Ql b ,
2144: .Ql x .
2145: .br
1.122 apb 2146: The ordering imposed by
2147: .Ic .WAIT
1.128 dsl 2148: is only relevant for parallel makes.
1.1 cgd 2149: .El
1.57 wiz 2150: .Sh SPECIAL TARGETS
1.1 cgd 2151: Special targets may not be included with other targets, i.e. they must be
2152: the only target specified.
1.61 ross 2153: .Bl -tag -width .BEGINx
1.1 cgd 2154: .It Ic .BEGIN
2155: Any command lines attached to this target are executed before anything
2156: else is done.
2157: .It Ic .DEFAULT
2158: This is sort of a
2159: .Ic .USE
2160: rule for any target (that was used only as a
2161: source) that
1.25 lukem 2162: .Nm
1.1 cgd 2163: can't figure out any other way to create.
2164: Only the shell script is used.
2165: The
2166: .Ic .IMPSRC
2167: variable of a target that inherits
2168: .Ic .DEFAULT Ns 's
2169: commands is set
2170: to the target's own name.
2171: .It Ic .END
2172: Any command lines attached to this target are executed after everything
2173: else is done.
1.168 sjg 2174: .It Ic .ERROR
2175: Any command lines attached to this target are executed when another target fails.
2176: The
2177: .Ic .ERROR_TARGET
2178: variable is set to the target that failed.
1.169 wiz 2179: See also
1.168 sjg 2180: .Ic MAKE_PRINT_VAR_ON_ERROR .
1.1 cgd 2181: .It Ic .IGNORE
2182: Mark each of the sources with the
2183: .Ic .IGNORE
2184: attribute.
2185: If no sources are specified, this is the equivalent of specifying the
2186: .Fl i
2187: option.
2188: .It Ic .INTERRUPT
2189: If
1.25 lukem 2190: .Nm
1.1 cgd 2191: is interrupted, the commands for this target will be executed.
2192: .It Ic .MAIN
2193: If no target is specified when
1.25 lukem 2194: .Nm
1.1 cgd 2195: is invoked, this target will be built.
2196: .It Ic .MAKEFLAGS
2197: This target provides a way to specify flags for
1.25 lukem 2198: .Nm
1.1 cgd 2199: when the makefile is used.
2200: The flags are as if typed to the shell, though the
2201: .Fl f
2202: option will have
2203: no effect.
1.12 christos 2204: .\" XXX: NOT YET!!!!
2205: .\" .It Ic .NOTPARALLEL
1.70 wiz 2206: .\" The named targets are executed in non parallel mode.
2207: .\" If no targets are
1.12 christos 2208: .\" specified, then all targets are executed in non parallel mode.
1.20 gwr 2209: .It Ic .NOPATH
2210: Apply the
2211: .Ic .NOPATH
1.67 grant 2212: attribute to any specified sources.
1.12 christos 2213: .It Ic .NOTPARALLEL
2214: Disable parallel mode.
2215: .It Ic .NO_PARALLEL
1.97 lukem 2216: Synonym for
2217: .Ic .NOTPARALLEL ,
2218: for compatibility with other pmake variants.
1.233 christos 2219: .It Ic .NULL
2220: .Sy This special target is deprecated!
2221: It will go away as soon as pattern rules are implemented.
2222: .Pp
2223: The source of this target is a suffix listed in
2224: .Ic .SUFFIXES .
2225: It tells
2226: .Nm
2227: to pretend that targets which have no other known suffix have that suffix.
2228: This is relevant when suffix transformation rules are tried, and has
2229: the following two aspects (.s1 is the null suffix):
2230: .Bl -inset -offset indent
2231: .It Em "remove a suffix" :
2232: if the target
2233: .Sq foo
2234: is needed, the transformation rule
2235: .Sq .s2.s1
2236: can be used to make it from
2237: .Sq foo.s2 .
2238: The
2239: .Va .TARGET
2240: and
2241: .Va .PREFIX
2242: local variables are set to
2243: .Sq foo .
2244: .It Em "add a suffix" :
2245: if the target
2246: .Sq foo.s2
2247: is needed, the transformation rule
2248: .Sq .s1.s2
2249: can be used to make it from
2250: .Sq foo .
2251: The
2252: .Va .IMPSRC
2253: local variable is set to
2254: .Sq foo .
2255: .El
2256: .Pp
2257: This feature might be easier to understand, if you think of
2258: .Sq .s1
2259: as a way of explicitly writing
2260: .Sq "" .
2261: .Pp
2262: Looking closely you will notice that the first, suffix removal aspect
2263: is a limited version of single suffix transformation rules.
2264: It abuses double suffix rules and only works with one source
2265: .Sq suffix .
2266: New makefiles should use single suffix rules and old ones should
2267: migrate to them.
2268: Using both at the same time won't crash
2269: .Nm ,
2270: but you're aiming a gun at your own foot.
2271: To protect your foot, the rules followed in that case are not laid out
2272: here, you need to read the source code.
2273: .Pp
2274: This special target is only currently retained because of the second,
2275: suffix adding aspect, even if that too abuses double suffix rules.
2276: There is no substitute before pattern rules are implemented.
2277: To use this feature in this case, it is strongly suggested to use
2278: a verbose suffix that is not a real or imaginable one in your project,
2279: for example
2280: .Sq .NOSUFFIX .
1.12 christos 2281: .It Ic .ORDER
2282: The named targets are made in sequence.
1.128 dsl 2283: This ordering does not add targets to the list of targets to be made.
2284: Since the dependents of a target do not get built until the target itself
2285: could be built, unless
2286: .Ql a
1.129 wiz 2287: is built by another part of the dependency graph,
1.128 dsl 2288: the following is a dependency loop:
2289: .Bd -literal
1.192 cheusov 2290: \&.ORDER: b a
1.128 dsl 2291: b: a
2292: .Ed
1.129 wiz 2293: .Pp
1.122 apb 2294: The ordering imposed by
2295: .Ic .ORDER
1.128 dsl 2296: is only relevant for parallel makes.
1.12 christos 2297: .\" XXX: NOT YET!!!!
2298: .\" .It Ic .PARALLEL
1.70 wiz 2299: .\" The named targets are executed in parallel mode.
2300: .\" If no targets are
1.12 christos 2301: .\" specified, then all targets are executed in parallel mode.
1.1 cgd 2302: .It Ic .PATH
2303: The sources are directories which are to be searched for files not
2304: found in the current directory.
2305: If no sources are specified, any previously specified directories are
2306: deleted.
1.34 thorpej 2307: If the source is the special
2308: .Ic .DOTLAST
2309: target, then the current working
1.33 thorpej 2310: directory is searched last.
1.222 apb 2311: .It Ic .PATH. Ns Va suffix
1.221 dholland 2312: Like
2313: .Ic .PATH
2314: but applies only to files with a particular suffix.
2315: The suffix must have been previously declared with
2316: .Ic .SUFFIXES .
1.14 christos 2317: .It Ic .PHONY
2318: Apply the
2319: .Ic .PHONY
1.67 grant 2320: attribute to any specified sources.
1.1 cgd 2321: .It Ic .PRECIOUS
2322: Apply the
2323: .Ic .PRECIOUS
2324: attribute to any specified sources.
2325: If no sources are specified, the
2326: .Ic .PRECIOUS
2327: attribute is applied to every
2328: target in the file.
1.83 sjg 2329: .It Ic .SHELL
1.86 wiz 2330: Sets the shell that
1.83 sjg 2331: .Nm
1.86 wiz 2332: will use to execute commands.
2333: The sources are a set of
1.83 sjg 2334: .Ar field=value
1.86 wiz 2335: pairs.
1.83 sjg 2336: .Bl -tag -width hasErrCtls
2337: .It Ar name
2338: This is the minimal specification, used to select one of the builtin
2339: shell specs;
2340: .Ar sh ,
2341: .Ar ksh ,
2342: and
2343: .Ar csh .
2344: .It Ar path
2345: Specifies the path to the shell.
2346: .It Ar hasErrCtl
2347: Indicates whether the shell supports exit on error.
2348: .It Ar check
2349: The command to turn on error checking.
2350: .It Ar ignore
2351: The command to disable error checking.
2352: .It Ar echo
2353: The command to turn on echoing of commands executed.
2354: .It Ar quiet
2355: The command to turn off echoing of commands executed.
2356: .It Ar filter
2357: The output to filter after issuing the
2358: .Ar quiet
1.86 wiz 2359: command.
2360: It is typically identical to
1.83 sjg 2361: .Ar quiet .
2362: .It Ar errFlag
2363: The flag to pass the shell to enable error checking.
2364: .It Ar echoFlag
2365: The flag to pass the shell to enable command echoing.
1.127 rillig 2366: .It Ar newline
2367: The string literal to pass the shell that results in a single newline
2368: character when used outside of any quoting characters.
1.83 sjg 2369: .El
2370: Example:
2371: .Bd -literal
1.167 joerg 2372: \&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e
1.194 sjg 2373: check="set \-e" ignore="set +e" \e
2374: echo="set \-v" quiet="set +v" filter="set +v" \e
1.167 joerg 2375: echoFlag=v errFlag=e newline="'\en'"
1.83 sjg 2376: .Ed
1.1 cgd 2377: .It Ic .SILENT
2378: Apply the
2379: .Ic .SILENT
2380: attribute to any specified sources.
2381: If no sources are specified, the
2382: .Ic .SILENT
2383: attribute is applied to every
2384: command in the file.
1.211 christos 2385: .It Ic .STALE
2386: This target gets run when a dependency file contains stale entries, having
2387: .Va .ALLSRC
2388: set to the name of that dependency file.
1.1 cgd 2389: .It Ic .SUFFIXES
1.233 christos 2390: Each source specifies a known suffix to
2391: .Nm .
2392: It allows the creation of suffix transformation rules.
2393: A rule that looks like a transformation rule is a regular rule
2394: if it is not composed of known suffixes.
2395: If no sources are specified, all known suffixes are forgotten.
2396: .Pp
2397: There is a built-in list of suffixes and related transformation rules in
1.74 wiz 2398: .Nm .
1.233 christos 2399: Clearing the suffix list does not remove the corresponding rules and they
2400: become active again if the related suffixes are made known again.
2401: In fact, there is no way other than the
2402: .Fl r
2403: command line option to completely remove the built-in rules.
2404: It is possible to nullify it with an explicit no-op rule (it will run, but
2405: won't do anything) or redefine it.
1.136 cube 2406: .Pp
2407: Example:
2408: .Bd -literal
1.233 christos 2409: \&.SUFFIXES: # Forget all suffixes
2410: \&.SUFFIXES: .c .o # Re-activate .c and .o
2411: \&.c: ; # Nullify (the semicolon is mandatory)
2412: \&.c.o: # Replace
1.194 sjg 2413: cc \-o ${.TARGET} \-c ${.IMPSRC}
1.136 cube 2414: .Ed
1.233 christos 2415: .Pp
2416: POSIX compatible suffixes start with a period and contain no slashes or other
2417: periods.
2418: In this implementation the amount and the location of periods is not
2419: restricted: there may be none or more than one period, anywhere in
2420: the suffix.
1.31 ross 2421: .El
1.1 cgd 2422: .Sh ENVIRONMENT
1.25 lukem 2423: .Nm
1.73 perry 2424: uses the following environment variables, if they exist:
1.16 christos 2425: .Ev MACHINE ,
1.26 hubertf 2426: .Ev MACHINE_ARCH ,
1.1 cgd 2427: .Ev MAKE ,
1.16 christos 2428: .Ev MAKEFLAGS ,
2429: .Ev MAKEOBJDIR ,
1.38 sjg 2430: .Ev MAKEOBJDIRPREFIX ,
1.76 jrf 2431: .Ev MAKESYSPATH ,
1.154 apb 2432: .Ev PWD ,
1.1 cgd 2433: and
1.154 apb 2434: .Ev TMPDIR .
1.57 wiz 2435: .Pp
1.38 sjg 2436: .Ev MAKEOBJDIRPREFIX
1.117 lukem 2437: and
1.38 sjg 2438: .Ev MAKEOBJDIR
1.117 lukem 2439: may only be set in the environment or on the command line to
1.38 sjg 2440: .Nm
1.117 lukem 2441: and not as makefile variables;
2442: see the description of
2443: .Ql Va .OBJDIR
2444: for more details.
1.1 cgd 2445: .Sh FILES
2446: .Bl -tag -width /usr/share/mk -compact
2447: .It .depend
2448: list of dependencies
2449: .It Makefile
2450: list of dependencies
2451: .It makefile
2452: list of dependencies
2453: .It sys.mk
2454: system makefile
2455: .It /usr/share/mk
2456: system makefile directory
2457: .El
1.128 dsl 2458: .Sh COMPATIBILITY
2459: The basic make syntax is compatible between different versions of make,
2460: however the special variables, variable modifiers and conditionals are not.
2461: .Pp
1.129 wiz 2462: The way that parallel makes are scheduled changed in
1.130 wiz 2463: .Nx 4.0
1.193 wiz 2464: so that .ORDER and .WAIT apply recursively to the dependent nodes.
1.128 dsl 2465: The algorithms used may change again in the future.
1.152 dsl 2466: .Pp
2467: The way that .for loop variables are substituted changed after
2468: .Nx 5.0
2469: so that they still appear to be variable expansions.
2470: In particular this stops them being treated as syntax, and removes some
2471: obscure problems using them in .if statements.
1.153 wiz 2472: .Sh SEE ALSO
2473: .Xr mkdep 1
2474: .Sh HISTORY
2475: A
2476: .Nm
2477: command appeared in
2478: .At v7 .
1.190 christos 2479: This
2480: .Nm
2481: implementation is based on Adam De Boor's pmake program which was written
1.209 christos 2482: for Sprite at Berkeley.
1.190 christos 2483: It was designed to be a parallel distributed make running jobs on different
1.191 wiz 2484: machines using a daemon called
1.190 christos 2485: .Dq customs .
1.152 dsl 2486: .Sh BUGS
2487: The
2488: .Nm
2489: syntax is difficult to parse without actually acting of the data.
2490: For instance finding the end of a variable use should involve scanning each
2491: the modifiers using the correct terminator for each field.
2492: In many places
2493: .Nm
2494: just counts {} and () in order to find the end of a variable expansion.
2495: .Pp
1.153 wiz 2496: There is no way of escaping a space character in a filename.
CVSweb <webmaster@jp.NetBSD.org>