oasis-root

make.1p (71589B)

'\" et
.TH MAKE "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
make
\(em maintain, update, and regenerate groups of programs
(\fBDEVELOPMENT\fP)
.SH SYNOPSIS
.LP
.nf
make \fB[\fR-einpqrst\fB] [\fR-f \fImakefile\fB]\fR... \fB[\fR-k|-S\fB] [\fImacro\fR=\fIvalue\fR...\fB]
    \fB[\fItarget_name\fR...\fB]\fR
.fi
.SH DESCRIPTION
The
.IR make
utility shall update files that are derived from other files. A typical
case is one where object files are derived from the corresponding
source files. The
.IR make
utility examines time relationships and shall update those derived files
(called targets) that have modified times earlier than the modified
times of the files (called prerequisites) from which they are derived.
A description file (makefile) contains a description of the
relationships between files, and the commands that need to be executed
to update the targets to reflect changes in their prerequisites. Each
specification, or rule, shall consist of a target, optional
prerequisites, and optional commands to be executed when a prerequisite
is newer than the target. There are two types of rule:
.IP " 1." 4
\fIInference rules\fP,
which have one target name with at least one
<period>
(\c
.BR '.' )
and no
<slash>
(\c
.BR '/' )
.IP " 2." 4
\fITarget rules\fP,
which can have more than one target name
.P
In addition,
.IR make
shall have a collection of built-in macros and inference rules that
infer prerequisite relationships to simplify maintenance of programs.
.P
To receive exactly the behavior described in this section, the
user shall ensure that a portable makefile shall:
.IP " *" 4
Include the special target
.BR .POSIX
.IP " *" 4
Omit any special target reserved for implementations (a leading period
followed by uppercase letters) that has not been specified by this
section
.P
The behavior of
.IR make
is unspecified if either or both of these conditions are not met.
.SH OPTIONS
The
.IR make
utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines",
except for Guideline 9.
.P
The following options shall be supported:
.IP "\fB\-e\fP" 10
Cause environment variables, including those with null values, to
override macro assignments within makefiles.
.IP "\fB\-f\ \fImakefile\fR" 10
Specify a different makefile. The argument
.IR makefile
is a pathname of a description file, which is also referred to as the
.IR makefile .
A pathname of
.BR '\-' 
shall denote the standard input. There can be multiple instances of
this option, and they shall be processed in the order specified. The
effect of specifying the same option-argument more than once is
unspecified.
.IP "\fB\-i\fP" 10
Ignore error codes returned by invoked commands. This mode is the same
as if the special target
.BR .IGNORE
were specified without prerequisites.
.IP "\fB\-k\fP" 10
Continue to update other targets that do not depend on the current
target if a non-ignored error occurs while executing the commands to
bring a target up-to-date.
.IP "\fB\-n\fP" 10
Write commands that would be executed on standard output, but do not
execute them. However, lines with a
<plus-sign>
(\c
.BR '\(pl' )
prefix shall be executed. In this mode, lines with an at-sign (\c
.BR '@' )
character prefix shall be written to standard output.
.IP "\fB\-p\fP" 10
Write to standard output the complete set of macro definitions and
target descriptions. The output format is unspecified.
.IP "\fB\-q\fP" 10
Return a zero exit value if the target file is up-to-date; otherwise,
return an exit value of 1. Targets shall not be updated if this option
is specified. However, a makefile command line (associated with the
targets) with a
<plus-sign>
(\c
.BR '\(pl' )
prefix shall be executed.
.IP "\fB\-r\fP" 10
Clear the suffix list and do not use the built-in rules.
.IP "\fB\-S\fP" 10
Terminate
.IR make
if an error occurs while executing the commands to bring a target
up-to-date. This shall be the default and the opposite of
.BR \-k .
.IP "\fB\-s\fP" 10
Do not write makefile command lines or touch messages (see
.BR \-t )
to standard output before executing. This mode shall be the same as if
the special target
.BR .SILENT
were specified without prerequisites.
.IP "\fB\-t\fP" 10
Update the modification time of each target as though a
.IR touch
.IR target
had been executed. Targets that have prerequisites but no commands (see
.IR "Target Rules"),
or that are already up-to-date, shall not be touched in this manner.
Write messages to standard output for each target file indicating the
name of the file and that it was touched. Normally, the
.IR makefile
command lines associated with each target are not executed. However, a
command line with a
<plus-sign>
(\c
.BR '\(pl' )
prefix shall be executed.
.P
Any options specified in the
.IR MAKEFLAGS
environment variable shall be evaluated before any options specified on
the
.IR make
utility command line. If the
.BR \-k
and
.BR \-S
options are both specified on the
.IR make
utility command line or by the
.IR MAKEFLAGS
environment variable, the last option specified shall take precedence.
If the
.BR \-f
or
.BR \-p
options appear in the
.IR MAKEFLAGS
environment variable, the result is undefined.
.SH OPERANDS
The following operands shall be supported:
.IP "\fItarget_name\fR" 10
Target names, as defined in the EXTENDED DESCRIPTION section. If no
target is specified, while
.IR make
is processing the makefiles, the first target that
.IR make
encounters that is not a special target or an inference rule shall be
used.
.IP "\fImacro\fR=\fIvalue\fR" 10
Macro definitions, as defined in
.IR "Macros".
.P
If the
.IR target_name
and
.IR macro =\c
.IR value
operands are intermixed on the
.IR make
utility command line, the results are unspecified.
.SH STDIN
The standard input shall be used only if the
.IR makefile
option-argument is
.BR '\-' .
See the INPUT FILES section.
.SH "INPUT FILES"
The input file, otherwise known as the makefile, is a text file
containing rules, macro definitions, include lines, and comments.
See the EXTENDED DESCRIPTION section.
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR make :
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 8.2" ", " "Internationalization Variables"
for the precedence of internationalization variables used to determine
the values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to
multi-byte characters in arguments and input files).
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error.
.IP "\fIMAKEFLAGS\fP" 10
.br
This variable shall be interpreted as a character string representing a
series of option characters to be used as the default options. The
implementation shall accept both of the following formats (but need not
accept them when intermixed):
.RS 10 
.IP " *" 4
The characters are option letters without the leading
<hyphen-minus>
characters or
<blank>
separation used on a
.IR make
utility command line.
.IP " *" 4
The characters are formatted in a manner similar to a portion of the
.IR make
utility command line: options are preceded by
<hyphen-minus>
characters and
<blank>-separated
as described in the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
The
.IR macro =\c
.IR value
macro definition operands can also be included. The difference between
the contents of
.IR MAKEFLAGS
and the
.IR make
utility command line is that the contents of the variable shall not be
subjected to the word expansions (see
.IR "Section 2.6" ", " "Word Expansions")
associated with parsing the command line values.
.RE
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.IP "\fIPROJECTDIR\fP" 10
.br
Provide a directory to be used to search for SCCS files not found in
the current directory. In all of the following cases, the search for
SCCS files is made in the directory
.BR SCCS
in the identified directory. If the value of
.IR PROJECTDIR
begins with a
<slash>,
it shall be considered an absolute pathname; otherwise, the value of
.IR PROJECTDIR
is treated as a user name and that user's initial working directory
shall be examined for a subdirectory
.BR src
or
.BR source .
If such a directory is found, it shall be used. Otherwise, the value
is used as a relative pathname.
.RS 10 
.P
If
.IR PROJECTDIR
is not set or has a null value, the search for SCCS files shall be made
in the directory
.BR SCCS
in the current directory.
.P
The setting of
.IR PROJECTDIR
affects all files listed in the remainder of this utility description
for files with a component named
.BR SCCS .
.RE
.P
The value of the
.IR SHELL
environment variable shall not be used as a macro and shall not be
modified by defining the
.BR SHELL
macro in a makefile or on the command line. All other environment
variables, including those with null values, shall be used as macros,
as defined in
.IR "Macros".
.SH "ASYNCHRONOUS EVENTS"
If not already ignored,
.IR make
shall trap SIGHUP, SIGTERM, SIGINT, and SIGQUIT and remove the current
target unless the target is a directory or the target is a prerequisite
of the special target
.BR .PRECIOUS
or unless one of the
.BR \-n ,
.BR \-p ,
or
.BR \-q
options was specified. Any targets removed in this manner shall be
reported in diagnostic messages of unspecified format, written to
standard error. After this cleanup process, if any,
.IR make
shall take the standard action for all other signals.
.SH STDOUT
The
.IR make
utility shall write all commands to be executed to standard output
unless the
.BR \-s
option was specified, the command is prefixed with an at-sign, or the
special target
.BR .SILENT
has either the current target as a prerequisite or has no
prerequisites. If
.IR make
is invoked without any work needing to be done, it shall write a
message to standard output indicating that no action was taken. If the
.BR \-t
option is present and a file is touched,
.IR make
shall write to standard output a message of unspecified format
indicating that the file was touched, including the filename of the
file.
.SH STDERR
The standard error shall be used only for diagnostic messages.
.SH "OUTPUT FILES"
Files can be created when the
.BR \-t
option is present. Additional files can also be created by the
utilities invoked by
.IR make .
.SH "EXTENDED DESCRIPTION"
The
.IR make
utility attempts to perform the actions required to ensure that the
specified targets are up-to-date. A target shall be considered
up-to-date if it exists and is newer than all of its dependencies, or
if it has already been made up-to-date by the current invocation of
.IR make
(regardless of the target's existence or age). A target may also be
considered up-to-date if it exists, is the same age as one or more of
its prerequisites, and is newer than the remaining prerequisites (if any).
The
.IR make
utility shall treat all prerequisites as targets themselves and
recursively ensure that they are up-to-date, processing them in the
order in which they appear in the rule. The
.IR make
utility shall use the modification times of files to determine whether
the corresponding targets are out-of-date.
.P
To ensure that a target is up-to-date,
.IR make
shall ensure that all of the prerequisites of a target are up-to-date,
then check to see if the target itself is up-to-date. If the target
is not up-to-date, the target shall be made up-to-date by executing
the rule's commands (if any). If the target does not exist after the
target has been successfully made up-to-date, the target shall be
treated as being newer than any target for which it is a prerequisite.
.P
If a target exists and there is neither a target rule nor an inference
rule for the target, the target shall be considered up-to-date. It
shall be an error if
.IR make
attempts to ensure that a target is up-to-date but the target does not
exist and there is neither a target rule nor an inference rule for the
target.
.SS "Makefile Syntax"
.P
A makefile can contain rules, macro definitions (see
.IR "Macros"),
include lines, and comments. There are two kinds of rules:
.IR "inference rules"
and
.IR "target rules" .
The
.IR make
utility shall contain a set of built-in inference rules. If the
.BR \-r
option is present, the built-in rules shall not be used and the suffix
list shall be cleared. Additional rules of both types can be specified
in a makefile. If a rule is defined more than once, the value of the
rule shall be that of the last one specified. Macros can also be
defined more than once, and the value of the macro is specified in
.IR "Macros".
There are three kinds of comments: blank lines, empty lines, and a
<number-sign>
(\c
.BR '#' )
and all following characters up to the first unescaped
<newline>
character. Blank lines, empty lines, and lines with
<number-sign>
(\c
.BR '#' )
as the first character on the line are also known as comment lines.
.P
By default, the following files shall be tried in sequence:
.BR ./makefile
and
.BR ./Makefile .
If neither
.BR ./makefile
or
.BR ./Makefile
are found, other implementation-defined files may also be tried.
On XSI-conformant systems, the additional files
.BR ./s.makefile ,
.BR SCCS/s.makefile ,
.BR ./s.Makefile ,
and
.BR SCCS/s.Makefile
shall also be tried.
.P
The
.BR \-f
option shall direct
.IR make
to ignore any of these default files and use the specified argument as
a makefile instead. If the
.BR '\-' 
argument is specified, standard input shall be used.
.P
The term
.IR makefile
is used to refer to any rules provided by the user, whether in
.BR ./makefile
or its variants, or specified by the
.BR \-f
option.
.P
The rules in makefiles shall consist of the following types of lines:
target rules, including special targets (see
.IR "Target Rules"),
inference rules (see
.IR "Inference Rules"),
macro definitions (see
.IR "Macros"),
and comments.
.P
Target and Inference Rules may contain
.IR "command lines" .
Command lines can have a prefix that shall be removed before
execution (see
.IR "Makefile Execution").
.P
When an escaped
<newline>
(one preceded by a
<backslash>)
is found anywhere in the makefile except in a command line, an include
line, or a line immediately preceding an include line, it shall be
replaced, along with any leading white space on the following line,
with a single
<space>.
When an escaped
<newline>
is found in a command line in a makefile, the command line shall
contain the
<backslash>,
the
<newline>,
and the next line, except that the first character of the next line
shall not be included if it is a
<tab>.
When an escaped
<newline>
is found in an include line or in a line immediately preceding an
include line, the behavior is unspecified.
.SS "Include Lines"
.P
If the word
.BR include
appears at the beginning of a line and is followed by one or more
<blank>
characters, the string formed by the remainder of the line shall be
processed as follows to produce a pathname:
.IP " *" 4
The trailing
<newline>,
any
<blank>
characters immediately preceding a comment,
and any comment shall be discarded. If the resulting string contains
any double-quote characters (\c
.BR '\&"' )
the behavior is unspecified.
.IP " *" 4
The resulting string shall be processed for macro expansion (see
.IR "Macros").
.IP " *" 4
Any
<blank>
characters that appear after the first non-\c
<blank>
shall be used as separators to divide the macro-expanded string into
fields. It is unspecified whether any other white-space characters
are also used as separators. It is unspecified whether pathname
expansion (see
.IR "Section 2.13" ", " "Pattern Matching Notation")
is also performed.
.IP " *" 4
If the processing of separators and optional pathname expansion
results in either zero or two or more non-empty fields, the
behavior is unspecified. If it results in one non-empty field,
that field is taken as the pathname.
.P
If the pathname does not begin with a
.BR '/' 
it shall be treated as relative to the current working directory
of the process, not relative to the directory containing the makefile.
If the file does not exist in this location, it is unspecified whether
additional directories are searched.
.P
The contents of the file specified by the pathname shall be read
and processed as if they appeared in the makefile in place of the
include line. If the file ends with an escaped
<newline>
the behavior is unspecified.
.P
The file may itself contain further include lines. Implementations
shall support nesting of include files up to a depth of at least 16.
.SS "Makefile Execution"
.P
Makefile command lines shall be processed one at a time.
.P
Makefile command lines can have one or more of the following prefixes: a
<hyphen-minus>
(\c
.BR '-' ),
an at-sign (\c
.BR '@' ),
or a
<plus-sign>
(\c
.BR '+' ).
These shall modify the way in which
.IR make
processes the command.
.IP "\fR\-\fR" 6
If the command prefix contains a
<hyphen-minus>,
or the
.BR \-i
option is present, or the special target
.BR .IGNORE
has either the current target as a prerequisite or has no prerequisites,
any error found while executing the command shall be ignored.
.IP "\fR@\fR" 6
If the command prefix contains an at-sign and the
.IR make
utility command line
.BR \-n
option is not specified, or the
.BR \-s
option is present, or the special target
.BR .SILENT
has either the current target as a prerequisite or has no prerequisites,
the command shall not be written to standard output before it is executed.
.IP "\fR+\fR" 6
If the command prefix contains a
<plus-sign>,
this indicates a makefile command line that shall be executed even if
.BR \-n ,
.BR \-q ,
or
.BR \-t
is specified.
.P
An
.IR "execution line"
is built from the command line by removing any prefix characters. Except
as described under the at-sign prefix, the execution line shall be
written to the standard output, optionally preceded by a
<tab>.
The execution line shall then be executed by a shell as if it were passed
as the argument to the
\fIsystem\fR()
interface, except that if errors are not being ignored then the shell
.BR \-e
option shall also be in effect. If errors are being ignored for the
command (as a result of the
.BR \-i
option, a
.BR '\-' 
command prefix, or a
.BR .IGNORE
special target), the shell
.BR \-e
option shall not be in effect. The environment for the command being
executed shall contain all of the variables in the environment of
.IR make .
.P
By default, when
.IR make
receives a non-zero status from the execution of a command, it shall
terminate with an error message to standard error.
.SS "Target Rules"
.P
Target rules are formatted as follows:
.sp
.RS 4
.nf
\fItarget \fB[\fItarget\fR...\fB]\fR: \fB[\fIprerequisite\fR...\fB][;\fIcommand\fB]
[\fR<tab>\fIcommand\fR
<tab>\fIcommand\fR
\&...\fB]\fR
.P
\fIline that does not begin with \fR<tab>
.fi
.P
.RE
.P
Target entries are specified by a
<blank>-separated,
non-null list of targets, then a
<colon>,
then a
<blank>-separated,
possibly empty list of prerequisites. Text following a
<semicolon>,
if any, and all following lines that begin with a
<tab>,
are makefile command lines to be executed to update the target. The
first non-empty line that does not begin with a
<tab>
or
.BR '#' 
shall begin a new entry. Any comment line may begin a new entry.
.P
Applications shall select target names from the set of characters
consisting solely of periods, underscores, digits, and alphabetics from
the portable character set (see the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 6.1" ", " "Portable Character Set").
Implementations may allow other characters in target names as
extensions. The interpretation of targets containing the characters
.BR '%' 
and
.BR '\&"' 
is implementation-defined.
.P
A target that has prerequisites, but does not have any commands, can be
used to add to the prerequisite list for that target. Only one target
rule for any given target can contain commands.
.P
Lines that begin with one of the following are called
.IR "special targets"
and control the operation of
.IR make :
.IP "\&\fB.DEFAULT\fR" 10
If the makefile uses this special target, the application shall ensure
that it is specified with commands, but without prerequisites. The
commands shall be used by
.IR make
if there are no other rules available to build a target.
.IP "\&\fB.IGNORE\fR" 10
Prerequisites of this special target are targets themselves; this shall
cause errors from commands associated with them to be ignored in the
same manner as specified by the
.BR \-i
option. Subsequent occurrences of
.BR .IGNORE
shall add to the list of targets ignoring command errors. If no
prerequisites are specified,
.IR make
shall behave as if the
.BR \-i
option had been specified and errors from all commands associated with
all targets shall be ignored.
.IP "\&\fB.POSIX\fR" 10
The application shall ensure that this special target is specified
without prerequisites or commands. If it appears as the first
non-comment line in the makefile,
.IR make
shall process the makefile as specified by this section; otherwise, the
behavior of
.IR make
is unspecified.
.IP "\&\fB.PRECIOUS\fR" 10
Prerequisites of this special target shall not be removed if
.IR make
receives one of the asynchronous events explicitly described in the
ASYNCHRONOUS EVENTS section. Subsequent occurrences of
.BR .PRECIOUS
shall add to the list of precious files. If no prerequisites are
specified, all targets in the makefile shall be treated as if specified
with
.BR .PRECIOUS .
.IP "\fB.SCCS_GET\fR" 10
The application shall ensure that this special target is specified
without prerequisites. If this special target is included in a
makefile, the commands specified with this target shall replace the
default commands associated with this special target (see
.IR "Default Rules").
The commands specified with this target are used to get all SCCS files
that are not found in the current directory.
.RS 10 
.P
When source files are named in a dependency list,
.IR make
shall treat them just like any other target. Because the source file is
presumed to be present in the directory, there is no need to add an
entry for it to the makefile. When a target has no dependencies, but is
present in the directory,
.IR make
shall assume that that file is up-to-date. If, however, an SCCS file
named
.BR SCCS/s. \c
.IR source_file
is found for a target
.IR source_file ,
.IR make
compares the timestamp of the target file with that of the
.BR SCCS/s.source_file
to ensure the target is up-to-date. If the target is missing, or if the
SCCS file is newer,
.IR make
shall automatically issue the commands specified for the
.BR .SCCS_GET
special target to retrieve the most recent version. However, if the
target is writable by anyone,
.IR make
shall not retrieve a new version.
.RE
.IP "\&\fB.SILENT\fR" 10
Prerequisites of this special target are targets themselves; this shall
cause commands associated with them not to be written to the standard
output before they are executed. Subsequent occurrences of
.BR .SILENT
shall add to the list of targets with silent commands. If no
prerequisites are specified,
.IR make
shall behave as if the
.BR \-s
option had been specified and no commands or touch messages associated
with any target shall be written to standard output.
.IP "\&\fB.SUFFIXES\fR" 10
Prerequisites of
.BR .SUFFIXES
shall be appended to the list of known suffixes and are used in
conjunction with the inference rules (see
.IR "Inference Rules").
If
.BR .SUFFIXES
does not have any prerequisites, the list of known suffixes shall be
cleared.
.P
The special targets
.BR .IGNORE ,
.BR .POSIX ,
.BR .PRECIOUS ,
.BR .SILENT ,
and
.BR .SUFFIXES
shall be specified without commands.
.P
Targets with names consisting of a leading
<period>
followed by the uppercase letters
.BR \(dqPOSIX\(dq 
and then any other characters are reserved for future standardization.
Targets with names consisting of a leading
<period>
followed by one or more uppercase letters are reserved for implementation
extensions.
.SS "Macros"
.P
Macro definitions are in the form:
.sp
.RS 4
.nf
\fIstring1\fR = \fB[\fIstring2\fB]\fR
.fi
.P
.RE
.P
The macro named
.IR string1
is defined as having the value of
.IR string2 ,
where
.IR string2
is defined as all characters, if any, after the
<equals-sign>,
up to a comment character (\c
.BR '#' )
or an unescaped
<newline>.
Any
<blank>
characters immediately before or after the
<equals-sign>
shall be ignored.
.P
Applications shall select macro names from the set of characters
consisting solely of periods, underscores, digits, and alphabetics from
the portable character set (see the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 6.1" ", " "Portable Character Set").
A macro name shall not contain an
<equals-sign>.
Implementations may allow other characters in macro names as extensions.
.P
Macros can appear anywhere in the makefile. Macro expansions using
the forms $(\c
.IR string1 )
or ${\c
.IR string1 }
shall be replaced by
.IR string2 ,
as follows:
.IP " *" 4
Macros in target lines shall be evaluated when the target line is read.
.IP " *" 4
Macros in makefile command lines shall be evaluated when the command is
executed.
.IP " *" 4
Macros in the string before the
<equals-sign>
in a macro definition shall be evaluated when the macro assignment
is made.
.IP " *" 4
Macros after the
<equals-sign>
in a macro definition shall not be evaluated until the defined macro
is used in a rule or command, or before the
<equals-sign>
in a macro definition.
.P
The parentheses or braces are optional if
.IR string1
is a single character. The macro $$ shall be replaced by the single
character
.BR '$' .
If
.IR string1
in a macro expansion contains a macro expansion, the results are
unspecified.
.P
Macro expansions using the forms $(\c
.IR string1 \c
.BR [: \c
.IR subst1 \c
.BR =[ \c
.IR subst2 \c
.BR ]] )
or ${\c
.IR string1 \c
.BR [: \c
.IR subst1 \c
.BR =[ \c
.IR subst2 \c
.BR ]] }
can be used to replace all occurrences of
.IR subst1
with
.IR subst2
when the macro substitution is performed. The
.IR subst1
to be replaced shall be recognized when it is a suffix at the end of a
word in
.IR string1
(where a
.IR word ,
in this context, is defined to be a string delimited by the beginning
of the line, a
<blank>,
or a
<newline>).
If
.IR string1
in a macro expansion contains a macro expansion, the results are
unspecified. If a
<percent-sign>
character appears as part of
.IR subst1
or
.IR subst2
after any macros have been recursively expanded, the results are
unspecified.
.P
Macro expansions in
.IR string1
of macro definition lines shall be evaluated when read. Macro
expansions in
.IR string2
of macro definition lines shall be performed when the macro identified
by
.IR string1
is expanded in a rule or command.
.P
Macro definitions shall be taken from the following sources, in the
following logical order, before the makefile(s) are read.
.IP " 1." 4
Macros specified on the
.IR make
utility command line, in the order specified on the command line. It is
unspecified whether the internal macros defined in
.IR "Internal Macros"
are accepted from this source.
.IP " 2." 4
Macros defined by the
.IR MAKEFLAGS
environment variable, in the order specified in the environment
variable. It is unspecified whether the internal macros defined in
.IR "Internal Macros"
are accepted from this source.
.IP " 3." 4
The contents of the environment, excluding the
.IR MAKEFLAGS
and
.IR SHELL
variables and including the variables with null values.
.IP " 4." 4
Macros defined in the inference rules built into
.IR make .
.P
Macro definitions from these sources shall not override macro
definitions from a lower-numbered source. Macro definitions from a
single source (for example, the
.IR make
utility command line, the
.IR MAKEFLAGS
environment variable, or the other environment variables) shall
override previous macro definitions from the same source.
.P
Macros defined in the makefile(s) shall override macro definitions that
occur before them in the makefile(s) and macro definitions from source
4. If the
.BR \-e
option is not specified, macros defined in the makefile(s) shall
override macro definitions from source 3. Macros defined in the
makefile(s) shall not override macro definitions from source 1 or
source 2.
.P
Before the makefile(s) are read, all of the
.IR make
utility command line options (except
.BR \-f
and
.BR \-p )
and
.IR make
utility command line macro definitions (except any for the
.IR MAKEFLAGS
macro), not already included in the
.IR MAKEFLAGS
macro, shall be added to the
.IR MAKEFLAGS
macro, quoted in an implementation-defined manner such that when
.IR MAKEFLAGS
is read by another instance of the
.IR make
command, the original macro's value is recovered. Other
implementation-defined options and macros may also be added to the
.IR MAKEFLAGS
macro. If this modifies the value of the
.IR MAKEFLAGS
macro, or, if the
.IR MAKEFLAGS
macro is modified at any subsequent time, the
.IR MAKEFLAGS
environment variable shall be modified to match the new value of the
.IR MAKEFLAGS
macro. The result of setting
.IR MAKEFLAGS
in the Makefile is unspecified.
.P
Before the makefile(s) are read, all of the
.IR make
utility command line macro definitions (except the
.IR MAKEFLAGS
macro or the
.IR SHELL
macro) shall be added to the environment of
.IR make .
Other implementation-defined variables may also be added to the
environment of
.IR make .
Macros defined by the
.IR MAKEFLAGS
environment variable and macros defined in the makefile(s) shall not
be added to the environment of
.IR make
if they are not already in its environment. With the exception of
.IR SHELL
(see below), it is unspecified whether macros defined in these ways
update the value of an environment variable that already exists in the
environment of
.IR make .
.P
The
.BR SHELL
macro shall be treated specially. It shall be provided by
.IR make
and set to the pathname of the shell command language interpreter (see
.IR "\fIsh\fR\^").
The
.IR SHELL
environment variable shall not affect the value of the
.BR SHELL
macro. If
.BR SHELL
is defined in the makefile or is specified on the command line, it
shall replace the original value of the
.BR SHELL
macro, but shall not affect the
.IR SHELL
environment variable. Other effects of defining
.BR SHELL
in the makefile or on the command line are implementation-defined.
.SS "Inference Rules"
.P
Inference rules are formatted as follows:
.sp
.RS 4
.nf
\fItarget\fR:
<tab>\fIcommand
\fB[\fR<tab>\fIcommand\fB]\fR
\&...
.P
\fIline that does not begin with \fR<tab>\fI or \fR#
.fi
.P
.RE
.P
The application shall ensure that the
.IR target
portion is a valid target name (see
.IR "Target Rules")
of the form
.BR .s2
or
.BR .s1.s2
(where
.BR .s1
and
.BR .s2
are suffixes that have been given as prerequisites of the
.BR .SUFFIXES
special target and
.IR s1
and
.IR s2
do not contain any
<slash>
or
<period>
characters.) If there is only one
<period>
in the target, it is a single-suffix inference rule. Targets with two
periods are double-suffix inference rules. Inference rules can have
only one target before the
<colon>.
.P
The application shall ensure that the makefile does not specify
prerequisites for inference rules; no characters other than white space
shall follow the
<colon>
in the first line, except when creating the
.IR "empty rule,"
described below. Prerequisites are inferred, as described below.
.P
Inference rules can be redefined. A target that matches an existing
inference rule shall overwrite the old inference rule. An empty rule
can be created with a command consisting of simply a
<semicolon>
(that is, the rule still exists and is found during inference rule search,
but since it is empty, execution has no effect). The empty rule can also
be formatted as follows:
.sp
.RS 4
.nf
\fIrule\fR: ;
.fi
.P
.RE
.P
where zero or more
<blank>
characters separate the
<colon>
and
<semicolon>.
.P
The
.IR make
utility uses the suffixes of targets and their prerequisites to infer
how a target can be made up-to-date. A list of inference rules defines
the commands to be executed. By default,
.IR make
contains a built-in set of inference rules. Additional rules can be
specified in the makefile.
.P
The special target
.BR .SUFFIXES
contains as its prerequisites a list of suffixes that shall be used by
the inference rules. The order in which the suffixes are specified
defines the order in which the inference rules for the suffixes are
used. New suffixes shall be appended to the current list by specifying
a
.BR .SUFFIXES
special target in the makefile. A
.BR .SUFFIXES
target with no prerequisites shall clear the list of suffixes. An
empty
.BR .SUFFIXES
target followed by a new
.BR .SUFFIXES
list is required to change the order of the suffixes.
.P
Normally, the user would provide an inference rule for each suffix.
The inference rule to update a target with a suffix
.BR .s1
from a prerequisite with a suffix
.BR .s2
is specified as a target
.BR .s2.s1 .
The internal macros provide the means to specify general inference
rules (see
.IR "Internal Macros").
.P
When no target rule is found to update a target, the inference rules
shall be checked. The suffix of the target (\c
.BR .s1 )
to be built is compared to the list of suffixes specified by the
.BR .SUFFIXES
special targets. If the
.BR .s1
suffix is found in
.BR .SUFFIXES ,
the inference rules shall be searched in the order defined for the
first
.BR .s2.s1
rule whose prerequisite file (\c
.BR $*.s2 )
exists. If the target is out-of-date with respect to this
prerequisite, the commands for that inference rule shall be executed.
.P
If the target to be built does not contain a suffix and there is no
rule for the target, the single suffix inference rules shall be
checked. The single-suffix inference rules define how to build a
target if a file is found with a name that matches the target name with
one of the single suffixes appended. A rule with one suffix
.BR .s2
is the definition of how to build
.IR target
from
.BR target.s2 .
The other suffix (\c
.BR .s1 )
is treated as null.
.P
A
<tilde>
(\c
.BR '\(ti' )
in the above rules refers to an SCCS file in the current directory.
Thus, the rule
.BR .c~.o
would transform an SCCS C-language source file into an object file (\c
.BR .o ).
Because the
.BR s.
of the SCCS files is a prefix, it is incompatible with
.IR make 's
suffix point of view. Hence, the
.BR '\(ti' 
is a way of changing any file reference into an SCCS file reference.
.SS "Libraries"
.P
If a target or prerequisite contains parentheses, it shall be treated
as a member of an archive library. For the
.IR lib (\c
.IR member \c
.BR .o )
expression
.IR lib
refers to the name of the archive library and
.IR member \c
.BR .o
to the member name. The application shall ensure that the member is an
object file with the
.BR .o
suffix. The modification time of the expression is the modification
time for the member as kept in the archive library; see
.IR "\fIar\fR\^".
The
.BR .a
suffix shall refer to an archive library. The
.BR .s2.a
rule shall be used to update a member in the library from a file
with a suffix
.BR .s2 .
.SS "Internal Macros"
.P
The
.IR make
utility shall maintain five internal macros that can be used in target
and inference rules. In order to clearly define the meaning of these
macros, some clarification of the terms
.IR "target rule" ,
.IR "inference rule" ,
.IR target ,
and
.IR prerequisite
is necessary.
.P
Target rules are specified by the user in a makefile for a particular
target. Inference rules are user-specified or
.IR make -specified
rules for a particular class of target name. Explicit prerequisites
are those prerequisites specified in a makefile on target lines.
Implicit prerequisites are those prerequisites that are generated when
inference rules are used. Inference rules are applied to implicit
prerequisites or to explicit prerequisites that do not have target
rules defined for them in the makefile. Target rules are applied to
targets specified in the makefile.
.P
Before any target in the makefile is updated, each of its prerequisites
(both explicit and implicit) shall be updated. This shall be
accomplished by recursively processing each prerequisite. Upon
recursion, each prerequisite shall become a target itself. Its
prerequisites in turn shall be processed recursively until a target is
found that has no prerequisites, or further recursion would
require applying two inference rules one immediately after the other,
at which point the recursion shall stop. As an extension,
implementations may continue recursion when two or more successive
inference rules need to be applied; however, if there are multiple
different chains of such rules that could be used to create the
target, it is unspecified which chain is used. The recursion shall
then back up, updating each target as it goes.
.P
In the definitions that follow, the word
.IR target
refers to one of:
.IP " *" 4
A target specified in the makefile
.IP " *" 4
An explicit prerequisite specified in the makefile that becomes the
target when
.IR make
processes it during recursion
.IP " *" 4
An implicit prerequisite that becomes a target when
.IR make
processes it during recursion
.P
In the definitions that follow, the word
.IR prerequisite
refers to one of the following:
.IP " *" 4
An explicit prerequisite specified in the makefile for a particular
target
.IP " *" 4
An implicit prerequisite generated as a result of locating an
appropriate inference rule and corresponding file that matches the
suffix of the target
.P
The five internal macros are:
.IP $@ 8
The $@ shall evaluate to the full target name of the current target, or
the archive filename part of a library archive target. It shall be
evaluated for both target and inference rules.
.RS 8 
.P
For example, in the
.BR .c.a
inference rule, $@ represents the out-of-date
.BR .a
file to be built. Similarly, in a makefile target rule to build
.BR lib.a
from
.BR file.c ,
$@ represents the out-of-date
.BR lib.a .
.RE
.IP $% 8
The $% macro shall be evaluated only when the current target is an
archive library member of the form
.IR libname (\c
.IR member \c
.BR .o ).
In these cases, $@ shall evaluate to
.IR libname
and $% shall evaluate to
.IR member \c
.BR .o .
The $% macro shall be evaluated for both target and inference rules.
.RS 8 
.P
For example, in a makefile target rule to build
.BR lib.a (\c
.BR file.o ),
$% represents
.BR file.o ,
as opposed to $@, which represents
.BR lib.a .
.RE
.IP $? 8
The $? macro shall evaluate to the list of prerequisites that are
newer than the current target. It shall be evaluated for both target
and inference rules.
.RS 8 
.P
For example, in a makefile target rule to build
.IR prog
from
.BR file1.o ,
.BR file2.o ,
and
.BR file3.o ,
and where
.IR prog
is not out-of-date with respect to
.BR file1.o ,
but is out-of-date with respect to
.BR file2.o
and
.BR file3.o ,
$? represents
.BR file2.o
and
.BR file3.o .
.RE
.IP $< 8
In an inference rule, the $< macro shall evaluate to the filename
whose existence allowed the inference rule to be chosen for the target.
In the
.BR .DEFAULT
rule, the $< macro shall evaluate to the current target name. The
meaning of the $< macro shall be otherwise unspecified.
.RS 8 
.P
For example, in the
.BR .c.a
inference rule, $< represents the prerequisite
.BR .c
file.
.RE
.IP $* 8
The $* macro shall evaluate to the current target name with its suffix
deleted. It shall be evaluated at least for inference rules.
.RS 8 
.P
For example, in the
.BR .c.a
inference rule, $*.o represents the out-of-date
.BR .o
file that corresponds to the prerequisite
.BR .c
file.
.RE
.P
Each of the internal macros has an alternative form. When an uppercase
.BR 'D' 
or
.BR 'F' 
is appended to any of the macros, the meaning shall be changed to the
.IR "directory part"
for
.BR 'D' 
and
.IR "filename part"
for
.BR 'F' .
The directory part is the path prefix of the file without a trailing
<slash>;
for the current directory, the directory part is
.BR '.' .
When the $? macro contains more than one prerequisite filename, the
$(?D) and $(?F) (or ${?D} and ${?F}) macros expand to a list of
directory name parts and filename parts respectively.
.P
For the target
.IR lib (\c
.IR member \c
.BR .o )
and the
.BR s2.a
rule, the internal macros shall be defined as:
.IP $< 8
.IR member \c
.BR .s2
.IP $* 8
.IR member
.IP $@ 8
.IR lib
.IP $? 8
.IR member \c
.BR .s2
.IP $% 8
.IR member \c
.BR .o
.SS "Default Rules"
.P
The default rules for
.IR make
shall achieve results that are the same as if the following were used.
Implementations that do not support the C-Language Development
Utilities option may omit
.BR CC ,
.BR CFLAGS ,
.BR YACC ,
.BR YFLAGS ,
.BR LEX ,
.BR LFLAGS ,
.BR LDFLAGS ,
and the
.BR .c ,
.BR .y ,
and
.BR .l
inference rules. Implementations that do not support FORTRAN may omit
.BR FC ,
.BR FFLAGS ,
and the
.BR .f
inference rules. Implementations may provide additional macros and
rules.
.sp
.RS 4
.nf
\fISPECIAL TARGETS\fP
.P
\&.SCCS_GET: sccs $(SCCSFLAGS) get $(SCCSGETFLAGS) $@
.P
\&.SUFFIXES: .o .c .y .l .a .sh .f .c\(ti .y\(ti .l\(ti .sh\(ti .f\(ti
.P
.IR MACROS
.P
MAKE=make
AR=ar
ARFLAGS=-rv
YACC=yacc
YFLAGS=
LEX=lex
LFLAGS=
LDFLAGS=
CC=c99
CFLAGS=-O 1
FC=fort77
FFLAGS=-O 1
GET=get
GFLAGS=
SCCSFLAGS=
SCCSGETFLAGS=-s
.P
\fISINGLE SUFFIX RULES\fP
.P
\&.c:
    $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $<
.P
\&.f:
    $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $<
.P
\&.sh:
    cp $< $@
    chmod a+x $@
.P
\&.c\(ti:
    $(GET) $(GFLAGS) -p $< > $*.c
    $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $*.c
.P
\&.f\(ti:
    $(GET) $(GFLAGS) -p $< > $*.f
    $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $*.f
.P
\&.sh\(ti:
    $(GET) $(GFLAGS) -p $< > $*.sh
    cp $*.sh $@
    chmod a+x $@
.P
\fIDOUBLE SUFFIX RULES\fP
.P
\&.c.o:
    $(CC) $(CFLAGS) -c $<
.P
\&.f.o:
    $(FC) $(FFLAGS) -c $<
.P
\&.y.o:
    $(YACC) $(YFLAGS) $<
    $(CC) $(CFLAGS) -c y.tab.c
    rm -f y.tab.c
    mv y.tab.o $@
.P
\&.l.o:
    $(LEX) $(LFLAGS) $<
    $(CC) $(CFLAGS) -c lex.yy.c
    rm -f lex.yy.c
    mv lex.yy.o $@
.P
\&.y.c:
    $(YACC) $(YFLAGS) $<
    mv y.tab.c $@
.P
\&.l.c:
    $(LEX) $(LFLAGS) $<
    mv lex.yy.c $@
.P
\&.c\(ti.o:
    $(GET) $(GFLAGS) -p $< > $*.c
    $(CC) $(CFLAGS) -c $*.c
.P
\&.f\(ti.o:
    $(GET) $(GFLAGS) -p $< > $*.f
    $(FC) $(FFLAGS) -c $*.f
.P
\&.y\(ti.o:
    $(GET) $(GFLAGS) -p $< > $*.y
    $(YACC) $(YFLAGS) $*.y
    $(CC) $(CFLAGS) -c y.tab.c
    rm -f y.tab.c
    mv y.tab.o $@
.P
\&.l\(ti.o:
    $(GET) $(GFLAGS) -p $< > $*.l
    $(LEX) $(LFLAGS) $*.l
    $(CC) $(CFLAGS) -c lex.yy.c
    rm -f lex.yy.c
    mv lex.yy.o $@
.P
\&.y\(ti.c:
    $(GET) $(GFLAGS) -p $< > $*.y
    $(YACC) $(YFLAGS) $*.y
    mv y.tab.c $@
.P
\&.l\(ti.c:
    $(GET) $(GFLAGS) -p $< > $*.l
    $(LEX) $(LFLAGS) $*.l
    mv lex.yy.c $@
.P
\&.c.a:
    $(CC) -c $(CFLAGS) $<
    $(AR) $(ARFLAGS) $@ $*.o
    rm -f $*.o
.P
\&.f.a:
    $(FC) -c $(FFLAGS) $<
    $(AR) $(ARFLAGS) $@ $*.o
    rm -f $*.o
.fi
.P
.RE
.SH "EXIT STATUS"
When the
.BR \-q
option is specified, the
.IR make
utility shall exit with one of the following values:
.IP "\00" 6
Successful completion.
.IP "\01" 6
The target was not up-to-date.
.IP >1 6
An error occurred.
.P
When the
.BR \-q
option is not specified, the
.IR make
utility shall exit with one of the following values:
.IP "\00" 6
Successful completion.
.IP >0 6
An error occurred.
.SH "CONSEQUENCES OF ERRORS"
Default.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
If there is a source file (such as
.BR ./source.c )
and there are two SCCS files corresponding to it (\c
.BR ./s.source.c
and
.BR ./SCCS/s.source.c ),
on XSI-conformant systems
.IR make
uses the SCCS file in the current directory. However, users are
advised to use the underlying SCCS utilities (\c
.IR admin ,
.IR delta ,
.IR get ,
and so on) or the
.IR sccs
utility for all source files in a given directory. If both forms are
used for a given source file, future developers are very likely to be
confused.
.P
It is incumbent upon portable makefiles to specify the
.BR .POSIX
special target in order to guarantee that they are not affected by
local extensions.
.P
The
.BR \-k
and
.BR \-S
options are both present so that the relationship between the command
line, the
.IR MAKEFLAGS
variable, and the makefile can be controlled precisely. If the
.BR k
flag is passed in
.IR MAKEFLAGS
and a command is of the form:
.sp
.RS 4
.nf
$(MAKE) -S foo
.fi
.P
.RE
.P
then the default behavior is restored for the child
.IR make .
.P
When the
.BR \-n
option is specified, it is always added to
.IR MAKEFLAGS .
This allows a recursive
.IR make
.BR \-n
.IR target
to be used to see all of the action that would be taken to update
.IR target .
.P
Because of widespread historical practice, interpreting a
<number-sign>
(\c
.BR '#' )
inside a variable as the start of a comment has the unfortunate
side-effect of making it impossible to place a
<number-sign>
in a variable, thus forbidding something like:
.sp
.RS 4
.nf
CFLAGS = "-D COMMENT_CHAR=\(aq#\(aq"
.fi
.P
.RE
.P
Many historical
.IR make
utilities stop chaining together inference rules when an intermediate
target is nonexistent. For example, it might be possible for a
.IR make
to determine that both
.BR .y.c
and
.BR .c.o
could be used to convert a
.BR .y
to a
.BR .o .
Instead, in this case,
.IR make
requires the use of a
.BR .y.o
rule.
.P
The best way to provide portable makefiles is to include all of the
rules needed in the makefile itself. The rules provided use only
features provided by other parts of this volume of POSIX.1\(hy2017. The default rules include
rules for optional commands in this volume of POSIX.1\(hy2017. Only rules pertaining to commands
that are provided are needed in an implementation's default set.
.P
Macros used within other macros are evaluated when the new macro is
used rather than when the new macro is defined. Therefore:
.sp
.RS 4
.nf
MACRO = \fIvalue1\fP
NEW   = $(MACRO)
MACRO = \fIvalue2\fP
.P
target:
    echo $(NEW)
.fi
.P
.RE
.P
would produce
.IR value2
and not
.IR value1
since
.BR NEW
was not expanded until it was needed in the
.IR echo
command line.
.P
Some historical applications have been known to intermix
.IR target_name
and
.IR macro=name
operands on the command line, expecting that all of the macros are
processed before any of the targets are dealt with. Conforming
applications do not do this, although some backwards-compatibility
support may be included in some implementations.
.P
The following characters in filenames may give trouble:
.BR '=' ,
.BR ':' ,
.BR '`' ,
single-quote, and
.BR '@' .
In include filenames, pattern matching characters and
.BR '\&"' 
should also be avoided, as they may be treated as special by some
implementations.
.P
For inference rules, the description of $< and $? seem similar. However,
an example shows the minor difference. In a makefile containing:
.sp
.RS 4
.nf
foo.o: foo.h
.fi
.P
.RE
.P
if
.BR foo.h
is newer than
.BR foo.o ,
yet
.BR foo.c
is older than
.BR foo.o ,
the built-in rule to make
.BR foo.o
from
.BR foo.c
is used, with $< equal to
.BR foo.c
and $? equal to
.BR foo.h .
If
.BR foo.c
is also newer than
.BR foo.o ,
$< is equal to
.BR foo.c
and $? is equal to
.BR "foo.h foo.c" .
.P
As a consequence of the general rules for target updating, a useful
special case is that if a target has no prerequisites and no commands,
and the target of the rule is a nonexistent file, then
.IR make
acts as if this target has been updated whenever its rule is run.
.TP 10
.BR Note:
This implies that all targets depending on this one will always
have their commands run.
.P
.P
Shell command sequences like
.IR "make;\ cp\ original\ copy;\ make"
may have problems on filesystems where the timestamp resolution is the
minimum (1 second) required by the standard and where
.IR make
considers identical timestamps to be up-to-date. Conversely, rules like
.IR "copy:\ original;\ cp\ -p\ original\ copy"
will result in redundant work on
.IR make
implementations that consider identical timestamps to be out-of-date.
.P
This standard does not specify precedence between macro definition and
include directives. Thus, the behavior of:
.sp
.RS 4
.nf
include =foo.mk
.fi
.P
.RE
.P
is unspecified. To define a variable named include, either the white
space before the
<equal-sign>
should be removed, or another macro should be used, as in:
.sp
.RS 4
.nf
INCLUDE_NAME = include
$(INCLUDE_NAME) =foo.mk
.fi
.P
.RE
.P
On the other hand, if the intent is to include a file which starts with an
<equal-sign>,
either the filename should be changed to
.IR "./=foo.mk" ,
or the makefile should be written as:
.sp
.RS 4
.nf
INCLUDE_FILE = =foo.mk
include $(INCLUDE_FILE)
.fi
.P
.RE
.SH EXAMPLES
.IP " 1." 4
The following command:
.RS 4 
.sp
.RS 4
.nf
make
.fi
.P
.RE
.P
makes the first target found in the makefile.
.RE
.IP " 2." 4
The following command:
.RS 4 
.sp
.RS 4
.nf
make junk
.fi
.P
.RE
.P
makes the target
.BR junk .
.RE
.IP " 3." 4
The following makefile says that
.BR pgm
depends on two files,
.BR a.o
and
.BR b.o ,
and that they in turn depend on their corresponding source files (\c
.BR a.c
and
.BR b.c ),
and a common file
.BR incl.h :
.RS 4 
.sp
.RS 4
.nf
\&.POSIX:
pgm: a.o b.o
    c99 a.o b.o -o pgm
a.o: incl.h a.c
    c99 -c a.c
b.o: incl.h b.c
    c99 -c b.c
.fi
.P
.RE
.RE
.IP " 4." 4
An example for making optimized
.BR .o
files from
.BR .c
files is:
.RS 4 
.sp
.RS 4
.nf
\&.c.o:
    c99 -c -O 1 $*.c
.fi
.P
.RE
.P
or:
.sp
.RS 4
.nf
\&.c.o:
    c99 -c -O 1 $<
.fi
.P
.RE
.RE
.IP " 5." 4
The most common use of the archive interface follows. Here, it is
assumed that the source files are all C-language source:
.RS 4 
.sp
.RS 4
.nf
lib: lib(file1.o) lib(file2.o) lib(file3.o)
    @echo lib is now up-to-date
.fi
.P
.RE
.P
The
.BR .c.a
rule is used to make
.BR file1.o ,
.BR file2.o ,
and
.BR file3.o
and insert them into
.BR lib .
.P
The treatment of escaped
<newline>
characters throughout the makefile is historical practice. For example,
the inference rule:
.sp
.RS 4
.nf
\&.c.o\e
:
.fi
.P
.RE
.P
works, and the macro:
.sp
.RS 4
.nf
f=  bar baz\e
    biz
a:
    echo ==$f==
.fi
.P
.RE
.P
echoes
.BR \(dq==bar\ baz\ biz==\(dq .
.P
If $? were:
.sp
.RS 4
.nf
/usr/include/stdio.h /usr/include/unistd.h foo.h
.fi
.P
.RE
.P
then $(?D) would be:
.sp
.RS 4
.nf
/usr/include /usr/include .
.fi
.P
.RE
.P
and $(?F) would be:
.sp
.RS 4
.nf
stdio.h unistd.h foo.h
.fi
.P
.RE
.RE
.IP " 6." 4
The contents of the built-in rules can be viewed by running:
.RS 4 
.sp
.RS 4
.nf
make -p -f /dev/null 2>/dev/null
.fi
.P
.RE
.RE
.SH RATIONALE
The
.IR make
utility described in this volume of POSIX.1\(hy2017 is intended to provide the means for
changing portable source code into executables that can be run on an
POSIX.1\(hy2008-conforming system. It reflects the most common features present
in System V and BSD
.IR make s.
.P
Historically, the
.IR make
utility has been an especially fertile ground for vendor and research
organization-specific syntax modifications and extensions. Examples
include:
.IP " *" 4
Syntax supporting parallel execution (such as from various
multi-processor vendors, GNU, and others)
.IP " *" 4
Additional ``operators'' separating targets and their prerequisites
(System V, BSD, and others)
.IP " *" 4
Specifying that command lines containing the strings
.BR \(dq${MAKE}\(dq 
and
.BR \(dq$(MAKE)\(dq 
are executed when the
.BR \-n
option is specified (GNU and System V)
.IP " *" 4
Modifications of the meaning of internal macros when referencing
libraries (BSD and others)
.IP " *" 4
Using a single instance of the shell for all of the command lines of
the target (BSD and others)
.IP " *" 4
Allowing
<space>
characters as well as
<tab>
characters to delimit command lines (BSD)
.IP " *" 4
Adding C preprocessor-style ``include'' and ``ifdef'' constructs
(System V, GNU, BSD, and others)
.IP " *" 4
Remote execution of command lines (Sprite and others)
.IP " *" 4
Specifying additional special targets (BSD, System V, and most others)
.IP " *" 4
Specifying an alternate shell to use to process commands.
.P
Additionally, many vendors and research organizations have rethought
the basic concepts of
.IR make ,
creating vastly extended, as well as completely new, syntaxes. Each of
these versions of
.IR make
fulfills the needs of a different community of users; it is
unreasonable for this volume of POSIX.1\(hy2017 to require behavior that would be incompatible
(and probably inferior) to historical practice for such a community.
.P
In similar circumstances, when the industry has enough sufficiently
incompatible formats as to make them irreconcilable, this volume of POSIX.1\(hy2017 has followed
one or both of two courses of action. Commands have been renamed (\c
.IR cksum ,
.IR echo ,
and
.IR pax )
and/or command line options have been provided to select the desired
behavior (\c
.IR grep ,
.IR od ,
and
.IR pax ).
.P
Because the syntax specified for the
.IR make
utility is, by and large, a subset of the syntaxes accepted by almost
all versions of
.IR make ,
it was decided that it would be counter-productive to change the name.
And since the makefile itself is a basic unit of portability, it would
not be completely effective to reserve a new option letter, such as
.IR make
.BR \-P ,
to achieve the portable behavior. Therefore, the special target
.BR .POSIX
was added to the makefile, allowing users to specify ``standard''
behavior. This special target does not preclude extensions in the
.IR make
utility, nor does it preclude such extensions being used by the
makefile specifying the target; it does, however, preclude any
extensions from being applied that could alter the behavior of
previously valid syntax; such extensions must be controlled via
command line options or new special targets. It is incumbent upon
portable makefiles to specify the
.BR .POSIX
special target in order to guarantee that they are not affected by
local extensions.
.P
The portable version of
.IR make
described in this reference page is not intended to be the
state-of-the-art software generation tool and, as such, some newer and
more leading-edge features have not been included. An attempt has been
made to describe the portable makefile in a manner that does not
preclude such extensions as long as they do not disturb the portable
behavior described here.
.P
When the
.BR \-n
option is specified, it is always added to
.IR MAKEFLAGS .
This allows a recursive
.IR make
.BR \-n
.IR target
to be used to see all of the action that would be taken to update
.IR target .
.P
The definition of
.IR MAKEFLAGS
allows both the System V letter string and the BSD command line
formats. The two formats are sufficiently different to allow
implementations to support both without ambiguity.
.P
Early proposals stated that an ``unquoted''
<number-sign>
was treated as the start of a comment. The
.IR make
utility does not pay any attention to quotes. A
<number-sign>
starts a comment regardless of its surroundings.
.P
The text about ``other implementation-defined pathnames may also be
tried'' in addition to
.BR ./makefile
and
.BR ./Makefile
is to allow such extensions as
.BR SCCS/s.Makefile
and other variations. It was made an implementation-defined
requirement (as opposed to unspecified behavior) to highlight
surprising implementations that might select something unexpected like
.BR /etc/Makefile .
XSI-conformant systems also try
.BR ./s.makefile ,
.BR SCCS/s.makefile ,
.BR ./s.Makefile ,
and
.BR SCCS/s.Makefile .
.P
Early proposals contained the macro
.BR NPROC
as a means of specifying that
.IR make
should use
.IR n
processes to do the work required. While this feature is a valuable
extension for many systems, it is not common usage and could require
other non-trivial extensions to makefile syntax. This extension is not
required by this volume of POSIX.1\(hy2017, but could be provided as a compatible extension. The
macro
.BR PARALLEL
is used by some historical systems with essentially the same meaning
(but without using a name that is a common system limit value). It is
suggested that implementors recognize the existing use of
.BR NPROC
and/or
.BR PARALLEL
as extensions to
.IR make .
.P
The default rules are based on System V. The default
.BR CC=
value is
.IR c99
instead of
.IR cc
because this volume of POSIX.1\(hy2017 does not standardize the utility named
.IR cc .
Thus, every conforming application would be required to define
.BR CC= \c
.IR c99
to expect to run. There is no advantage conferred by the hope that the
makefile might hit the ``preferred'' compiler because this cannot be
guaranteed to work. Also, since the portable makescript can only use
the
.IR c99
options, no advantage is conferred in terms of what the script can do.
It is a quality-of-implementation issue as to whether
.IR c99
is as valuable as
.IR cc .
.P
The
.BR \-d
option to
.IR make
is frequently used to produce debugging information, but is too
implementation-defined to add to this volume of POSIX.1\(hy2017.
.P
The
.BR \-p
option is not passed in
.IR MAKEFLAGS
on most historical implementations and to change this would cause many
implementations to break without sufficiently increased portability.
.P
Commands that begin with a
<plus-sign>
(\c
.BR '\(pl' )
are executed even if the
.BR \-n
option is present. Based on the GNU version of
.IR make ,
the behavior of
.BR \-n
when the
<plus-sign>
prefix is encountered has been extended to apply to
.BR \-q
and
.BR \-t
as well. However, the System V convention of forcing command execution
with
.BR \-n
when the command line of a target contains either of the strings
.BR \(dq$(MAKE)\(dq 
or
.BR \(dq${MAKE}\(dq 
has not been adopted. This functionality appeared in early proposals,
but the danger of this approach was pointed out with the following
example of a portion of a makefile:
.sp
.RS 4
.nf
subdir:
    cd subdir; rm all_the_files; $(MAKE)
.fi
.P
.RE
.P
The loss of the System V behavior in this case is well-balanced by the
safety afforded to other makefiles that were not aware of this
situation. In any event, the command line
<plus-sign>
prefix can provide the desired functionality.
.P
The double
<colon>
in the target rule format is supported in BSD systems to allow more
than one target line containing the same target name to have commands
associated with it. Since this is not functionality described in the
SVID or XPG3 it has been allowed as an extension, but not mandated.
.P
The default rules are provided with text specifying that the built-in
rules shall be the same as if the listed set were used. The intent is
that implementations should be able to use the rules without change,
but will be allowed to alter them in ways that do not affect the
primary behavior.
.P
One point of discussion was whether to drop the default rules list from
\&this volume of POSIX.1\(hy2017. They provide convenience, but do not enhance portability of
applications. The prime benefit is in portability of users who wish to
type
.IR make
.IR command
and have the command build from a
.BR command.c
file.
.P
The historical
.IR MAKESHELL
feature, and related features provided by other
.IR make
implementations, were omitted. In some implementations it is used
to let a user override the shell to be used to run
.IR make
commands. This was confusing; for a portable
.IR make ,
the shell should be chosen by the makefile writer. Further, a makefile
writer cannot require an alternate shell to be used and still consider
the makefile portable. While it would be possible to standardize a
mechanism for specifying an alternate shell, existing implementations
do not agree on such a mechanism, and makefile writers can already
invoke an alternate shell by specifying the shell name in the rule
for a target; for example:
.sp
.RS 4
.nf
python -c "foo"
.fi
.P
.RE
.P
The
.IR make
utilities in most historical implementations process the prerequisites
of a target in left-to-right order, and the makefile format
requires this. It supports the standard idiom used in many makefiles
that produce
.IR yacc
programs; for example:
.sp
.RS 4
.nf
foo: y.tab.o lex.o main.o
    $(CC) $(CFLAGS) -o $\fR@\fP t.tab.o lex.o main.o
.fi
.P
.RE
.P
In this example, if
.IR make
chose any arbitrary order, the
.BR lex.o
might not be made with the correct
.BR y.tab.h .
Although there may be better ways to express this relationship, it is
widely used historically. Implementations that desire to update
prerequisites in parallel should require an explicit extension to
.IR make
or the makefile format to accomplish it, as described previously.
.P
The algorithm for determining a new entry for target rules is partially
unspecified. Some historical
.IR make s
allow comment lines (including blank and empty lines) within the
collection of commands marked by leading
<tab>
characters. A conforming makefile must ensure that each command starts
with a
<tab>,
but implementations are free to ignore comments without triggering
the start of a new entry.
.P
The ASYNCHRONOUS EVENTS section includes having SIGTERM and SIGHUP,
along with the more traditional SIGINT and SIGQUIT, remove the current
target unless directed not to do so. SIGTERM and SIGHUP were added to
parallel other utilities that have historically cleaned up their work
as a result of these signals. When
.IR make
receives any signal other than SIGQUIT, it is required to resend itself
the signal it received so that it exits with a status that reflects the
signal. The results from SIGQUIT are partially unspecified because, on
systems that create
.BR core
files upon receipt of SIGQUIT, the
.BR core
from
.IR make
would conflict with a
.BR core
file from the command that was running when the SIGQUIT arrived. The
main concern was to prevent damaged files from appearing up-to-date when
.IR make
is rerun.
.P
The
.BR .PRECIOUS
special target was extended to affect all targets globally (by
specifying no prerequisites). The
.BR .IGNORE
and
.BR .SILENT
special targets were extended to allow prerequisites; it was judged to
be more useful in some cases to be able to turn off errors or echoing
for a list of targets than for the entire makefile. These extensions
to
.IR make
in System V were made to match historical practice from the BSD
.IR make .
.P
Macros are not exported to the environment of commands to be run. This
was never the case in any historical
.IR make
and would have serious consequences. The environment is the same as
the environment to
.IR make
except that
.IR MAKEFLAGS
and macros defined on the
.IR make
command line are added, and except that macros defined by the
.IR MAKEFLAGS
environment variable and macros defined in the makefile(s) may update the
value of an existing environment variable (other than
.IR SHELL ).
.P
Some implementations do not use
\fIsystem\fR()
for all command lines, as required by the portable makefile
format; as a performance enhancement, they select lines without shell
metacharacters for direct execution by
\fIexecve\fR().
There is no requirement that
\fIsystem\fR()
be used specifically, but merely that the same results be achieved.
The metacharacters typically used to bypass the direct
\fIexecve\fR()
execution have been any of:
.sp
.RS 4
.nf
=  |  \(ha  (  )  ;  &  <  >  *  ?  [  ]  :  $  `  \(aq  "  \e  \en
.fi
.P
.RE
.P
The default in some advanced versions of
.IR make
is to group all the command lines for a target and execute them using a
single shell invocation; the System V method is to pass each line
individually to a separate shell. The single-shell method has the
advantages in performance and the lack of a requirement for many
continued lines. However, converting to this newer method has caused
portability problems with many historical makefiles, so the behavior
with the POSIX makefile is specified to be the same as that of System
V. It is suggested that the special target
.BR .ONESHELL
be used as an implementation extension to achieve the single-shell
grouping for a target or group of targets.
.P
Novice users of
.IR make
have had difficulty with the historical need to start commands with a
<tab>.
Since it is often difficult to discern differences between
<tab>
and
<space>
characters on terminals or printed listings, confusing bugs can arise. In
early proposals, an attempt was made to correct this problem by allowing
leading
<blank>
characters instead of
<tab>
characters. However, implementors reported many makefiles that failed
in subtle ways following this change, and it is difficult to implement a
.IR make
that unambiguously can differentiate between macro and command lines.
There is extensive historical practice of allowing leading
<space>
characters before macro definitions. Forcing macro lines into column 1
would be a significant backwards-compatibility problem for some makefiles.
Therefore, historical practice was restored.
.P
There is substantial variation in the handling of include lines by
different implementations. However, there is enough commonality for the
standard to be able to specify a minimum set of requirements that allow
the feature to be used portably. Known variations have been explicitly
called out as unspecified behavior in the description.
.P
The System V dynamic dependency feature was not included. It would
support:
.sp
.RS 4
.nf
cat: $$@.c
.fi
.P
.RE
.P
that would expand to;
.sp
.RS 4
.nf
cat: cat.c
.fi
.P
.RE
.P
This feature exists only in the new version of System V
.IR make
and, while useful, is not in wide usage. This means that macros are
expanded twice for prerequisites: once at makefile parse time and once
at target update time.
.P
Consideration was given to adding metarules to the POSIX
.IR make .
This would make
.BR "%.o:\ %.c"
the same as
.BR .c.o: .
This is quite useful and available from some vendors, but it would
cause too many changes to this
.IR make
to support. It would have introduced rule chaining and new substitution
rules. However, the rules for target names have been set to reserve the
.BR '%' 
and
.BR '\&"' 
characters. These are traditionally used to implement metarules and
quoting of target names, respectively. Implementors are strongly
encouraged to use these characters only for these purposes.
.P
A request was made to extend the suffix delimiter character from a
<period>
to any character. The metarules feature in newer
.IR make s
solves this problem in a more general way. This volume of POSIX.1\(hy2017 is staying with the
more conservative historical definition.
.P
The standard output format for the
.BR \-p
option is not described because it is primarily a debugging option and
because the format is not generally useful to programs. In historical
implementations the output is not suitable for use in generating
makefiles. The
.BR \-p
format has been variable across historical implementations. Therefore,
the definition of
.BR \-p
was only to provide a consistently named option for obtaining
.IR make
script debugging information.
.P
Some historical implementations have not cleared the suffix list with
.BR \-r .
.P
Implementations should be aware that some historical applications have
intermixed
.IR target_name
and
.IR macro =\c
.IR value
operands on the command line, expecting that all of the macros are
processed before any of the targets are dealt with. Conforming
applications do not do this, but some backwards-compatibility support
may be warranted.
.P
Empty inference rules are specified with a
<semicolon>
command rather than omitting all commands, as described in an early
proposal. The latter case has no traditional meaning and is reserved
for implementation extensions, such as in GNU
.IR make .
.P
Earlier versions of this standard defined comment lines only as lines with
.BR '#' 
as the first character. Many places then talked about comments, blank
lines, and empty lines; but some places inadvertently only mentioned
comments when blank lines and empty lines had also been accepted in
all known implementations. The standard now defines comment lines to
be blank lines, empty lines, and lines starting with a
.BR '#' 
character and explictily lists cases where blank lines and empty lines
are not acceptable.
.P
On most historic systems, the
.IR make
utility considered a target with a prerequisite that had an identical
timestamp as up-to-date. The HP-UX implementation of
.IR make
treated it as out-of-date. The standard now allows either behavior,
but implementations are encouraged to follow the example set by HP-UX.
This is especially important on file systems where the timestamp
resolution is the minimum (1 second) required by the standard. All
implementations of
.IR make
should make full use of the finest timestamp resolution available on
the file systems holding targets and prerequisites to ensure that
targets are up-to-date even for prerequisite files with timestamps
that were updated within the same second. However, if the timestamp
resolutions of the file systems containing a target and a prerequisite
are different, the timestamp with the more precise resolution should
be rounded down to the resolution of the less precise timestamp for
the comparison.
.SH "FUTURE DIRECTIONS"
Some implementations of
.IR make
include an
.IR export
directive to add specified
.IR make
variables to the environment. This may be considered for
standardization in a future version.
.P
A future version of this standard may require that macro expansions
using the forms $(\c
.IR string1 \c
.BR :[ \c
.IR op \c
.BR ]%[ \c
.IR os \c
.BR ]=[ \c
.IR np \c
.BR ][%][ \c
.IR ns \c
.BR ] )
or ${\c
.IR string1 \c
.BR :[ \c
.IR op \c
.BR ]%[ \c
.IR os \c
.BR ]=[ \c
.IR np \c
.BR ][%][ \c
.IR ns \c
.BR ] }
are treated as pattern macro expansions.
.SH "SEE ALSO"
.IR "Chapter 2" ", " "Shell Command Language",
.IR "\fIar\fR\^",
.IR "\fIc99\fR\^",
.IR "\fIget\fR\^",
.IR "\fIlex\fR\^",
.IR "\fIsccs\fR\^",
.IR "\fIsh\fR\^",
.IR "\fIyacc\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 6.1" ", " "Portable Character Set",
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.P
The System Interfaces volume of POSIX.1\(hy2017,
.IR "\fIexec\fR\^",
.IR "\fIsystem\fR\^(\|)"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .