2740 lines
72 KiB
Groff
2740 lines
72 KiB
Groff
.\" $NetBSD: make.1,v 1.361 2023/03/23 03:29:28 sjg Exp $
|
|
.\"
|
|
.\" Copyright (c) 1990, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" from: @(#)make.1 8.4 (Berkeley) 3/19/94
|
|
.\"
|
|
.Dd March 22, 2023
|
|
.Dt BMAKE 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm bmake
|
|
.Nd maintain program dependencies
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl BeikNnqrSstWwX
|
|
.Op Fl C Ar directory
|
|
.Op Fl D Ar variable
|
|
.Op Fl d Ar flags
|
|
.Op Fl f Ar makefile
|
|
.Op Fl I Ar directory
|
|
.Op Fl J Ar private
|
|
.Op Fl j Ar max_jobs
|
|
.Op Fl m Ar directory
|
|
.Op Fl T Ar file
|
|
.Op Fl V Ar variable
|
|
.Op Fl v Ar variable
|
|
.Op Ar variable\| Ns Cm \&= Ns Ar value
|
|
.Op Ar target No ...
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a program designed to simplify the maintenance of other programs.
|
|
Its input is a list of specifications as to the files upon which programs
|
|
and other files depend.
|
|
If no
|
|
.Fl f Ar makefile
|
|
option is given,
|
|
.Nm
|
|
tries to open
|
|
.Sq Pa makefile
|
|
then
|
|
.Sq Pa Makefile
|
|
in order to find the specifications.
|
|
If the file
|
|
.Sq Pa .depend
|
|
exists, it is read, see
|
|
.Xr mkdep 1 .
|
|
.Pp
|
|
This manual page is intended as a reference document only.
|
|
For a more thorough description of
|
|
.Nm
|
|
and makefiles, please refer to
|
|
.%T "PMake \- A Tutorial"
|
|
(from 1993).
|
|
.Pp
|
|
.Nm
|
|
prepends the contents of the
|
|
.Ev MAKEFLAGS
|
|
environment variable to the command line arguments before parsing them.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl B
|
|
Try to be backwards compatible by executing a single shell per command and
|
|
by making the sources of a dependency line in sequence.
|
|
.It Fl C Ar directory
|
|
Change to
|
|
.Ar directory
|
|
before reading the makefiles or doing anything else.
|
|
If multiple
|
|
.Fl C
|
|
options are specified, each is interpreted relative to the previous one:
|
|
.Fl C Pa / Fl C Pa etc
|
|
is equivalent to
|
|
.Fl C Pa /etc .
|
|
.It Fl D Ar variable
|
|
Define
|
|
.Ar variable
|
|
to be 1, in the global scope.
|
|
.It Fl d Oo Cm \- Oc Ns Ar flags
|
|
Turn on debugging, and specify which portions of
|
|
.Nm
|
|
are to print debugging information.
|
|
Unless the flags are preceded by
|
|
.Ql \- ,
|
|
they are added to the
|
|
.Ev MAKEFLAGS
|
|
environment variable and are passed on to any child make processes.
|
|
By default, debugging information is printed to standard error,
|
|
but this can be changed using the
|
|
.Cm F
|
|
debugging flag.
|
|
The debugging output is always unbuffered; in addition, if debugging
|
|
is enabled but debugging output is not directed to standard output,
|
|
the standard output is line buffered.
|
|
The available
|
|
.Ar flags
|
|
are:
|
|
.Bl -tag -width Ds
|
|
.It Cm A
|
|
Print all possible debugging information;
|
|
equivalent to specifying all of the debugging flags.
|
|
.It Cm a
|
|
Print debugging information about archive searching and caching.
|
|
.It Cm C
|
|
Print debugging information about the current working directory.
|
|
.It Cm c
|
|
Print debugging information about conditional evaluation.
|
|
.It Cm d
|
|
Print debugging information about directory searching and caching.
|
|
.It Cm e
|
|
Print debugging information about failed commands and targets.
|
|
.It Cm F Ns Oo Cm \&+ Oc Ns Ar filename
|
|
Specify where debugging output is written.
|
|
This must be the last flag, because it consumes the remainder of
|
|
the argument.
|
|
If the character immediately after the
|
|
.Cm F
|
|
flag is
|
|
.Ql \&+ ,
|
|
the file is opened in append mode;
|
|
otherwise the file is overwritten.
|
|
If the file name is
|
|
.Ql stdout
|
|
or
|
|
.Ql stderr ,
|
|
debugging output is written to the standard output or standard error output
|
|
respectively (and the
|
|
.Ql \&+
|
|
option has no effect).
|
|
Otherwise, the output is written to the named file.
|
|
If the file name ends with
|
|
.Ql .%d ,
|
|
the
|
|
.Ql %d
|
|
is replaced by the pid.
|
|
.It Cm f
|
|
Print debugging information about loop evaluation.
|
|
.It Cm g1
|
|
Print the input graph before making anything.
|
|
.It Cm g2
|
|
Print the input graph after making everything, or before exiting
|
|
on error.
|
|
.It Cm g3
|
|
Print the input graph before exiting on error.
|
|
.It Cm h
|
|
Print debugging information about hash table operations.
|
|
.It Cm j
|
|
Print debugging information about running multiple shells.
|
|
.It Cm L
|
|
Turn on lint checks.
|
|
This throws errors for variable assignments that do not parse correctly,
|
|
at the time of assignment, so the file and line number are available.
|
|
.It Cm l
|
|
Print commands in Makefiles regardless of whether or not they are prefixed by
|
|
.Ql @
|
|
or other
|
|
.Dq quiet
|
|
flags.
|
|
Also known as
|
|
.Dq loud
|
|
behavior.
|
|
.It Cm M
|
|
Print debugging information about
|
|
.Dq meta
|
|
mode decisions about targets.
|
|
.It Cm m
|
|
Print debugging information about making targets, including modification
|
|
dates.
|
|
.It Cm n
|
|
Don't delete the temporary command scripts created when running commands.
|
|
These temporary scripts are created in the directory
|
|
referred to by the
|
|
.Ev TMPDIR
|
|
environment variable, or in
|
|
.Pa /tmp
|
|
if
|
|
.Ev TMPDIR
|
|
is unset or set to the empty string.
|
|
The temporary scripts are created by
|
|
.Xr mkstemp 3 ,
|
|
and have names of the form
|
|
.Pa makeXXXXXX .
|
|
.Em NOTE :
|
|
This can create many files in
|
|
.Ev TMPDIR
|
|
or
|
|
.Pa /tmp ,
|
|
so use with care.
|
|
.It Cm p
|
|
Print debugging information about makefile parsing.
|
|
.It Cm s
|
|
Print debugging information about suffix-transformation rules.
|
|
.It Cm t
|
|
Print debugging information about target list maintenance.
|
|
.It Cm V
|
|
Force the
|
|
.Fl V
|
|
option to print raw values of variables,
|
|
overriding the default behavior set via
|
|
.Va .MAKE.EXPAND_VARIABLES .
|
|
.It Cm v
|
|
Print debugging information about variable assignment and expansion.
|
|
.It Cm x
|
|
Run shell commands with
|
|
.Fl x
|
|
so the actual commands are printed as they are executed.
|
|
.El
|
|
.It Fl e
|
|
Let environment variables override global variables within makefiles.
|
|
.It Fl f Ar makefile
|
|
Specify a makefile to read instead of the default
|
|
.Pa makefile
|
|
or
|
|
.Pa Makefile .
|
|
If
|
|
.Ar makefile
|
|
is
|
|
.Ql \&- ,
|
|
standard input is read.
|
|
Multiple makefiles may be specified, and are read in the order specified.
|
|
.It Fl I Ar directory
|
|
Specify a directory in which to search for makefiles and included makefiles.
|
|
The system makefile directory (or directories, see the
|
|
.Fl m
|
|
option) is automatically included as part of this list.
|
|
.It Fl i
|
|
Ignore non-zero exit of shell commands in the makefile.
|
|
Equivalent to specifying
|
|
.Ql \&-
|
|
before each command line in the makefile.
|
|
.It Fl J Ar private
|
|
This option should
|
|
.Em not
|
|
be specified by the user.
|
|
.Pp
|
|
When the
|
|
.Fl j
|
|
option is in use in a recursive build, this option is passed by a make
|
|
to child makes to allow all the make processes in the build to
|
|
cooperate to avoid overloading the system.
|
|
.It Fl j Ar max_jobs
|
|
Specify the maximum number of jobs that
|
|
.Nm
|
|
may have running at any one time.
|
|
The value of
|
|
.Ar max_jobs
|
|
is saved in
|
|
.Va .MAKE.JOBS .
|
|
Turns compatibility mode off, unless the
|
|
.Fl B
|
|
option is also specified.
|
|
When compatibility mode is off, all commands associated with a
|
|
target are executed in a single shell invocation as opposed to the
|
|
traditional one shell invocation per line.
|
|
This can break traditional scripts which change directories on each
|
|
command invocation and then expect to start with a fresh environment
|
|
on the next line.
|
|
It is more efficient to correct the scripts rather than turn backwards
|
|
compatibility on.
|
|
.Pp
|
|
A job token pool with
|
|
.Ar max_jobs
|
|
tokens is used to control the total number of jobs running.
|
|
Each instance of
|
|
.Nm
|
|
will wait for a token from the pool before running a new job.
|
|
.It Fl k
|
|
Continue processing after errors are encountered, but only on those targets
|
|
that do not depend on the target whose creation caused the error.
|
|
.It Fl m Ar directory
|
|
Specify a directory in which to search for
|
|
.Pa sys.mk
|
|
and makefiles included via the
|
|
.Li \&< Ns Ar file Ns Li \&> Ns -style
|
|
include statement.
|
|
The
|
|
.Fl m
|
|
option can be used multiple times to form a search path.
|
|
This path overrides the default system include path
|
|
.Pa /usr/share/mk .
|
|
Furthermore, the system include path is appended to the search path used for
|
|
.Li \*q Ns Ar file Ns Li \*q Ns -style
|
|
include statements (see the
|
|
.Fl I
|
|
option).
|
|
The system include path can be referenced via the read-only variable
|
|
.Va .SYSPATH .
|
|
.Pp
|
|
If a directory name in the
|
|
.Fl m
|
|
argument (or the
|
|
.Ev MAKESYSPATH
|
|
environment variable) starts with the string
|
|
.Ql \&.../ ,
|
|
.Nm
|
|
searches for the specified file or directory named in the remaining part
|
|
of the argument string.
|
|
The search starts with the current directory
|
|
and then works upward towards the root of the file system.
|
|
If the search is successful, the resulting directory replaces the
|
|
.Ql \&.../
|
|
specification in the
|
|
.Fl m
|
|
argument.
|
|
This feature allows
|
|
.Nm
|
|
to easily search in the current source tree for customized
|
|
.Pa sys.mk
|
|
files (e.g., by using
|
|
.Ql \&.../mk/sys.mk
|
|
as an argument).
|
|
.It Fl n
|
|
Display the commands that would have been executed, but do not
|
|
actually execute them unless the target depends on the
|
|
.Va .MAKE
|
|
special source (see below) or the command is prefixed with
|
|
.Sq Cm + .
|
|
.It Fl N
|
|
Display the commands that would have been executed,
|
|
but do not actually execute any of them;
|
|
useful for debugging top-level makefiles
|
|
without descending into subdirectories.
|
|
.It Fl q
|
|
Do not execute any commands,
|
|
instead exit 0 if the specified targets are up to date, and 1 otherwise.
|
|
.It Fl r
|
|
Do not use the built-in rules specified in the system makefile.
|
|
.It Fl S
|
|
Stop processing if an error is encountered.
|
|
This is the default behavior and the opposite of
|
|
.Fl k .
|
|
.It Fl s
|
|
Do not echo any commands as they are executed.
|
|
Equivalent to specifying
|
|
.Sq Ic @
|
|
before each command line in the makefile.
|
|
.It Fl T Ar tracefile
|
|
When used with the
|
|
.Fl j
|
|
flag,
|
|
append a trace record to
|
|
.Ar tracefile
|
|
for each job started and completed.
|
|
.It Fl t
|
|
Rather than re-building a target as specified in the makefile, create it
|
|
or update its modification time to make it appear up-to-date.
|
|
.It Fl V Ar variable
|
|
Print the value of
|
|
.Ar variable .
|
|
Do not build any targets.
|
|
Multiple instances of this option may be specified;
|
|
the variables are printed one per line,
|
|
with a blank line for each null or undefined variable.
|
|
The value printed is extracted from the global scope after all
|
|
makefiles have been read.
|
|
.Pp
|
|
By default, the raw variable contents (which may
|
|
include additional unexpanded variable references) are shown.
|
|
If
|
|
.Ar variable
|
|
contains a
|
|
.Ql \&$ ,
|
|
it is not interpreted as a variable name but rather as an expression.
|
|
Its value is expanded before printing.
|
|
The value is also expanded before printing if
|
|
.Va .MAKE.EXPAND_VARIABLES
|
|
is set to true and the
|
|
.Fl dV
|
|
option has not been used to override it.
|
|
.Pp
|
|
Note that loop-local and target-local variables, as well as values
|
|
taken temporarily by global variables during makefile processing, are
|
|
not accessible via this option.
|
|
The
|
|
.Fl dv
|
|
debug mode can be used to see these at the cost of generating
|
|
substantial extraneous output.
|
|
.It Fl v Ar variable
|
|
Like
|
|
.Fl V ,
|
|
but all printed variables are always expanded to their complete value.
|
|
The last occurrence of
|
|
.Fl V
|
|
or
|
|
.Fl v
|
|
decides whether all variables are expanded or not.
|
|
.It Fl W
|
|
Treat any warnings during makefile parsing as errors.
|
|
.It Fl w
|
|
Print entering and leaving directory messages, pre and post processing.
|
|
.It Fl X
|
|
Don't export variables passed on the command line to the environment
|
|
individually.
|
|
Variables passed on the command line are still exported via the
|
|
.Ev MAKEFLAGS
|
|
environment variable.
|
|
This option may be useful on systems which have a small limit on the
|
|
size of command arguments.
|
|
.It Ar variable\| Ns Cm \&= Ns Ar value
|
|
Set the value of the variable
|
|
.Ar variable
|
|
to
|
|
.Ar value .
|
|
Normally, all values passed on the command line are also exported to
|
|
sub-makes in the environment.
|
|
The
|
|
.Fl X
|
|
flag disables this behavior.
|
|
Variable assignments should follow options for POSIX compatibility
|
|
but no ordering is enforced.
|
|
.El
|
|
.Pp
|
|
There are several different types of lines in a makefile: dependency
|
|
specifications, shell commands, variable assignments, include statements,
|
|
conditional directives, for loops, other directives, and comments.
|
|
.Pp
|
|
Lines may be continued from one line to the next
|
|
by ending them with a backslash
|
|
.Pq Ql \e .
|
|
The trailing newline character and initial whitespace on the following
|
|
line are compressed into a single space.
|
|
.Sh FILE DEPENDENCY SPECIFICATIONS
|
|
Dependency lines consist of one or more targets, an operator, and zero
|
|
or more sources.
|
|
This creates a relationship where the targets
|
|
.Dq depend
|
|
on the sources and are customarily created from them.
|
|
A target is considered out of date if it does not exist,
|
|
or if its modification time is less than that of any of its sources.
|
|
An out-of-date target is re-created, but not until all sources
|
|
have been examined and themselves re-created as needed.
|
|
Three operators may be used:
|
|
.Bl -tag -width flag
|
|
.It Ic \&:
|
|
Many dependency lines may name this target but only one may have
|
|
attached shell commands.
|
|
All sources named in all dependency lines are considered together,
|
|
and if needed the attached shell commands are run to create or
|
|
re-create the target.
|
|
If
|
|
.Nm
|
|
is interrupted, the target is removed.
|
|
.It Ic \&!
|
|
The same, but the target is always re-created whether or not it is out
|
|
of date.
|
|
.It Ic \&::
|
|
Any dependency line may have attached shell commands, but each one
|
|
is handled independently: its sources are considered and the attached
|
|
shell commands are run if the target is out of date with respect to
|
|
(only) those sources.
|
|
Thus, different groups of the attached shell commands may be run
|
|
depending on the circumstances.
|
|
Furthermore, unlike
|
|
.Ic \&: ,
|
|
for dependency lines with no sources, the attached shell
|
|
commands are always run.
|
|
Also unlike
|
|
.Ic \&: ,
|
|
the target is not removed if
|
|
.Nm
|
|
is interrupted.
|
|
.El
|
|
.Pp
|
|
All dependency lines mentioning a particular target must use the same
|
|
operator.
|
|
.Pp
|
|
Targets and sources may contain the shell wildcard values
|
|
.Ql \&? ,
|
|
.Ql * ,
|
|
.Ql [] ,
|
|
and
|
|
.Ql {} .
|
|
The values
|
|
.Ql \&? ,
|
|
.Ql * ,
|
|
and
|
|
.Ql []
|
|
may only be used as part of the final component of the target or source,
|
|
and only match existing files.
|
|
The value
|
|
.Ql {}
|
|
need not necessarily be used to describe existing files.
|
|
Expansion is in directory order, not alphabetically as done in the shell.
|
|
.Sh SHELL COMMANDS
|
|
Each target may have associated with it one or more lines of shell commands,
|
|
normally used to create the target.
|
|
Each of the lines in this script
|
|
.Em must
|
|
be preceded by a tab.
|
|
(For historical reasons, spaces are not accepted.)
|
|
While targets can occur in many dependency lines if desired,
|
|
by default only one of these rules may be followed by a creation script.
|
|
If the
|
|
.Sq Ic \&::
|
|
operator is used, however, all rules may include scripts,
|
|
and the respective scripts are executed in the order found.
|
|
.Pp
|
|
Each line is treated as a separate shell command,
|
|
unless the end of line is escaped with a backslash
|
|
.Ql \e ,
|
|
in which case that line and the next are combined.
|
|
If the first characters of the command are any combination of
|
|
.Sq Ic @ ,
|
|
.Sq Ic + ,
|
|
or
|
|
.Sq Ic \- ,
|
|
the command is treated specially.
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ic @
|
|
causes the command not to be echoed before it is executed.
|
|
.It Ic +
|
|
causes the command to be executed even when
|
|
.Fl n
|
|
is given.
|
|
This is similar to the effect of the
|
|
.Va .MAKE
|
|
special source,
|
|
except that the effect can be limited to a single line of a script.
|
|
.It Ic \-
|
|
in compatibility mode
|
|
causes any non-zero exit status of the command line to be ignored.
|
|
.El
|
|
.Pp
|
|
When
|
|
.Nm
|
|
is run in jobs mode with
|
|
.Fl j Ar max_jobs ,
|
|
the entire script for the target is fed to a single instance of the shell.
|
|
In compatibility (non-jobs) mode, each command is run in a separate process.
|
|
If the command contains any shell meta characters
|
|
.Pq Ql #=|^(){};&<>*?[]:$`\e\en ,
|
|
it is passed to the shell; otherwise
|
|
.Nm
|
|
attempts direct execution.
|
|
If a line starts with
|
|
.Sq Ic \-
|
|
and the shell has ErrCtl enabled,
|
|
failure of the command line is ignored as in compatibility mode.
|
|
Otherwise
|
|
.Sq Ic \-
|
|
affects the entire job;
|
|
the script stops at the first command line that fails,
|
|
but the target is not deemed to have failed.
|
|
.Pp
|
|
Makefiles should be written so that the mode of
|
|
.Nm
|
|
operation does not change their behavior.
|
|
For example, any command which uses
|
|
.Dq cd
|
|
or
|
|
.Dq chdir
|
|
without the intention of changing the directory for subsequent commands
|
|
should be put in parentheses so it executes in a subshell.
|
|
To force the use of a single shell, escape the line breaks so as to make
|
|
the whole script one command.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
avoid-chdir-side-effects:
|
|
@echo "Building $@ in $$(pwd)"
|
|
@(cd ${.CURDIR} && ${MAKE} $@)
|
|
@echo "Back in $$(pwd)"
|
|
|
|
ensure-one-shell-regardless-of-mode:
|
|
@echo "Building $@ in $$(pwd)"; \e
|
|
(cd ${.CURDIR} && ${MAKE} $@); \e
|
|
echo "Back in $$(pwd)"
|
|
.Ed
|
|
.Pp
|
|
Since
|
|
.Nm
|
|
changes the current working directory to
|
|
.Sq Va .OBJDIR
|
|
before executing any targets,
|
|
each child process starts with that as its current working directory.
|
|
.Sh VARIABLE ASSIGNMENTS
|
|
Variables in make behave much like macros in the C preprocessor.
|
|
.Pp
|
|
Variable assignments have the form
|
|
.Sq Ar NAME Ar op Ar value ,
|
|
where:
|
|
.Bl -tag -offset Ds -width Ds
|
|
.It Ar NAME
|
|
is a single-word variable name,
|
|
consisting, by tradition, of all upper-case letters,
|
|
.It Ar op
|
|
is one of the variable assignment operators described below, and
|
|
.It Ar value
|
|
is interpreted according to the variable assignment operator.
|
|
.El
|
|
.Pp
|
|
Whitespace around
|
|
.Ar NAME ,
|
|
.Ar op
|
|
and
|
|
.Ar value
|
|
is discarded.
|
|
.Ss Variable assignment operators
|
|
The five operators that assign values to variables are:
|
|
.Bl -tag -width Ds
|
|
.It Ic \&=
|
|
Assign the value to the variable.
|
|
Any previous value is overwritten.
|
|
.It Ic \&+=
|
|
Append the value to the current value of the variable,
|
|
separating them by a single space.
|
|
.It Ic \&?=
|
|
Assign the value to the variable if it is not already defined.
|
|
.It Ic \&:=
|
|
Expand the value, then assign it to the variable.
|
|
.Pp
|
|
.Em NOTE :
|
|
References to undefined variables are
|
|
.Em not
|
|
expanded.
|
|
This can cause problems when variable modifiers are used.
|
|
.\" See var-op-expand.mk, the section with LATER and INDIRECT.
|
|
.It Ic \&!=
|
|
Expand the value and pass it to the shell for execution,
|
|
then assign the output from the child's standard output to the variable.
|
|
Any newlines in the result are replaced with spaces.
|
|
.El
|
|
.Ss Expansion of variables
|
|
In most contexts where variables are expanded,
|
|
.Ql \&$$
|
|
expands to a single dollar sign.
|
|
In other contexts (most variable modifiers, string literals in conditions),
|
|
.Ql \&\e$
|
|
expands to a single dollar sign.
|
|
.Pp
|
|
References to variables have the form
|
|
.Cm \&${ Ns Ar name Ns Oo Ns Cm \&: Ns Ar modifiers Oc Ns Cm \&}
|
|
or
|
|
.Cm \&$( Ns Ar name Ns Oo Ns Cm \&: Ns Ar modifiers Oc Ns Cm \&) .
|
|
If the variable name consists of only a single character
|
|
and the expression contains no modifiers,
|
|
the surrounding curly braces or parentheses are not required.
|
|
This shorter form is not recommended.
|
|
.Pp
|
|
If the variable name contains a dollar, the name itself is expanded first.
|
|
This allows almost arbitrary variable names, however names containing dollar,
|
|
braces, parentheses or whitespace are really best avoided.
|
|
.Pp
|
|
If the result of expanding a nested variable expression contains a dollar sign
|
|
.Pq Ql \&$ ,
|
|
the result is subject to further expansion.
|
|
.Pp
|
|
Variable substitution occurs at four distinct times, depending on where
|
|
the variable is being used.
|
|
.Bl -enum
|
|
.It
|
|
Variables in dependency lines are expanded as the line is read.
|
|
.It
|
|
Variables in conditionals are expanded individually,
|
|
but only as far as necessary to determine the result of the conditional.
|
|
.It
|
|
Variables in shell commands are expanded when the shell command is
|
|
executed.
|
|
.It
|
|
.Ic .for
|
|
loop index variables are expanded on each loop iteration.
|
|
Note that other variables are not expanded when composing the body of a loop,
|
|
so the following example code:
|
|
.Bd -literal -offset indent
|
|
\&.for i in 1 2 3
|
|
a+= ${i}
|
|
j= ${i}
|
|
b+= ${j}
|
|
\&.endfor
|
|
|
|
all:
|
|
@echo ${a}
|
|
@echo ${b}
|
|
.Ed
|
|
.Pp
|
|
prints:
|
|
.Bd -literal -offset indent
|
|
1 2 3
|
|
3 3 3
|
|
.Ed
|
|
.Pp
|
|
After the loop is executed:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Va a
|
|
contains
|
|
.Ql ${:U1} ${:U2} ${:U3} ,
|
|
which expands to
|
|
.Ql 1 2 3 .
|
|
.It Va j
|
|
contains
|
|
.Ql ${:U3} ,
|
|
which expands to
|
|
.Ql 3 .
|
|
.It Va b
|
|
contains
|
|
.Ql ${j} ${j} ${j} ,
|
|
which expands to
|
|
.Ql ${:U3} ${:U3} ${:U3}
|
|
and further to
|
|
.Ql 3 3 3 .
|
|
.El
|
|
.El
|
|
.Ss Variable classes
|
|
The four different classes of variables (in order of increasing precedence)
|
|
are:
|
|
.Bl -tag -width Ds
|
|
.It Environment variables
|
|
Variables defined as part of
|
|
.Nm Ns 's
|
|
environment.
|
|
.It Global variables
|
|
Variables defined in the makefile or in included makefiles.
|
|
.It Command line variables
|
|
Variables defined as part of the command line.
|
|
.It Local variables
|
|
Variables that are defined specific to a certain target.
|
|
.El
|
|
.Pp
|
|
Local variables can be set on a dependency line, unless
|
|
.Va .MAKE.TARGET_LOCAL_VARIABLES
|
|
is set to
|
|
.Ql false .
|
|
The rest of the line
|
|
(which already has had global variables expanded)
|
|
is the variable value.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
COMPILER_WRAPPERS= ccache distcc icecc
|
|
|
|
${OBJS}: .MAKE.META.CMP_FILTER=${COMPILER_WRAPPERS:S,^,N,}
|
|
.Ed
|
|
.Pp
|
|
Only the targets
|
|
.Ql ${OBJS}
|
|
are impacted by that filter (in
|
|
.Dq meta
|
|
mode) and
|
|
simply enabling/disabling any of the compiler wrappers does not render all
|
|
of those targets out-of-date.
|
|
.Pp
|
|
.Em NOTE :
|
|
target-local variable assignments behave differently in that;
|
|
.Bl -tag -width Ds -offset indent
|
|
.It Ic \&+=
|
|
Only appends to a previous local assignment
|
|
for the same target and variable.
|
|
.It Ic \&:=
|
|
Is redundant with respect to global variables,
|
|
which have already been expanded.
|
|
.El
|
|
.Pp
|
|
The seven built-in local variables are:
|
|
.Bl -tag -width ".Va .ARCHIVE" -offset indent
|
|
.It Va .ALLSRC
|
|
The list of all sources for this target; also known as
|
|
.Sq Va \&> .
|
|
.It Va .ARCHIVE
|
|
The name of the archive file; also known as
|
|
.Sq Va \&! .
|
|
.It Va .IMPSRC
|
|
In suffix-transformation rules, the name/path of the source from which the
|
|
target is to be transformed (the
|
|
.Dq implied
|
|
source); also known as
|
|
.Sq Va \&< .
|
|
It is not defined in explicit rules.
|
|
.It Va .MEMBER
|
|
The name of the archive member; also known as
|
|
.Sq Va % .
|
|
.It Va .OODATE
|
|
The list of sources for this target that were deemed out-of-date; also
|
|
known as
|
|
.Sq Va \&? .
|
|
.It Va .PREFIX
|
|
The file prefix of the target, containing only the file portion, no suffix
|
|
or preceding directory components; also known as
|
|
.Sq Va * .
|
|
The suffix must be one of the known suffixes declared with
|
|
.Ic .SUFFIXES ,
|
|
or it is not recognized.
|
|
.It Va .TARGET
|
|
The name of the target; also known as
|
|
.Sq Va @ .
|
|
For compatibility with other makes this is an alias for
|
|
.Va .ARCHIVE
|
|
in archive member rules.
|
|
.El
|
|
.Pp
|
|
The shorter forms
|
|
.Po
|
|
.Sq Va \&> ,
|
|
.Sq Va \&! ,
|
|
.Sq Va \&< ,
|
|
.Sq Va \&% ,
|
|
.Sq Va \&? ,
|
|
.Sq Va \&* ,
|
|
and
|
|
.Sq Va \&@
|
|
.Pc
|
|
are permitted for backward
|
|
compatibility with historical makefiles and legacy POSIX make and are
|
|
not recommended.
|
|
.Pp
|
|
Variants of these variables with the punctuation followed immediately by
|
|
.Ql D
|
|
or
|
|
.Ql F ,
|
|
e.g.\&
|
|
.Ql $(@D) ,
|
|
are legacy forms equivalent to using the
|
|
.Ql :H
|
|
and
|
|
.Ql :T
|
|
modifiers.
|
|
These forms are accepted for compatibility with
|
|
.At V
|
|
makefiles and POSIX but are not recommended.
|
|
.Pp
|
|
Four of the local variables may be used in sources on dependency lines
|
|
because they expand to the proper value for each target on the line.
|
|
These variables are
|
|
.Sq Va .TARGET ,
|
|
.Sq Va .PREFIX ,
|
|
.Sq Va .ARCHIVE ,
|
|
and
|
|
.Sq Va .MEMBER .
|
|
.Ss Additional built-in variables
|
|
In addition,
|
|
.Nm
|
|
sets or knows about the following variables:
|
|
.Bl -tag
|
|
.\" NB: This list is sorted case-insensitive, ignoring punctuation.
|
|
.\" NB: To find all built-in variables in make's source code,
|
|
.\" NB: search for Var_*, Global_*, SetVarObjdir, GetBooleanExpr,
|
|
.\" NB: and the implementation of Var_SetWithFlags.
|
|
.\" NB: Last synced on 2023-01-01.
|
|
.It Va .ALLTARGETS
|
|
The list of all targets encountered in the makefiles.
|
|
If evaluated during makefile parsing,
|
|
lists only those targets encountered thus far.
|
|
.It Va .CURDIR
|
|
A path to the directory where
|
|
.Nm
|
|
was executed.
|
|
Refer to the description of
|
|
.Sq Va PWD
|
|
for more details.
|
|
.It Va .ERROR_CMD
|
|
Is used in error handling, see
|
|
.Va MAKE_PRINT_VAR_ON_ERROR .
|
|
.It Va .ERROR_CWD
|
|
Is used in error handling, see
|
|
.Va MAKE_PRINT_VAR_ON_ERROR .
|
|
.It Va .ERROR_META_FILE
|
|
Is used in error handling in
|
|
.Dq meta
|
|
mode, see
|
|
.Va MAKE_PRINT_VAR_ON_ERROR .
|
|
.It Va .ERROR_TARGET
|
|
Is used in error handling, see
|
|
.Va MAKE_PRINT_VAR_ON_ERROR .
|
|
.It Va .INCLUDEDFROMDIR
|
|
The directory of the file this makefile was included from.
|
|
.It Va .INCLUDEDFROMFILE
|
|
The filename of the file this makefile was included from.
|
|
.\" .INCLUDES is intentionally undocumented, as it is obsolete.
|
|
.\" .LIBS is intentionally undocumented, as it is obsolete.
|
|
.It Va MACHINE
|
|
The machine hardware name, see
|
|
.Xr uname 1 .
|
|
.It Va MACHINE_ARCH
|
|
The machine processor architecture name, see
|
|
.Xr uname 1 .
|
|
.It Va MAKE
|
|
The name that
|
|
.Nm
|
|
was executed with
|
|
.Pq Va argv[0] .
|
|
.It Va .MAKE
|
|
The same as
|
|
.Va MAKE ,
|
|
for compatibility.
|
|
The preferred variable to use is the environment variable
|
|
.Ev MAKE
|
|
because it is more compatible with other make variants
|
|
and cannot be confused with the special target with the same name.
|
|
.\" '.MAKE.cmd_filtered' is intentionally undocumented,
|
|
.\" as it is an internal implementation detail.
|
|
.It Va .MAKE.DEPENDFILE
|
|
Names the makefile (default
|
|
.Sq Pa .depend )
|
|
from which generated dependencies are read.
|
|
.It Va .MAKE.DIE_QUIETLY
|
|
If set to
|
|
.Ql true ,
|
|
do not print error information at the end.
|
|
.It Va .MAKE.EXPAND_VARIABLES
|
|
A boolean that controls the default behavior of the
|
|
.Fl V
|
|
option.
|
|
If true, variable values printed with
|
|
.Fl V
|
|
are fully expanded; if false, the raw variable contents (which may
|
|
include additional unexpanded variable references) are shown.
|
|
.It Va .MAKE.EXPORTED
|
|
The list of variables exported by
|
|
.Nm .
|
|
.It Va MAKEFILE
|
|
The top-level makefile that is currently read,
|
|
as given in the command line.
|
|
.It Va .MAKEFLAGS
|
|
The environment variable
|
|
.Sq Ev MAKEFLAGS
|
|
may contain anything that
|
|
may be specified on
|
|
.Nm Ns 's
|
|
command line.
|
|
Anything specified on
|
|
.Nm Ns 's
|
|
command line is appended to the
|
|
.Va .MAKEFLAGS
|
|
variable, which is then added to the environment for all programs that
|
|
.Nm
|
|
executes.
|
|
.It Va .MAKE.GID
|
|
The numeric group ID of the user running
|
|
.Nm .
|
|
It is read-only.
|
|
.It Va .MAKE.JOB.PREFIX
|
|
If
|
|
.Nm
|
|
is run with
|
|
.Fl j ,
|
|
the output for each target is prefixed with a token
|
|
.Dl --- Ar target Li ---
|
|
the first part of which can be controlled via
|
|
.Va .MAKE.JOB.PREFIX .
|
|
If
|
|
.Va .MAKE.JOB.PREFIX
|
|
is empty, no token is printed.
|
|
For example, setting
|
|
.Va .MAKE.JOB.PREFIX
|
|
to
|
|
.Ql ${.newline}---${.MAKE:T}[${.MAKE.PID}]
|
|
would produce tokens like
|
|
.Dl ---make[1234] Ar target Li ---
|
|
making it easier to track the degree of parallelism being achieved.
|
|
.It Va .MAKE.JOBS
|
|
The argument to the
|
|
.Fl j
|
|
option.
|
|
.It Va .MAKE.LEVEL
|
|
The recursion depth of
|
|
.Nm .
|
|
The top-level instance of
|
|
.Nm
|
|
has level 0, and each child make has its parent level plus 1.
|
|
This allows tests like:
|
|
.Li .if ${.MAKE.LEVEL} == 0
|
|
to protect things which should only be evaluated in the top-level instance of
|
|
.Nm .
|
|
.It Va .MAKE.LEVEL.ENV
|
|
The name of the environment variable that stores the level of nested calls to
|
|
.Nm .
|
|
.It Va .MAKE.MAKEFILE_PREFERENCE
|
|
The ordered list of makefile names
|
|
(default
|
|
.Sq Pa makefile ,
|
|
.Sq Pa Makefile )
|
|
that
|
|
.Nm
|
|
looks for.
|
|
.It Va .MAKE.MAKEFILES
|
|
The list of makefiles read by
|
|
.Nm ,
|
|
which is useful for tracking dependencies.
|
|
Each makefile is recorded only once, regardless of the number of times read.
|
|
.It Va .MAKE.META.BAILIWICK
|
|
In
|
|
.Dq meta
|
|
mode, provides a list of prefixes which
|
|
match the directories controlled by
|
|
.Nm .
|
|
If a file that was generated outside of
|
|
.Va .OBJDIR
|
|
but within said bailiwick is missing,
|
|
the current target is considered out-of-date.
|
|
.It Va .MAKE.META.CMP_FILTER
|
|
In
|
|
.Dq meta
|
|
mode, it can (very rarely!) be useful to filter command
|
|
lines before comparison.
|
|
This variable can be set to a set of modifiers that are applied to
|
|
each line of the old and new command that differ, if the filtered
|
|
commands still differ, the target is considered out-of-date.
|
|
.It Va .MAKE.META.CREATED
|
|
In
|
|
.Dq meta
|
|
mode, this variable contains a list of all the meta files
|
|
updated.
|
|
If not empty, it can be used to trigger processing of
|
|
.Va .MAKE.META.FILES .
|
|
.It Va .MAKE.META.FILES
|
|
In
|
|
.Dq meta
|
|
mode, this variable contains a list of all the meta files
|
|
used (updated or not).
|
|
This list can be used to process the meta files to extract dependency
|
|
information.
|
|
.It Va .MAKE.META.IGNORE_FILTER
|
|
Provides a list of variable modifiers to apply to each pathname.
|
|
Ignore if the expansion is an empty string.
|
|
.It Va .MAKE.META.IGNORE_PATHS
|
|
Provides a list of path prefixes that should be ignored;
|
|
because the contents are expected to change over time.
|
|
The default list includes:
|
|
.Sq Pa /dev /etc /proc /tmp /var/run /var/tmp
|
|
.It Va .MAKE.META.IGNORE_PATTERNS
|
|
Provides a list of patterns to match against pathnames.
|
|
Ignore any that match.
|
|
.It Va .MAKE.META.PREFIX
|
|
Defines the message printed for each meta file updated in
|
|
.Dq meta verbose
|
|
mode.
|
|
The default value is:
|
|
.Dl Building ${.TARGET:H:tA}/${.TARGET:T}
|
|
.It Va .MAKE.MODE
|
|
Processed after reading all makefiles.
|
|
Affects the mode that
|
|
.Nm
|
|
runs in.
|
|
It can contain these keywords:
|
|
.Bl -tag -width indent
|
|
.It Cm compat
|
|
Like
|
|
.Fl B ,
|
|
puts
|
|
.Nm
|
|
into
|
|
.Dq compat
|
|
mode.
|
|
.It Cm meta
|
|
Puts
|
|
.Nm
|
|
into
|
|
.Dq meta
|
|
mode, where meta files are created for each target
|
|
to capture the command run, the output generated, and if
|
|
.Xr filemon 4
|
|
is available, the system calls which are of interest to
|
|
.Nm .
|
|
The captured output can be useful when diagnosing errors.
|
|
.It Cm curdirOk= Ns Ar bf
|
|
By default,
|
|
.Nm
|
|
does not create
|
|
.Pa .meta
|
|
files in
|
|
.Sq Va .CURDIR .
|
|
This can be overridden by setting
|
|
.Ar bf
|
|
to a value which represents true.
|
|
.It Cm missing-meta= Ns Ar bf
|
|
If
|
|
.Ar bf
|
|
is true, a missing
|
|
.Pa .meta
|
|
file makes the target out-of-date.
|
|
.It Cm missing-filemon= Ns Ar bf
|
|
If
|
|
.Ar bf
|
|
is true, missing filemon data makes the target out-of-date.
|
|
.It Cm nofilemon
|
|
Do not use
|
|
.Xr filemon 4 .
|
|
.It Cm env
|
|
For debugging, it can be useful to include the environment
|
|
in the
|
|
.Pa .meta
|
|
file.
|
|
.It Cm verbose
|
|
If in
|
|
.Dq meta
|
|
mode, print a clue about the target being built.
|
|
This is useful if the build is otherwise running silently.
|
|
The message printed is the expanded value of
|
|
.Va .MAKE.META.PREFIX .
|
|
.It Cm ignore-cmd
|
|
Some makefiles have commands which are simply not stable.
|
|
This keyword causes them to be ignored for
|
|
determining whether a target is out of date in
|
|
.Dq meta
|
|
mode.
|
|
See also
|
|
.Ic .NOMETA_CMP .
|
|
.It Cm silent= Ns Ar bf
|
|
If
|
|
.Ar bf
|
|
is true, when a .meta file is created, mark the target
|
|
.Ic .SILENT .
|
|
.It Cm randomize-targets
|
|
In both compat and parallel mode, do not make the targets in the usual order,
|
|
but instead randomize their order.
|
|
This mode can be used to detect undeclared dependencies between files.
|
|
.El
|
|
.It Va MAKEOBJDIR
|
|
Used to create files in a separate directory, see
|
|
.Va .OBJDIR .
|
|
.It Va MAKE_OBJDIR_CHECK_WRITABLE
|
|
Used to force a separate directory for the created files,
|
|
even if that directory is not writable, see
|
|
.Va .OBJDIR .
|
|
.It Va MAKEOBJDIRPREFIX
|
|
Used to create files in a separate directory, see
|
|
.Va .OBJDIR .
|
|
.It Va .MAKE.OS
|
|
The name of the operating system, see
|
|
.Xr uname 1 .
|
|
It is read-only.
|
|
.It Va .MAKEOVERRIDES
|
|
This variable is used to record the names of variables assigned to
|
|
on the command line, so that they may be exported as part of
|
|
.Sq Ev MAKEFLAGS .
|
|
This behavior can be disabled by assigning an empty value to
|
|
.Sq Va .MAKEOVERRIDES
|
|
within a makefile.
|
|
Extra variables can be exported from a makefile
|
|
by appending their names to
|
|
.Sq Va .MAKEOVERRIDES .
|
|
.Sq Ev MAKEFLAGS
|
|
is re-exported whenever
|
|
.Sq Va .MAKEOVERRIDES
|
|
is modified.
|
|
.It Va .MAKE.PATH_FILEMON
|
|
If
|
|
.Nm
|
|
was built with
|
|
.Xr filemon 4
|
|
support, this is set to the path of the device node.
|
|
This allows makefiles to test for this support.
|
|
.It Va .MAKE.PID
|
|
The process ID of
|
|
.Nm .
|
|
It is read-only.
|
|
.It Va .MAKE.PPID
|
|
The parent process ID of
|
|
.Nm .
|
|
It is read-only.
|
|
.It Va MAKE_PRINT_VAR_ON_ERROR
|
|
When
|
|
.Nm
|
|
stops due to an error, it sets
|
|
.Sq Va .ERROR_TARGET
|
|
to the name of the target that failed,
|
|
.Sq Va .ERROR_CMD
|
|
to the commands of the failed target,
|
|
and in
|
|
.Dq meta
|
|
mode, it also sets
|
|
.Sq Va .ERROR_CWD
|
|
to the
|
|
.Xr getcwd 3 ,
|
|
and
|
|
.Sq Va .ERROR_META_FILE
|
|
to the path of the meta file (if any) describing the failed target.
|
|
It then prints its name and the value of
|
|
.Sq Va .CURDIR
|
|
as well as the value of any variables named in
|
|
.Sq Va MAKE_PRINT_VAR_ON_ERROR .
|
|
.It Va .MAKE.SAVE_DOLLARS
|
|
If true,
|
|
.Ql $$
|
|
are preserved when doing
|
|
.Ql :=
|
|
assignments.
|
|
The default is false, for backwards compatibility.
|
|
Set to true for compatability with other makes.
|
|
If set to false,
|
|
.Ql $$
|
|
becomes
|
|
.Ql $
|
|
per normal evaluation rules.
|
|
.It Va .MAKE.TARGET_LOCAL_VARIABLES
|
|
If set to
|
|
.Ql false ,
|
|
apparent variable assignments in dependency lines are
|
|
treated as normal sources.
|
|
.It Va .MAKE.UID
|
|
The numeric ID of the user running
|
|
.Nm .
|
|
It is read-only.
|
|
.\" 'MAKE_VERSION' is intentionally undocumented
|
|
.\" since it is only defined in the bmake distribution,
|
|
.\" but not in NetBSD's native make.
|
|
.\" '.meta.%d.lcwd' is intentionally undocumented
|
|
.\" since it is an internal implementation detail.
|
|
.\" '.meta.%d.ldir' is intentionally undocumented
|
|
.\" since it is an internal implementation detail.
|
|
.\" 'MFLAGS' is intentionally undocumented
|
|
.\" since it is obsolete.
|
|
.It Va .newline
|
|
This variable is simply assigned a newline character as its value.
|
|
It is read-only.
|
|
This allows expansions using the
|
|
.Cm \&:@
|
|
modifier to put a newline between
|
|
iterations of the loop rather than a space.
|
|
For example, in case of an error,
|
|
.Nm
|
|
prints the variable names and their values using:
|
|
.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
|
|
.It Va .OBJDIR
|
|
A path to the directory where the targets are built.
|
|
Its value is determined by trying to
|
|
.Xr chdir 2
|
|
to the following directories in order and using the first match:
|
|
.Bl -enum
|
|
.It
|
|
.Cm ${MAKEOBJDIRPREFIX} Ns Cm ${.CURDIR}
|
|
.Pp
|
|
(Only if
|
|
.Sq Ev MAKEOBJDIRPREFIX
|
|
is set in the environment or on the command line.)
|
|
.It
|
|
.Cm ${MAKEOBJDIR}
|
|
.Pp
|
|
(Only if
|
|
.Sq Ev MAKEOBJDIR
|
|
is set in the environment or on the command line.)
|
|
.It
|
|
.Cm ${.CURDIR} Ns Pa /obj. Ns Cm ${MACHINE}
|
|
.It
|
|
.Cm ${.CURDIR} Ns Pa /obj
|
|
.It
|
|
.Pa /usr/obj/ Ns Cm ${.CURDIR}
|
|
.It
|
|
.Cm ${.CURDIR}
|
|
.El
|
|
.Pp
|
|
Variable expansion is performed on the value before it is used,
|
|
so expressions such as
|
|
.Cm ${.CURDIR:S,^/usr/src,/var/obj,}
|
|
may be used.
|
|
This is especially useful with
|
|
.Sq Ev MAKEOBJDIR .
|
|
.Pp
|
|
.Sq Va .OBJDIR
|
|
may be modified in the makefile via the special target
|
|
.Sq Ic .OBJDIR .
|
|
In all cases,
|
|
.Nm
|
|
changes to the specified directory if it exists, and sets
|
|
.Sq Va .OBJDIR
|
|
and
|
|
.Sq Va PWD
|
|
to that directory before executing any targets.
|
|
.Pp
|
|
Except in the case of an explicit
|
|
.Sq Ic .OBJDIR
|
|
target,
|
|
.Nm
|
|
checks that the specified directory is writable and ignores it if not.
|
|
This check can be skipped by setting the environment variable
|
|
.Sq Ev MAKE_OBJDIR_CHECK_WRITABLE
|
|
to
|
|
.Dq no .
|
|
.It Va .PARSEDIR
|
|
The directory name of the current makefile being parsed.
|
|
.It Va .PARSEFILE
|
|
The basename of the current makefile being parsed.
|
|
This variable and
|
|
.Sq Va .PARSEDIR
|
|
are both set only while the makefiles are being parsed.
|
|
To retain their current values,
|
|
assign them to a variable using assignment with expansion
|
|
.Sq Cm \&:= .
|
|
.It Va .PATH
|
|
The space-separated list of directories that
|
|
.Nm
|
|
searches for files.
|
|
To update this search list, use the special target
|
|
.Sq Ic .PATH
|
|
rather than modifying the variable directly.
|
|
.It Va %POSIX
|
|
Is set in POSIX mode, see the special
|
|
.Ql Va .POSIX
|
|
target.
|
|
.\" XXX: There is no make variable named 'PWD',
|
|
.\" XXX: make only reads and writes the environment variable 'PWD'.
|
|
.It Va PWD
|
|
Alternate path to the current directory.
|
|
.Nm
|
|
normally sets
|
|
.Sq Va .CURDIR
|
|
to the canonical path given by
|
|
.Xr getcwd 3 .
|
|
However, if the environment variable
|
|
.Sq Ev PWD
|
|
is set and gives a path to the current directory,
|
|
.Nm
|
|
sets
|
|
.Sq Va .CURDIR
|
|
to the value of
|
|
.Sq Ev PWD
|
|
instead.
|
|
This behavior is disabled if
|
|
.Sq Ev MAKEOBJDIRPREFIX
|
|
is set or
|
|
.Sq Ev MAKEOBJDIR
|
|
contains a variable transform.
|
|
.Sq Va PWD
|
|
is set to the value of
|
|
.Sq Va .OBJDIR
|
|
for all programs which
|
|
.Nm
|
|
executes.
|
|
.It Va .SHELL
|
|
The pathname of the shell used to run target scripts.
|
|
It is read-only.
|
|
.It Va .SUFFIXES
|
|
The list of known suffixes.
|
|
It is read-only.
|
|
.It Va .SYSPATH
|
|
The space-separated list of directories that
|
|
.Nm
|
|
searches for makefiles, referred to as the system include path.
|
|
To update this search list, use the special target
|
|
.Sq Ic .SYSPATH
|
|
rather than modifying the variable which is read-only.
|
|
.It Va .TARGETS
|
|
The list of targets explicitly specified on the command line, if any.
|
|
.It Va VPATH
|
|
The colon-separated
|
|
.Pq Dq \&:
|
|
list of directories that
|
|
.Nm
|
|
searches for files.
|
|
This variable is supported for compatibility with old make programs only, use
|
|
.Sq Va .PATH
|
|
instead.
|
|
.El
|
|
.Ss Variable modifiers
|
|
The general format of a variable expansion is:
|
|
.Pp
|
|
.Sm off
|
|
.D1 Ic \&${ Ar variable\| Oo Ic \&: Ar modifier\| Oo Ic \&: No ... Oc Oc Ic \&}
|
|
.Sm on
|
|
.Pp
|
|
Each modifier begins with a colon.
|
|
To escape a colon, precede it with a backslash
|
|
.Ql \e .
|
|
.Pp
|
|
A list of indirect modifiers can be specified via a variable, as follows:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
.Ar modifier_variable\^ Li \&= Ar modifier Ns Oo Ic \&: Ns No ... Oc
|
|
|
|
.Sm off
|
|
.Ic \&${ Ar variable Ic \&:${ Ar modifier_variable Ic \&} Oo Ic \&: No ... Oc Ic \&}
|
|
.Sm on
|
|
.Ed
|
|
.Pp
|
|
In this case, the first modifier in the
|
|
.Ar modifier_variable
|
|
does not start with a colon,
|
|
since that colon already occurs in the referencing variable.
|
|
If any of the modifiers in the
|
|
.Ar modifier_variable
|
|
contains a dollar sign
|
|
.Pq Ql $ ,
|
|
these must be doubled to avoid early expansion.
|
|
.Pp
|
|
Some modifiers interpret the expression value as a single string,
|
|
others treat the expression value as a whitespace-separated list of words.
|
|
When splitting a string into words,
|
|
whitespace can be escaped using double quotes, single quotes and backslashes,
|
|
like in the shell.
|
|
The quotes and backslashes are retained in the words.
|
|
.Pp
|
|
The supported modifiers are:
|
|
.Bl -tag -width EEE
|
|
.It Cm \&:E
|
|
Replaces each word with its suffix.
|
|
.It Cm \&:H
|
|
Replaces each word with its dirname.
|
|
.It Cm \&:M\| Ns Ar pattern
|
|
Selects only those words that match
|
|
.Ar pattern .
|
|
The standard shell wildcard characters
|
|
.Pf ( Ql * ,
|
|
.Ql \&? ,
|
|
and
|
|
.Ql \&[] )
|
|
may
|
|
be used.
|
|
The wildcard characters may be escaped with a backslash
|
|
.Pq Ql \e .
|
|
As a consequence of the way values are split into words, matched,
|
|
and then joined, the construct
|
|
.Ql ${VAR:M*}
|
|
removes all leading and trailing whitespace
|
|
and normalizes the inter-word spacing to a single space.
|
|
.It Cm \&:N\| Ns Ar pattern
|
|
This is the opposite of
|
|
.Sq Cm \&:M ,
|
|
selecting all words which do
|
|
.Em not
|
|
match
|
|
.Ar pattern .
|
|
.It Cm \&:O
|
|
Orders the words lexicographically.
|
|
.It Cm \&:On
|
|
Orders the words numerically.
|
|
A number followed by one of
|
|
.Ql k ,
|
|
.Ql M
|
|
or
|
|
.Ql G
|
|
is multiplied by the appropriate factor, which is 1024 for
|
|
.Ql k ,
|
|
1048576 for
|
|
.Ql M ,
|
|
or 1073741824 for
|
|
.Ql G .
|
|
Both upper- and lower-case letters are accepted.
|
|
.It Cm \&:Or
|
|
Orders the words in reverse lexicographical order.
|
|
.It Cm \&:Orn
|
|
Orders the words in reverse numerical order.
|
|
.It Cm \&:Ox
|
|
Shuffles the words.
|
|
The results are different each time you are referring to the
|
|
modified variable; use the assignment with expansion
|
|
.Sq Cm \&:=
|
|
to prevent such behavior.
|
|
For example,
|
|
.Bd -literal -offset indent
|
|
LIST= uno due tre quattro
|
|
RANDOM_LIST= ${LIST:Ox}
|
|
STATIC_RANDOM_LIST:= ${LIST:Ox}
|
|
|
|
all:
|
|
@echo "${RANDOM_LIST}"
|
|
@echo "${RANDOM_LIST}"
|
|
@echo "${STATIC_RANDOM_LIST}"
|
|
@echo "${STATIC_RANDOM_LIST}"
|
|
.Ed
|
|
may produce output similar to:
|
|
.Bd -literal -offset indent
|
|
quattro due tre uno
|
|
tre due quattro uno
|
|
due uno quattro tre
|
|
due uno quattro tre
|
|
.Ed
|
|
.It Cm \&:Q
|
|
Quotes every shell meta-character in the value, so that it can be passed
|
|
safely to the shell.
|
|
.It Cm \&:q
|
|
Quotes every shell meta-character in the value, and also doubles
|
|
.Sq $
|
|
characters so that it can be passed
|
|
safely through recursive invocations of
|
|
.Nm .
|
|
This is equivalent to
|
|
.Sq Cm \&:S/\e\&$/&&/g:Q .
|
|
.It Cm \&:R
|
|
Replaces each word with everything but its suffix.
|
|
.It Cm \&:range Ns Oo Cm = Ns Ar count Oc
|
|
The value is an integer sequence representing the words of the original
|
|
value, or the supplied
|
|
.Ar count .
|
|
.It Cm \&:gmtime Ns Oo Cm = Ns Ar timestamp Oc
|
|
The value is interpreted as a format string for
|
|
.Xr strftime 3 ,
|
|
using
|
|
.Xr gmtime 3 ,
|
|
producing the formatted timestamp.
|
|
If a
|
|
.Ar timestamp
|
|
value is not provided or is 0, the current time is used.
|
|
.It Cm \&:hash
|
|
Computes a 32-bit hash of the value and encodes it as 8 hex digits.
|
|
.It Cm \&:localtime Ns Oo Cm = Ns Ar timestamp Oc
|
|
The value is interpreted as a format string for
|
|
.Xr strftime 3 ,
|
|
using
|
|
.Xr localtime 3 ,
|
|
producing the formatted timestamp.
|
|
If a
|
|
.Ar timestamp
|
|
value is not provided or is 0, the current time is used.
|
|
.It Cm \&:tA
|
|
Attempts to convert the value to an absolute path using
|
|
.Xr realpath 3 .
|
|
If that fails, the value is unchanged.
|
|
.It Cm \&:tl
|
|
Converts the value to lower-case letters.
|
|
.It Cm \&:ts Ns Ar c
|
|
When joining the words after a modifier that treats the value as words,
|
|
the words are normally separated by a space.
|
|
This modifier changes the separator to the character
|
|
.Ar c .
|
|
If
|
|
.Ar c
|
|
is omitted, no separator is used.
|
|
The common escapes (including octal numeric codes) work as expected.
|
|
.It Cm \&:tu
|
|
Converts the value to upper-case letters.
|
|
.It Cm \&:tW
|
|
Causes subsequent modifiers to treat the value as a single word
|
|
(possibly containing embedded whitespace).
|
|
See also
|
|
.Sq Cm \&:[*] .
|
|
.It Cm \&:tw
|
|
Causes the value to be treated as a list of words.
|
|
See also
|
|
.Sq Cm \&:[@] .
|
|
.Sm off
|
|
.It Cm \&:S\| No \&/ Ar old_string\| No \&/ Ar new_string\| No \&/ Op Cm 1gW
|
|
.Sm on
|
|
Modifies the first occurrence of
|
|
.Ar old_string
|
|
in each word of the value, replacing it with
|
|
.Ar new_string .
|
|
If a
|
|
.Ql g
|
|
is appended to the last delimiter of the pattern,
|
|
all occurrences in each word are replaced.
|
|
If a
|
|
.Ql 1
|
|
is appended to the last delimiter of the pattern,
|
|
only the first occurrence is affected.
|
|
If a
|
|
.Ql W
|
|
is appended to the last delimiter of the pattern,
|
|
the value is treated as a single word.
|
|
If
|
|
.Ar old_string
|
|
begins with a caret
|
|
.Pq Ql ^ ,
|
|
.Ar old_string
|
|
is anchored at the beginning of each word.
|
|
If
|
|
.Ar old_string
|
|
ends with a dollar sign
|
|
.Pq Ql \&$ ,
|
|
it is anchored at the end of each word.
|
|
Inside
|
|
.Ar new_string ,
|
|
an ampersand
|
|
.Pq Ql &
|
|
is replaced by
|
|
.Ar old_string
|
|
(without the anchoring
|
|
.Ql ^
|
|
or
|
|
.Ql \&$ ) .
|
|
Any character may be used as the delimiter for the parts of the modifier
|
|
string.
|
|
The anchoring, ampersand and delimiter characters can be escaped with a
|
|
backslash
|
|
.Pq Ql \e .
|
|
.Pp
|
|
Both
|
|
.Ar old_string
|
|
and
|
|
.Ar new_string
|
|
may contain nested expressions.
|
|
To prevent a dollar sign from starting a nested expression,
|
|
escape it with a backslash.
|
|
.Sm off
|
|
.It Cm \&:C\| No \&/ Ar pattern\| No \&/ Ar replacement\| No \&/ Op Cm 1gW
|
|
.Sm on
|
|
The
|
|
.Cm \&:C
|
|
modifier works like the
|
|
.Cm \&:S
|
|
modifier except that the old and new strings, instead of being
|
|
simple strings, are an extended regular expression
|
|
.Ar pattern
|
|
(see
|
|
.Xr regex 3 )
|
|
and an
|
|
.Xr ed 1 Ns \-style
|
|
.Ar replacement .
|
|
Normally, the first occurrence of the pattern
|
|
.Ar pattern
|
|
in each word of the value is substituted with
|
|
.Ar replacement .
|
|
The
|
|
.Ql 1
|
|
modifier causes the substitution to apply to at most one word; the
|
|
.Ql g
|
|
modifier causes the substitution to apply to as many instances of the
|
|
search pattern
|
|
.Ar pattern
|
|
as occur in the word or words it is found in; the
|
|
.Ql W
|
|
modifier causes the value to be treated as a single word
|
|
(possibly containing embedded whitespace).
|
|
.Pp
|
|
As for the
|
|
.Cm \&:S
|
|
modifier, the
|
|
.Ar pattern
|
|
and
|
|
.Ar replacement
|
|
are subjected to variable expansion before being parsed as
|
|
regular expressions.
|
|
.It Cm \&:T
|
|
Replaces each word with its last path component (basename).
|
|
.It Cm \&:u
|
|
Removes adjacent duplicate words (like
|
|
.Xr uniq 1 ) .
|
|
.Sm off
|
|
.It Cm \&:\&?\| Ar true_string\| Cm \&: Ar false_string
|
|
.Sm on
|
|
If the variable name (not its value), when parsed as a
|
|
.Cm .if
|
|
conditional expression, evaluates to true, return as its value the
|
|
.Ar true_string ,
|
|
otherwise return the
|
|
.Ar false_string .
|
|
Since the variable name is used as the expression,
|
|
\&:\&? must be the first modifier after the variable name
|
|
.No itself Ns \^\(em\^ Ns
|
|
which, of course, usually contains variable expansions.
|
|
A common error is trying to use expressions like
|
|
.Dl ${NUMBERS:M42:?match:no}
|
|
which actually tests defined(NUMBERS).
|
|
To determine if any words match
|
|
.Dq 42 ,
|
|
you need to use something like:
|
|
.Dl ${"${NUMBERS:M42}" != \&"\&":?match:no} .
|
|
.It Cm :\| Ns Ar old_string\| Ns Cm = Ns Ar new_string
|
|
This is the
|
|
.At V
|
|
style substitution.
|
|
It can only be the last modifier specified,
|
|
as a
|
|
.Ql \&:
|
|
in either
|
|
.Ar old_string
|
|
or
|
|
.Ar new_string
|
|
is treated as a regular character, not as the end of the modifier.
|
|
.Pp
|
|
If
|
|
.Ar old_string
|
|
does not contain the pattern matching character
|
|
.Ql % ,
|
|
and the word ends with
|
|
.Ar old_string
|
|
or equals it,
|
|
that suffix is replaced with
|
|
.Ar new_string .
|
|
.Pp
|
|
Otherwise, the first
|
|
.Ql %
|
|
in
|
|
.Ar old_string
|
|
matches a possibly empty substring of arbitrary characters,
|
|
and if the whole pattern is found in the word,
|
|
the matching part is replaced with
|
|
.Ar new_string ,
|
|
and the first occurrence of
|
|
.Ql %
|
|
in
|
|
.Ar new_string
|
|
(if any) is replaced with the substring matched by the
|
|
.Ql % .
|
|
.Pp
|
|
Both
|
|
.Ar old_string
|
|
and
|
|
.Ar new_string
|
|
may contain nested expressions.
|
|
To prevent a dollar sign from starting a nested expression,
|
|
escape it with a backslash.
|
|
.Sm off
|
|
.It Cm \&:@ Ar varname\| Cm @ Ar string\| Cm @
|
|
.Sm on
|
|
This is the loop expansion mechanism from the OSF Development
|
|
Environment (ODE) make.
|
|
Unlike
|
|
.Cm \&.for
|
|
loops, expansion occurs at the time of reference.
|
|
For each word in the value, assign the word to the variable named
|
|
.Ar varname
|
|
and evaluate
|
|
.Ar string .
|
|
The ODE convention is that
|
|
.Ar varname
|
|
should start and end with a period, for example:
|
|
.Dl ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@}
|
|
.Pp
|
|
However, a single-letter variable is often more readable:
|
|
.Dl ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}
|
|
.It Cm \&:_ Ns Oo Cm = Ns Ar var Oc
|
|
Saves the current variable value in
|
|
.Ql $_
|
|
or the named
|
|
.Ar var
|
|
for later reference.
|
|
Example usage:
|
|
.Bd -literal -offset indent
|
|
M_cmpv.units = 1 1000 1000000
|
|
M_cmpv = S,., ,g:_:range:@i@+ $${_:[-$$i]} \&\\
|
|
\\* $${M_cmpv.units:[$$i]}@:S,^,expr 0 ,1:sh
|
|
|
|
.Dv .if ${VERSION:${M_cmpv}} < ${3.1.12:L:${M_cmpv}}
|
|
|
|
.Ed
|
|
Here
|
|
.Ql $_
|
|
is used to save the result of the
|
|
.Ql :S
|
|
modifier which is later referenced using the index values from
|
|
.Ql :range .
|
|
.It Cm \&:U\| Ns Ar newval
|
|
If the variable is undefined,
|
|
.Ar newval
|
|
is the value.
|
|
If the variable is defined, the existing value is returned.
|
|
This is another ODE make feature.
|
|
It is handy for setting per-target CFLAGS for instance:
|
|
.Dl ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}}
|
|
If a value is only required if the variable is undefined, use:
|
|
.Dl ${VAR:D:Unewval}
|
|
.It Cm \&:D\| Ns Ar newval
|
|
If the variable is defined,
|
|
.Ar newval
|
|
is the value.
|
|
.It Cm \&:L
|
|
The name of the variable is the value.
|
|
.It Cm \&:P
|
|
The path of the node which has the same name as the variable is the value.
|
|
If no such node exists or its path is null, the name of the variable is used.
|
|
In order for this modifier to work, the name (node) must at least have
|
|
appeared on the right-hand side of a dependency.
|
|
.Sm off
|
|
.It Cm \&:\&! Ar cmd\| Cm \&!
|
|
.Sm on
|
|
The output of running
|
|
.Ar cmd
|
|
is the value.
|
|
.It Cm \&:sh
|
|
The value is run as a command, and the output becomes the new value.
|
|
.It Cm \&::= Ns Ar str
|
|
The variable is assigned the value
|
|
.Ar str
|
|
after substitution.
|
|
This modifier and its variations are useful in obscure situations
|
|
such as wanting to set a variable
|
|
at a point where a target's shell commands are being parsed.
|
|
These assignment modifiers always expand to nothing.
|
|
.Pp
|
|
The
|
|
.Sq Cm \&::
|
|
helps avoid false matches with the
|
|
.At V
|
|
style
|
|
.Ql \&:=
|
|
modifier and since substitution always occurs, the
|
|
.Ql \&::=
|
|
form is vaguely appropriate.
|
|
.It Cm \&::?= Ns Ar str
|
|
As for
|
|
.Cm \&::=
|
|
but only if the variable does not already have a value.
|
|
.It Cm \&::+= Ns Ar str
|
|
Append
|
|
.Ar str
|
|
to the variable.
|
|
.It Cm \&::!= Ns Ar cmd
|
|
Assign the output of
|
|
.Ar cmd
|
|
to the variable.
|
|
.It Cm \&:\&[ Ns Ar range Ns Cm \&]
|
|
Selects one or more words from the value,
|
|
or performs other operations related to the way in which the
|
|
value is split into words.
|
|
.Pp
|
|
An empty value, or a value that consists entirely of white-space,
|
|
is treated as a single word.
|
|
For the purposes of the
|
|
.Sq Cm \&:[]
|
|
modifier, the words are indexed both forwards using positive integers
|
|
(where index 1 represents the first word),
|
|
and backwards using negative integers
|
|
(where index \-1 represents the last word).
|
|
.Pp
|
|
The
|
|
.Ar range
|
|
is subjected to variable expansion, and the expanded result is
|
|
then interpreted as follows:
|
|
.Bl -tag -width index
|
|
.\" :[n]
|
|
.It Ar index
|
|
Selects a single word from the value.
|
|
.\" :[start..end]
|
|
.It Ar start Ns Cm \&.. Ns Ar end
|
|
Selects all words from
|
|
.Ar start
|
|
to
|
|
.Ar end ,
|
|
inclusive.
|
|
For example,
|
|
.Sq Cm \&:[2..-1]
|
|
selects all words from the second word to the last word.
|
|
If
|
|
.Ar start
|
|
is greater than
|
|
.Ar end ,
|
|
the words are output in reverse order.
|
|
For example,
|
|
.Sq Cm \&:[-1..1]
|
|
selects all the words from last to first.
|
|
If the list is already ordered,
|
|
this effectively reverses the list,
|
|
but it is more efficient to use
|
|
.Sq Cm \&:Or
|
|
instead of
|
|
.Sq Cm \&:O:[-1..1] .
|
|
.\" :[*]
|
|
.It Cm \&*
|
|
Causes subsequent modifiers to treat the value as a single word
|
|
(possibly containing embedded whitespace).
|
|
Analogous to the effect of
|
|
.Li \&$*
|
|
in Bourne shell.
|
|
.\" :[0]
|
|
.It 0
|
|
Means the same as
|
|
.Sq Cm \&:[*] .
|
|
.\" :[*]
|
|
.It Cm \&@
|
|
Causes subsequent modifiers to treat the value as a sequence of words
|
|
delimited by whitespace.
|
|
Analogous to the effect of
|
|
.Li \&$@
|
|
in Bourne shell.
|
|
.\" :[#]
|
|
.It Cm \&#
|
|
Returns the number of words in the value.
|
|
.El \" :[range]
|
|
.El
|
|
.Sh DIRECTIVES
|
|
.Nm
|
|
offers directives for including makefiles, conditionals and for loops.
|
|
All these directives are identified by a line beginning with a single dot
|
|
.Pq Ql \&.
|
|
character, followed by the keyword of the directive, such as
|
|
.Cm include
|
|
or
|
|
.Cm if .
|
|
.Ss File inclusion
|
|
Files are included with either
|
|
.Cm \&.include \&< Ns Ar file Ns Cm \&>
|
|
or
|
|
.Cm \&.include \&\*q Ns Ar file Ns Cm \&\*q .
|
|
Variables between the angle brackets or double quotes are expanded
|
|
to form the file name.
|
|
If angle brackets are used, the included makefile is expected to be in
|
|
the system makefile directory.
|
|
If double quotes are used, the including makefile's directory and any
|
|
directories specified using the
|
|
.Fl I
|
|
option are searched before the system makefile directory.
|
|
.Pp
|
|
For compatibility with other make variants,
|
|
.Sq Cm include Ar file No ...
|
|
(without leading dot)
|
|
is also accepted.
|
|
.Pp
|
|
If the include statement is written as
|
|
.Cm .-include
|
|
or as
|
|
.Cm .sinclude ,
|
|
errors locating and/or opening include files are ignored.
|
|
.Pp
|
|
If the include statement is written as
|
|
.Cm .dinclude ,
|
|
not only are errors locating and/or opening include files ignored,
|
|
but stale dependencies within the included file are ignored just like in
|
|
.Va .MAKE.DEPENDFILE .
|
|
.Ss Exporting variables
|
|
The directives for exporting and unexporting variables are:
|
|
.Bl -tag -width Ds
|
|
.It Ic .export Ar variable No ...
|
|
Export the specified global variable.
|
|
If no variable list is provided, all globals are exported
|
|
except for internal variables (those that start with
|
|
.Ql \&. ) .
|
|
This is not affected by the
|
|
.Fl X
|
|
flag, so should be used with caution.
|
|
For compatibility with other make programs,
|
|
.Cm export Ar variable\| Ns Cm \&= Ns Ar value
|
|
(without leading dot) is also accepted.
|
|
.Pp
|
|
Appending a variable name to
|
|
.Va .MAKE.EXPORTED
|
|
is equivalent to exporting a variable.
|
|
.It Ic .export-env Ar variable No ...
|
|
The same as
|
|
.Ql .export ,
|
|
except that the variable is not appended to
|
|
.Va .MAKE.EXPORTED .
|
|
This allows exporting a value to the environment which is different from that
|
|
used by
|
|
.Nm
|
|
internally.
|
|
.It Ic .export-literal Ar variable No ...
|
|
The same as
|
|
.Ql .export-env ,
|
|
except that variables in the value are not expanded.
|
|
.It Ic .unexport Ar variable No ...
|
|
The opposite of
|
|
.Ql .export .
|
|
The specified global
|
|
.Ar variable
|
|
is removed from
|
|
.Va .MAKE.EXPORTED .
|
|
If no variable list is provided, all globals are unexported,
|
|
and
|
|
.Va .MAKE.EXPORTED
|
|
deleted.
|
|
.It Ic .unexport-env
|
|
Unexport all globals previously exported and
|
|
clear the environment inherited from the parent.
|
|
This operation causes a memory leak of the original environment,
|
|
so should be used sparingly.
|
|
Testing for
|
|
.Va .MAKE.LEVEL
|
|
being 0 would make sense.
|
|
Also note that any variables which originated in the parent environment
|
|
should be explicitly preserved if desired.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
.Li .if ${.MAKE.LEVEL} == 0
|
|
PATH := ${PATH}
|
|
.Li .unexport-env
|
|
.Li .export PATH
|
|
.Li .endif
|
|
.Pp
|
|
.Ed
|
|
Would result in an environment containing only
|
|
.Sq Ev PATH ,
|
|
which is the minimal useful environment.
|
|
.\" TODO: Check the below sentence, environment variables don't start with '.'.
|
|
Actually
|
|
.Sq Va .MAKE.LEVEL
|
|
is also pushed into the new environment.
|
|
.El
|
|
.Ss Messages
|
|
The directives for printing messages to the output are:
|
|
.Bl -tag -width Ds
|
|
.It Ic .info Ar message
|
|
The message is printed along with the name of the makefile and line number.
|
|
.It Ic .warning Ar message
|
|
The message prefixed by
|
|
.Sq Li warning:
|
|
is printed along with the name of the makefile and line number.
|
|
.It Ic .error Ar message
|
|
The message is printed along with the name of the makefile and line number,
|
|
.Nm
|
|
exits immediately.
|
|
.El
|
|
.Ss Conditionals
|
|
The directives for conditionals are:
|
|
.ds maybenot Oo Ic \&! Oc Ns
|
|
.Bl -tag
|
|
.It Ic .if \*[maybenot] Ar expression Op Ar operator expression No ...
|
|
Test the value of an expression.
|
|
.It Ic .ifdef \*[maybenot] Ar variable Op Ar operator variable No ...
|
|
Test whether a variable is defined.
|
|
.It Ic .ifndef \*[maybenot] Ar variable Op Ar operator variable No ...
|
|
Test whether a variable is not defined.
|
|
.It Ic .ifmake \*[maybenot] Ar target Op Ar operator target No ...
|
|
Test the target being requested.
|
|
.It Ic .ifnmake \*[maybenot] Ar target Op Ar operator target No ...
|
|
Test the target being requested.
|
|
.It Ic .else
|
|
Reverse the sense of the last conditional.
|
|
.It Ic .elif \*[maybenot] Ar expression Op Ar operator expression No ...
|
|
A combination of
|
|
.Sq Ic .else
|
|
followed by
|
|
.Sq Ic .if .
|
|
.It Ic .elifdef \*[maybenot] Ar variable Op Ar operator variable No ...
|
|
A combination of
|
|
.Sq Ic .else
|
|
followed by
|
|
.Sq Ic .ifdef .
|
|
.It Ic .elifndef \*[maybenot] Ar variable Op Ar operator variable No ...
|
|
A combination of
|
|
.Sq Ic .else
|
|
followed by
|
|
.Sq Ic .ifndef .
|
|
.It Ic .elifmake \*[maybenot] Ar target Op Ar operator target No ...
|
|
A combination of
|
|
.Sq Ic .else
|
|
followed by
|
|
.Sq Ic .ifmake .
|
|
.It Ic .elifnmake \*[maybenot] Ar target Op Ar operator target No ...
|
|
A combination of
|
|
.Sq Ic .else
|
|
followed by
|
|
.Sq Ic .ifnmake .
|
|
.It Ic .endif
|
|
End the body of the conditional.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar operator
|
|
may be any one of the following:
|
|
.Bl -tag
|
|
.It Ic \&|\&|
|
|
Logical OR.
|
|
.It Ic \&&&
|
|
Logical AND; of higher precedence than
|
|
.Sq Ic \&|\&| .
|
|
.El
|
|
.Pp
|
|
.Nm
|
|
only evaluates a conditional as far as is necessary to determine its value.
|
|
Parentheses can be used to override the operator precedence.
|
|
The boolean operator
|
|
.Sq Ic \&!
|
|
may be used to logically negate an entire conditional.
|
|
It is of higher precedence than
|
|
.Sq Ic \&&& .
|
|
.Pp
|
|
The value of
|
|
.Ar expression
|
|
may be any of the following function call expressions:
|
|
.Bl -tag
|
|
.Sm off
|
|
.It Ic defined Li \&( Ar varname Li \&)
|
|
.Sm on
|
|
Evaluates to true if the variable
|
|
.Ar varname
|
|
has been defined.
|
|
.Sm off
|
|
.It Ic make Li \&( Ar target Li \&)
|
|
.Sm on
|
|
Evaluates to true if the target was specified as part of
|
|
.Nm Ns 's
|
|
command line or was declared the default target (either implicitly or
|
|
explicitly, see
|
|
.Va .MAIN )
|
|
before the line containing the conditional.
|
|
.Sm off
|
|
.It Ic empty Li \&( Ar varname Oo Li : Ar modifiers Oc Li \&)
|
|
.Sm on
|
|
Evaluates to true if the expansion of the variable,
|
|
after applying the modifiers, results in an empty string.
|
|
.Sm off
|
|
.It Ic exists Li \&( Ar pathname Li \&)
|
|
.Sm on
|
|
Evaluates to true if the given pathname exists.
|
|
If relative, the pathname is searched for on the system search path (see
|
|
.Va .PATH ) .
|
|
.Sm off
|
|
.It Ic target Li \&( Ar target Li \&)
|
|
.Sm on
|
|
Evaluates to true if the target has been defined.
|
|
.Sm off
|
|
.It Ic commands Li \&( Ar target Li \&)
|
|
.Sm on
|
|
Evaluates to true if the target has been defined
|
|
and has commands associated with it.
|
|
.El
|
|
.Pp
|
|
.Ar Expression
|
|
may also be an arithmetic or string comparison.
|
|
Variable expansion is performed on both sides of the comparison.
|
|
If both sides are numeric and neither is enclosed in quotes,
|
|
the comparison is done numerically, otherwise lexicographically.
|
|
A string is interpreted as hexadecimal integer if it is preceded by
|
|
.Li 0x ,
|
|
otherwise it is a decimal floating-point number;
|
|
octal numbers are not supported.
|
|
.Pp
|
|
All comparisons may use the operators
|
|
.Sq Ic \&==
|
|
and
|
|
.Sq Ic \&!= .
|
|
Numeric comparisons may also use the operators
|
|
.Sq Ic \&< ,
|
|
.Sq Ic \&<= ,
|
|
.Sq Ic \&>
|
|
and
|
|
.Sq Ic \&>= .
|
|
.Pp
|
|
If the comparison has neither a comparison operator nor a right side,
|
|
the expression evaluates to true if it is nonempty
|
|
and its numeric value (if any) is not zero.
|
|
.Pp
|
|
When
|
|
.Nm
|
|
is evaluating one of these conditional expressions, and it encounters
|
|
a (whitespace separated) word it doesn't recognize, either the
|
|
.Dq make
|
|
or
|
|
.Dq defined
|
|
function is applied to it, depending on the form of the conditional.
|
|
If the form is
|
|
.Sq Ic .ifdef ,
|
|
.Sq Ic .ifndef
|
|
or
|
|
.Sq Ic .if ,
|
|
the
|
|
.Dq defined
|
|
function is applied.
|
|
Similarly, if the form is
|
|
.Sq Ic .ifmake
|
|
or
|
|
.Sq Ic .ifnmake ,
|
|
the
|
|
.Dq make
|
|
function is applied.
|
|
.Pp
|
|
If the conditional evaluates to true,
|
|
parsing of the makefile continues as before.
|
|
If it evaluates to false, the following lines are skipped.
|
|
In both cases, this continues until the corresponding
|
|
.Sq Ic .else
|
|
or
|
|
.Sq Ic .endif
|
|
is found.
|
|
.Ss For loops
|
|
For loops are typically used to apply a set of rules to a list of files.
|
|
The syntax of a for loop is:
|
|
.Pp
|
|
.Bl -tag -compact -width Ds
|
|
.It Ic \&.for Ar variable Oo Ar variable No ... Oc Ic in Ar expression
|
|
.It Aq Ar make-lines
|
|
.It Ic \&.endfor
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar expression
|
|
is expanded and then split into words.
|
|
On each iteration of the loop, one word is taken and assigned to each
|
|
.Ar variable ,
|
|
in order, and these
|
|
.Ar variables
|
|
are substituted into the
|
|
.Ar make-lines
|
|
inside the body of the for loop.
|
|
The number of words must come out even; that is, if there are three
|
|
iteration variables, the number of words provided must be a multiple
|
|
of three.
|
|
.Pp
|
|
If
|
|
.Sq Ic .break
|
|
is encountered within a
|
|
.Cm \&.for
|
|
loop, it causes early termination of the loop, otherwise a parse error.
|
|
.\" TODO: Describe limitations with defined/empty.
|
|
.Ss Other directives
|
|
.Bl -tag -width Ds
|
|
.It Ic .undef Ar variable No ...
|
|
Un-define the specified global variables.
|
|
Only global variables can be un-defined.
|
|
.El
|
|
.Sh COMMENTS
|
|
Comments begin with a hash
|
|
.Pq Ql \&#
|
|
character, anywhere but in a shell
|
|
command line, and continue to the end of an unescaped new line.
|
|
.Sh SPECIAL SOURCES (ATTRIBUTES)
|
|
.Bl -tag -width .IGNOREx
|
|
.It Ic .EXEC
|
|
Target is never out of date, but always execute commands anyway.
|
|
.It Ic .IGNORE
|
|
Ignore any errors from the commands associated with this target, exactly
|
|
as if they all were preceded by a dash
|
|
.Pq Ql \- .
|
|
.\" .It Ic .INVISIBLE
|
|
.\" XXX
|
|
.\" .It Ic .JOIN
|
|
.\" XXX
|
|
.It Ic .MADE
|
|
Mark all sources of this target as being up to date.
|
|
.It Ic .MAKE
|
|
Execute the commands associated with this target even if the
|
|
.Fl n
|
|
or
|
|
.Fl t
|
|
options were specified.
|
|
Normally used to mark recursive
|
|
.Nm Ns s .
|
|
.It Ic .META
|
|
Create a meta file for the target, even if it is flagged as
|
|
.Ic .PHONY ,
|
|
.Ic .MAKE ,
|
|
or
|
|
.Ic .SPECIAL .
|
|
Usage in conjunction with
|
|
.Ic .MAKE
|
|
is the most likely case.
|
|
In
|
|
.Dq meta
|
|
mode, the target is out-of-date if the meta file is missing.
|
|
.It Ic .NOMETA
|
|
Do not create a meta file for the target.
|
|
Meta files are also not created for
|
|
.Ic .PHONY ,
|
|
.Ic .MAKE ,
|
|
or
|
|
.Ic .SPECIAL
|
|
targets.
|
|
.It Ic .NOMETA_CMP
|
|
Ignore differences in commands when deciding if target is out of date.
|
|
This is useful if the command contains a value which always changes.
|
|
If the number of commands change, though,
|
|
the target is still considered out of date.
|
|
The same effect applies to any command line that uses the variable
|
|
.Va .OODATE ,
|
|
which can be used for that purpose even when not otherwise needed or desired:
|
|
.Bd -literal -offset indent
|
|
|
|
skip-compare-for-some:
|
|
@echo this is compared
|
|
@echo this is not ${.OODATE:M.NOMETA_CMP}
|
|
@echo this is also compared
|
|
|
|
.Ed
|
|
The
|
|
.Cm \&:M
|
|
pattern suppresses any expansion of the unwanted variable.
|
|
.It Ic .NOPATH
|
|
Do not search for the target in the directories specified by
|
|
.Va .PATH .
|
|
.It Ic .NOTMAIN
|
|
Normally
|
|
.Nm
|
|
selects the first target it encounters as the default target to be built
|
|
if no target was specified.
|
|
This source prevents this target from being selected.
|
|
.It Ic .OPTIONAL
|
|
If a target is marked with this attribute and
|
|
.Nm
|
|
can't figure out how to create it, it ignores this fact and assumes
|
|
the file isn't needed or already exists.
|
|
.It Ic .PHONY
|
|
The target does not correspond to an actual file;
|
|
it is always considered to be out of date,
|
|
and is not created with the
|
|
.Fl t
|
|
option.
|
|
Suffix-transformation rules are not applied to
|
|
.Ic .PHONY
|
|
targets.
|
|
.It Ic .PRECIOUS
|
|
When
|
|
.Nm
|
|
is interrupted, it normally removes any partially made targets.
|
|
This source prevents the target from being removed.
|
|
.It Ic .RECURSIVE
|
|
Synonym for
|
|
.Ic .MAKE .
|
|
.It Ic .SILENT
|
|
Do not echo any of the commands associated with this target, exactly
|
|
as if they all were preceded by an at sign
|
|
.Pq Ql @ .
|
|
.It Ic .USE
|
|
Turn the target into
|
|
.Nm Ns 's
|
|
version of a macro.
|
|
When the target is used as a source for another target, the other target
|
|
acquires the commands, sources, and attributes (except for
|
|
.Ic .USE )
|
|
of the
|
|
source.
|
|
If the target already has commands, the
|
|
.Ic .USE
|
|
target's commands are appended
|
|
to them.
|
|
.It Ic .USEBEFORE
|
|
Like
|
|
.Ic .USE ,
|
|
but instead of appending, prepend the
|
|
.Ic .USEBEFORE
|
|
target commands to the target.
|
|
.It Ic .WAIT
|
|
If
|
|
.Ic .WAIT
|
|
appears in a dependency line, the sources that precede it are
|
|
made before the sources that succeed it in the line.
|
|
Since the dependents of files are not made until the file itself
|
|
could be made, this also stops the dependents being built unless they
|
|
are needed for another branch of the dependency tree.
|
|
So given:
|
|
.Bd -literal
|
|
x: a .WAIT b
|
|
echo x
|
|
a:
|
|
echo a
|
|
b: b1
|
|
echo b
|
|
b1:
|
|
echo b1
|
|
|
|
.Ed
|
|
the output is always
|
|
.Ql a ,
|
|
.Ql b1 ,
|
|
.Ql b ,
|
|
.Ql x .
|
|
.Pp
|
|
The ordering imposed by
|
|
.Ic .WAIT
|
|
is only relevant for parallel makes.
|
|
.El
|
|
.Sh SPECIAL TARGETS
|
|
Special targets may not be included with other targets, i.e. they must be
|
|
the only target specified.
|
|
.Bl -tag -width .BEGINx
|
|
.It Ic .BEGIN
|
|
Any command lines attached to this target are executed before anything
|
|
else is done.
|
|
.It Ic .DEFAULT
|
|
This is sort of a
|
|
.Ic .USE
|
|
rule for any target (that was used only as a source) that
|
|
.Nm
|
|
can't figure out any other way to create.
|
|
Only the shell script is used.
|
|
The
|
|
.Va .IMPSRC
|
|
variable of a target that inherits
|
|
.Ic .DEFAULT Ns 's
|
|
commands is set to the target's own name.
|
|
.It Ic .DELETE_ON_ERROR
|
|
If this target is present in the makefile, it globally causes make to
|
|
delete targets whose commands fail.
|
|
(By default, only targets whose commands are interrupted during
|
|
execution are deleted.
|
|
This is the historical behavior.)
|
|
This setting can be used to help prevent half-finished or malformed
|
|
targets from being left around and corrupting future rebuilds.
|
|
.It Ic .END
|
|
Any command lines attached to this target are executed after everything
|
|
else is done successfully.
|
|
.It Ic .ERROR
|
|
Any command lines attached to this target are executed when another target fails.
|
|
The
|
|
.Va .ERROR_TARGET
|
|
variable is set to the target that failed.
|
|
See also
|
|
.Va MAKE_PRINT_VAR_ON_ERROR .
|
|
.It Ic .IGNORE
|
|
Mark each of the sources with the
|
|
.Ic .IGNORE
|
|
attribute.
|
|
If no sources are specified, this is the equivalent of specifying the
|
|
.Fl i
|
|
option.
|
|
.It Ic .INTERRUPT
|
|
If
|
|
.Nm
|
|
is interrupted, the commands for this target are executed.
|
|
.It Ic .MAIN
|
|
If no target is specified when
|
|
.Nm
|
|
is invoked, this target is built.
|
|
.It Ic .MAKEFLAGS
|
|
This target provides a way to specify flags for
|
|
.Nm
|
|
at the time when the makefiles are read.
|
|
The flags are as if typed to the shell, though the
|
|
.Fl f
|
|
option has
|
|
no effect.
|
|
.\" XXX: NOT YET!!!!
|
|
.\" .It Ic .NOTPARALLEL
|
|
.\" The named targets are executed in non parallel mode.
|
|
.\" If no targets are
|
|
.\" specified, all targets are executed in non parallel mode.
|
|
.It Ic .NOPATH
|
|
Apply the
|
|
.Ic .NOPATH
|
|
attribute to any specified sources.
|
|
.It Ic .NOTPARALLEL
|
|
Disable parallel mode.
|
|
.It Ic .NO_PARALLEL
|
|
Synonym for
|
|
.Ic .NOTPARALLEL ,
|
|
for compatibility with other pmake variants.
|
|
.It Ic .NOREADONLY
|
|
clear the read-only attribute from the global variables specified as sources.
|
|
.It Ic .OBJDIR
|
|
The source is a new value for
|
|
.Sq Va .OBJDIR .
|
|
If it exists,
|
|
.Nm
|
|
changes the current working directory to it and updates the value of
|
|
.Sq Va .OBJDIR .
|
|
.It Ic .ORDER
|
|
In parallel mode, the named targets are made in sequence.
|
|
This ordering does not add targets to the list of targets to be made.
|
|
.Pp
|
|
Since the dependents of a target do not get built until the target itself
|
|
could be built, unless
|
|
.Ql a
|
|
is built by another part of the dependency graph,
|
|
the following is a dependency loop:
|
|
.Bd -literal
|
|
\&.ORDER: b a
|
|
b: a
|
|
.Ed
|
|
.Pp
|
|
.\" XXX: NOT YET!!!!
|
|
.\" .It Ic .PARALLEL
|
|
.\" The named targets are executed in parallel mode.
|
|
.\" If no targets are
|
|
.\" specified, all targets are executed in parallel mode.
|
|
.It Ic .PATH
|
|
The sources are directories which are to be searched for files not
|
|
found in the current directory.
|
|
If no sources are specified,
|
|
any previously specified directories are removed from the search path.
|
|
If the source is the special
|
|
.Ic .DOTLAST
|
|
target, the current working directory is searched last.
|
|
.It Ic .PATH. Ns Ar suffix
|
|
Like
|
|
.Ic .PATH
|
|
but applies only to files with a particular suffix.
|
|
The suffix must have been previously declared with
|
|
.Ic .SUFFIXES .
|
|
.It Ic .PHONY
|
|
Apply the
|
|
.Ic .PHONY
|
|
attribute to any specified sources.
|
|
.It Ic .POSIX
|
|
If this is the first non-comment line in the main makefile,
|
|
the variable
|
|
.Va %POSIX
|
|
is set to the value
|
|
.Ql 1003.2
|
|
and the makefile
|
|
.Ql <posix.mk>
|
|
is included if it exists,
|
|
to provide POSIX-compatible default rules.
|
|
If
|
|
.Nm
|
|
is run with the
|
|
.Fl r
|
|
flag, only
|
|
.Ql posix.mk
|
|
contributes to the default rules.
|
|
.It Ic .PRECIOUS
|
|
Apply the
|
|
.Ic .PRECIOUS
|
|
attribute to any specified sources.
|
|
If no sources are specified, the
|
|
.Ic .PRECIOUS
|
|
attribute is applied to every target in the file.
|
|
.It Ic .READONLY
|
|
set the read-only attribute on the global variables specified as sources.
|
|
.It Ic .SHELL
|
|
Sets the shell that
|
|
.Nm
|
|
uses to execute commands in jobs mode.
|
|
The sources are a set of
|
|
.Ar field\| Ns Cm \&= Ns Ar value
|
|
pairs.
|
|
.Bl -tag -width ".Li hasErrCtls"
|
|
.It Li name
|
|
This is the minimal specification, used to select one of the built-in
|
|
shell specs;
|
|
.Li sh ,
|
|
.Li ksh ,
|
|
and
|
|
.Li csh .
|
|
.It Li path
|
|
Specifies the absolute path to the shell.
|
|
.It Li hasErrCtl
|
|
Indicates whether the shell supports exit on error.
|
|
.It Li check
|
|
The command to turn on error checking.
|
|
.It Li ignore
|
|
The command to disable error checking.
|
|
.It Li echo
|
|
The command to turn on echoing of commands executed.
|
|
.It Li quiet
|
|
The command to turn off echoing of commands executed.
|
|
.It Li filter
|
|
The output to filter after issuing the
|
|
.Li quiet
|
|
command.
|
|
It is typically identical to
|
|
.Li quiet .
|
|
.It Li errFlag
|
|
The flag to pass the shell to enable error checking.
|
|
.It Li echoFlag
|
|
The flag to pass the shell to enable command echoing.
|
|
.It Li newline
|
|
The string literal to pass the shell that results in a single newline
|
|
character when used outside of any quoting characters.
|
|
.El
|
|
Example:
|
|
.Bd -literal
|
|
\&.SHELL: name=ksh path=/bin/ksh hasErrCtl=true \e
|
|
check="set \-e" ignore="set +e" \e
|
|
echo="set \-v" quiet="set +v" filter="set +v" \e
|
|
echoFlag=v errFlag=e newline="'\en'"
|
|
.Ed
|
|
.It Ic .SILENT
|
|
Apply the
|
|
.Ic .SILENT
|
|
attribute to any specified sources.
|
|
If no sources are specified, the
|
|
.Ic .SILENT
|
|
attribute is applied to every
|
|
command in the file.
|
|
.It Ic .STALE
|
|
This target gets run when a dependency file contains stale entries, having
|
|
.Va .ALLSRC
|
|
set to the name of that dependency file.
|
|
.It Ic .SUFFIXES
|
|
Each source specifies a suffix to
|
|
.Nm .
|
|
If no sources are specified, any previously specified suffixes are deleted.
|
|
It allows the creation of suffix-transformation rules.
|
|
.Pp
|
|
Example:
|
|
.Bd -literal
|
|
\&.SUFFIXES: .c .o
|
|
\&.c.o:
|
|
cc \-o ${.TARGET} \-c ${.IMPSRC}
|
|
.Ed
|
|
.It Ic .SYSPATH
|
|
The sources are directories which are to be added to the system
|
|
include path which
|
|
.Nm
|
|
searches for makefiles.
|
|
If no sources are specified,
|
|
any previously specified directories are removed from the system
|
|
include path.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
.Nm
|
|
uses the following environment variables, if they exist:
|
|
.Ev MACHINE ,
|
|
.Ev MACHINE_ARCH ,
|
|
.Ev MAKE ,
|
|
.Ev MAKEFLAGS ,
|
|
.Ev MAKEOBJDIR ,
|
|
.Ev MAKEOBJDIRPREFIX ,
|
|
.Ev MAKESYSPATH ,
|
|
.Ev PWD ,
|
|
and
|
|
.Ev TMPDIR .
|
|
.Pp
|
|
.Ev MAKEOBJDIRPREFIX
|
|
and
|
|
.Ev MAKEOBJDIR
|
|
may only be set in the environment or on the command line to
|
|
.Nm
|
|
and not as makefile variables;
|
|
see the description of
|
|
.Sq Va .OBJDIR
|
|
for more details.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/mk -compact
|
|
.It .depend
|
|
list of dependencies
|
|
.It makefile
|
|
first default makefile if no makefile is specified on the command line
|
|
.It Makefile
|
|
second default makefile if no makefile is specified on the command line
|
|
.It sys.mk
|
|
system makefile
|
|
.It /usr/share/mk
|
|
system makefile directory
|
|
.El
|
|
.Sh COMPATIBILITY
|
|
The basic make syntax is compatible between different make variants;
|
|
however the special variables, variable modifiers and conditionals are not.
|
|
.Ss Older versions
|
|
An incomplete list of changes in older versions of
|
|
.Nm :
|
|
.Pp
|
|
The way that .for loop variables are substituted changed after
|
|
NetBSD 5.0
|
|
so that they still appear to be variable expansions.
|
|
In particular this stops them being treated as syntax, and removes some
|
|
obscure problems using them in .if statements.
|
|
.Pp
|
|
The way that parallel makes are scheduled changed in
|
|
NetBSD 4.0
|
|
so that .ORDER and .WAIT apply recursively to the dependent nodes.
|
|
The algorithms used may change again in the future.
|
|
.Ss Other make dialects
|
|
Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not
|
|
support most of the features of
|
|
.Nm
|
|
as described in this manual.
|
|
Most notably:
|
|
.Bl -bullet -offset indent
|
|
.It
|
|
The
|
|
.Ic .WAIT
|
|
and
|
|
.Ic .ORDER
|
|
declarations and most functionality pertaining to parallelization.
|
|
(GNU make supports parallelization but lacks the features needed to
|
|
control it effectively.)
|
|
.It
|
|
Directives, including for loops and conditionals and most of the
|
|
forms of include files.
|
|
(GNU make has its own incompatible and less powerful syntax for
|
|
conditionals.)
|
|
.\" The "less powerful" above means that GNU make does not have the
|
|
.\" make(target), target(target) and commands(target) functions.
|
|
.It
|
|
All built-in variables that begin with a dot.
|
|
.It
|
|
Most of the special sources and targets that begin with a dot,
|
|
with the notable exception of
|
|
.Ic .PHONY ,
|
|
.Ic .PRECIOUS ,
|
|
and
|
|
.Ic .SUFFIXES .
|
|
.It
|
|
Variable modifiers, except for the
|
|
.Ql :old=new
|
|
string substitution, which does not portably support globbing with
|
|
.Ql %
|
|
and historically only works on declared suffixes.
|
|
.It
|
|
The
|
|
.Ic $>
|
|
variable even in its short form; most makes support this functionality
|
|
but its name varies.
|
|
.El
|
|
.Pp
|
|
Some features are somewhat more portable, such as assignment with
|
|
.Ic += ,
|
|
.Ic ?= ,
|
|
and
|
|
.Ic != .
|
|
The
|
|
.Va .PATH
|
|
functionality is based on an older feature
|
|
.Ic VPATH
|
|
found in GNU make and many versions of SVR4 make; however,
|
|
historically its behavior is too ill-defined (and too buggy) to rely
|
|
upon.
|
|
.Pp
|
|
The
|
|
.Ic $@
|
|
and
|
|
.Ic $<
|
|
variables are more or less universally portable, as is the
|
|
.Ic $(MAKE)
|
|
variable.
|
|
Basic use of suffix rules (for files only in the current directory,
|
|
not trying to chain transformations together, etc.) is also reasonably
|
|
portable.
|
|
.Sh SEE ALSO
|
|
.Xr mkdep 1
|
|
.Sh HISTORY
|
|
.Nm
|
|
is derived from NetBSD
|
|
.Xr make 1 .
|
|
It uses autoconf to facilitate portability to other platforms.
|
|
.Pp
|
|
A
|
|
make
|
|
command appeared in
|
|
.At v7 .
|
|
This
|
|
make
|
|
implementation is based on Adam de Boor's pmake program,
|
|
which was written for Sprite at Berkeley.
|
|
It was designed to be a parallel distributed make running jobs on different
|
|
machines using a daemon called
|
|
.Dq customs .
|
|
.Pp
|
|
Historically the target/dependency
|
|
.Ic FRC
|
|
has been used to FoRCe rebuilding (since the target/dependency
|
|
does not exist ... unless someone creates an
|
|
.Pa FRC
|
|
file).
|
|
.Sh BUGS
|
|
The
|
|
make
|
|
syntax is difficult to parse.
|
|
For instance, finding the end of a variable's use should involve scanning
|
|
each of the modifiers, using the correct terminator for each field.
|
|
In many places
|
|
make
|
|
just counts {} and () in order to find the end of a variable expansion.
|
|
.Pp
|
|
There is no way of escaping a space character in a filename.
|
|
.Pp
|
|
In jobs mode, when a target fails;
|
|
make
|
|
will put an error token into the job token pool.
|
|
This will cause all other instances of
|
|
make
|
|
using that token pool to abort the build and exit with error code 6.
|
|
Sometimes the attempt to suppress a cascade of unnecessary errors,
|
|
can result in a seemingly unexplained
|
|
.Ql *** Error code 6
|
|
|
|
|