path: root/man-pages-posix-2003/man1p/make.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "MAKE" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" make 
.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 \- maintain, update, and regenerate groups of programs (\fBDEVELOPMENT\fP)
.SH SYNOPSIS
.LP
\fBmake\fP \fB[\fP\fB-einpqrst\fP\fB][\fP\fB-f\fP \fImakefile\fP\fB]\fP\fB...\fP\fB[\fP
\fB-k| -S\fP\fB][\fP\fImacro\fP\fB=\fP\fIvalue\fP\fB]\fP\fB...
.br
\ \ \ \ \ \ \fP \fB[\fP\fItarget_name\fP\fB...\fP\fB]\fP\fB\fP
.SH DESCRIPTION
.LP
The \fImake\fP 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 \fImake\fP 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 ( \fB'.'\fP ) and no slash ( \fB'/'\fP )
.LP
.IP " 2." 4
\fITarget rules\fP, which can have more than one target name
.LP
.LP
In addition, \fImake\fP shall have a collection of built-in macros
and inference rules that infer prerequisite relationships to
simplify maintenance of programs.
.LP
To receive exactly the behavior described in this section, the user
shall ensure that a portable makefile shall:
.IP " *" 3
Include the special target \fB.POSIX\fP
.LP
.IP " *" 3
Omit any special target reserved for implementations (a leading period
followed by uppercase letters) that has not been
specified by this section
.LP
.LP
The behavior of \fImake\fP is unspecified if either or both of these
conditions are not met.
.SH OPTIONS
.LP
The \fImake\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-e\fP
Cause environment variables, including those with null values, to
override macro assignments within makefiles.
.TP 7
\fB-f\ \fP \fImakefile\fP
Specify a different makefile. The argument \fImakefile\fP is a pathname
of a description file, which is also referred to as
the \fImakefile\fP. A pathname of \fB'-'\fP 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.
.TP 7
\fB-i\fP
Ignore error codes returned by invoked commands. This mode is the
same as if the special target \fB.IGNORE\fP were specified
without prerequisites.
.TP 7
\fB-k\fP
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.
.TP 7
\fB-n\fP
Write commands that would be executed on standard output, but do not
execute them. However, lines with a plus sign (
\fB'+'\fP ) prefix shall be executed. In this mode, lines with an
at sign ( \fB'@'\fP ) character prefix shall be written to
standard output.
.TP 7
\fB-p\fP
Write to standard output the complete set of macro definitions and
target descriptions. The output format is unspecified.
.TP 7
\fB-q\fP
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 ( \fB'+'\fP )
prefix shall be executed.
.TP 7
\fB-r\fP
Clear the suffix list and do not use the built-in rules.
.TP 7
\fB-S\fP
Terminate \fImake\fP if an error occurs while executing the commands
to bring a target up-to-date. This shall be the default
and the opposite of \fB-k\fP.
.TP 7
\fB-s\fP
Do not write makefile command lines or touch messages (see \fB-t\fP)
to standard output before executing. This mode shall be
the same as if the special target \fB.SILENT\fP were specified without
prerequisites.
.TP 7
\fB-t\fP
Update the modification time of each target as though a \fItouch\fP
\fItarget\fP had
been executed. Targets that have prerequisites but no commands (see
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 \fImakefile\fP
command lines associated with each target are not executed.
However, a command line with a plus sign ( \fB'+'\fP ) prefix shall
be executed.
.sp
.LP
Any options specified in the \fIMAKEFLAGS\fP environment variable
shall be evaluated before any options specified on the
\fImake\fP utility command line. If the \fB-k\fP and \fB-S\fP options
are both specified on the \fImake\fP utility command line
or by the \fIMAKEFLAGS\fP environment variable, the last option specified
shall take precedence. If the \fB-f\fP or \fB-p\fP
options appear in the \fIMAKEFLAGS\fP environment variable, the result
is undefined.
.SH OPERANDS
.LP
The following operands shall be supported:
.TP 7
\fItarget_name\fP
Target names, as defined in the EXTENDED DESCRIPTION section. If no
target is specified, while \fImake\fP is processing the
makefiles, the first target that \fImake\fP encounters that is not
a special target or an inference rule shall be used.
.TP 7
\fImacro\fP=\fIvalue\fP
Macro definitions, as defined in Macros .
.sp
.LP
If the \fItarget_name\fP and \fImacro\fP= \fIvalue\fP operands are
intermixed on the \fImake\fP utility command line, the
results are unspecified.
.SH STDIN
.LP
The standard input shall be used only if the \fImakefile\fP option-argument
is \fB'-'\fP . See the INPUT FILES section.
.SH INPUT FILES
.LP
The input file, otherwise known as the makefile, is a text file containing
rules, macro definitions, and comments. See the
EXTENDED DESCRIPTION section.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fImake\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fIMAKEFLAGS\fP
.sp
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
.IP " *" 3
The characters are option letters without the leading hyphens or <blank>
separation used on a \fImake\fP utility command
line.
.LP
.IP " *" 3
The characters are formatted in a manner similar to a portion of the
\fImake\fP utility command line: options are preceded by
hyphens and <blank>-separated as described in the Base Definitions
volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
The \fImacro\fP= \fIvalue\fP macro
definition operands can also be included. The difference between the
contents of \fIMAKEFLAGS\fP and the \fImake\fP utility
command line is that the contents of the variable shall not be subjected
to the word expansions (see \fIWord Expansions\fP ) associated with
parsing the command line values.
.LP
.RE
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fIPROJECTDIR\fP
.sp
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 \fBSCCS\fP in the identified
directory. If the value of \fIPROJECTDIR\fP begins
with a slash, it shall be considered an absolute pathname; otherwise,
the value of \fIPROJECTDIR\fP is treated as a user name and
that user's initial working directory shall be examined for a subdirectory
\fBsrc\fP or \fBsource\fP. If such a directory is
found, it shall be used. Otherwise, the value is used as a relative
pathname. 
.LP
If \fIPROJECTDIR\fP is not set or has a null value, the search for
SCCS files shall be made in the directory \fBSCCS\fP in the
current directory.
.LP
The setting of \fIPROJECTDIR\fP affects all files listed in the remainder
of this utility description for files with a
component named \fBSCCS\fP. 
.sp
.LP
The value of the \fISHELL\fP environment variable shall not be used
as a macro and shall not be modified by defining the
\fBSHELL\fP 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 Macros .
.SH ASYNCHRONOUS EVENTS
.LP
If not already ignored, \fImake\fP 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 \fB.PRECIOUS\fP or unless one of the \fB-n\fP,
\fB-p\fP, or \fB-q\fP 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, \fImake\fP shall take the standard action for
all other signals.
.SH STDOUT
.LP
The \fImake\fP utility shall write all commands to be executed to
standard output unless the \fB-s\fP option was specified,
the command is prefixed with an at sign, or the special target \fB.SILENT\fP
has either the current target as a prerequisite or
has no prerequisites. If \fImake\fP 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 \fB-t\fP option is present
and a file is touched, \fImake\fP shall write to standard
output a message of unspecified format indicating that the file was
touched, including the filename of the file.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
Files can be created when the \fB-t\fP option is present. Additional
files can also be created by the utilities invoked by
\fImake\fP.
.SH EXTENDED DESCRIPTION
.LP
The \fImake\fP utility attempts to perform the actions required to
ensure that the specified targets are up-to-date. A target
is considered out-of-date if it is older than any of its prerequisites
or if it does not exist. The \fImake\fP 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 \fImake\fP utility shall use the modification
times of files to determine whether the corresponding
targets are out-of-date.
.LP
After \fImake\fP has ensured that all of the prerequisites of a target
are up-to-date and if the target is out-of-date, the
commands associated with the target entry shall be executed. If there
are no commands listed for the target, the target shall be
treated as up-to-date.
.SS Makefile Syntax
.LP
A makefile can contain rules, macro definitions (see Macros ), and
comments. There are two kinds
of rules: \fIinference rules\fP and \fItarget rules\fP. The \fImake\fP
utility shall contain a set of built-in inference rules.
If the \fB-r\fP 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 Macros . Comments start with a number
sign ( \fB'#'\fP ) and continue until an unescaped <newline>
is reached.
.LP
By default, the following files shall be tried in sequence: \fB./makefile\fP
and \fB./Makefile\fP. If neither
\fB\&./makefile\fP or \fB./Makefile\fP are found, other implementation-defined
files may also be tried.  On
XSI-conformant systems, the additional files \fB./s.makefile\fP, \fBSCCS/s.makefile\fP,
\fB\&./s.Makefile\fP, and
\fBSCCS/s.Makefile\fP shall also be tried. 
.LP
The \fB-f\fP option shall direct \fImake\fP to ignore any of these
default files and use the specified argument as a makefile
instead. If the \fB'-'\fP argument is specified, standard input shall
be used.
.LP
The term \fImakefile\fP is used to refer to any rules provided by
the user, whether in \fB./makefile\fP or its variants, or
specified by the \fB-f\fP option.
.LP
The rules in makefiles shall consist of the following types of lines:
target rules, including special targets (see Target Rules ), inference
rules (see Inference Rules ), macro definitions
(see Macros ), empty lines, and comments.
.LP
When an escaped <newline> (one preceded by a backslash) is found anywhere
in the makefile except in a command 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>.
.SS Makefile Execution
.LP
Makefile command lines shall be processed one at a time by writing
the makefile command line to the standard output (unless one
of the conditions listed under \fB'@'\fP suppresses the writing) and
executing the command(s) in the line. A <tab> may
precede the command to standard output. Command execution shall be
as if the makefile command line were the argument to the \fIsystem\fP()
function. The environment for the command being executed shall contain
all of
the variables in the environment of \fImake\fP.
.LP
By default, when \fImake\fP receives a non-zero status from the execution
of a command, it shall terminate with an error
message to standard error.
.LP
Makefile command lines can have one or more of the following prefixes:
a hyphen ( \fB'-'\fP ), an at sign ( \fB'@'\fP ),
or a plus sign ( \fB'+'\fP ). These shall modify the way in which
\fImake\fP processes the command. When a command is written
to standard output, the prefix shall not be included in the output.
.TP 7
\fB-\fP
If the command prefix contains a hyphen, or the \fB-i\fP option is
present, or the special target \fB.IGNORE\fP has either
the current target as a prerequisite or has no prerequisites, any
error found while executing the command shall be ignored.
.TP 7
\fB@\fP
If the command prefix contains an at sign and the \fImake\fP utility
command line \fB-n\fP option is not specified, or the
\fB-s\fP option is present, or the special target \fB.SILENT\fP 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.
.TP 7
\fB+\fP
If the command prefix contains a plus sign, this indicates a makefile
command line that shall be executed even if \fB-n\fP,
\fB-q\fP, or \fB-t\fP is specified.
.sp
.SS Target Rules
.LP
Target rules are formatted as follows:
.sp
.RS
.nf

\fItarget\fP \fB[\fP\fItarget\fP\fB...\fP\fB]\fP\fB:\fP \fB[\fP\fIprerequisite\fP\fB...\fP\fB][;\fP\fIcommand\fP\fB]
[\fP\fB<tab>\fP\fIcommand\fP\fB<tab>\fP\fIcommand\fP\fB...\fP\fB]\fP\fB
.br

\fP\fIline that does not begin with\fP \fB<tab>
\fP
.fi
.RE
.LP
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 \fB'#'\fP shall begin a new entry. An empty
or blank line, or a line beginning with \fB'#'\fP,
may begin a new entry.
.LP
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 IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character
Set). Implementations may allow other characters in
target names as extensions. The interpretation of targets containing
the characters \fB'%'\fP and \fB''\fP is
implementation-defined.
.LP
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.
.LP
Lines that begin with one of the following are called \fIspecial targets\fP
and control the operation of \fImake\fP:
.TP 7
\fB\&.DEFAULT\fP
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 \fImake\fP if there are
no other rules available to build a target.
.TP 7
\fB\&.IGNORE\fP
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 \fB-i\fP option. Subsequent
occurrences of \fB.IGNORE\fP shall add to the list of
targets ignoring command errors. If no prerequisites are specified,
\fImake\fP shall behave as if the \fB-i\fP option had been
specified and errors from all commands associated with all targets
shall be ignored.
.TP 7
\fB\&.POSIX\fP
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, \fImake\fP shall process the
makefile as specified by this section; otherwise, the
behavior of \fImake\fP is unspecified.
.TP 7
\fB\&.PRECIOUS\fP
Prerequisites of this special target shall not be removed if \fImake\fP
receives one of the asynchronous events explicitly
described in the ASYNCHRONOUS EVENTS section. Subsequent occurrences
of \fB.PRECIOUS\fP 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 \fB.PRECIOUS\fP.
.TP 7
\fB\&.SCCS_GET\fP
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 Default
Rules ). The commands specified with this target are used to get all
SCCS files that are not
found in the current directory. 
.LP
When source files are named in a dependency list, \fImake\fP 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, \fImake\fP shall assume
that that file is up-to-date. If, however, an SCCS file
named \fBSCCS/s.\fP \fIsource_file\fP is found for a target \fIsource_file\fP,
\fImake\fP compares the timestamp of the target
file with that of the \fBSCCS/s.source_file\fP to ensure the target
is up-to-date. If the target is missing, or if the SCCS file
is newer, \fImake\fP shall automatically issue the commands specified
for the \fB.SCCS_GET\fP special target to retrieve the most
recent version. However, if the target is writable by anyone, \fImake\fP
shall not retrieve a new version. 
.TP 7
\fB\&.SILENT\fP
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 \fB.SILENT\fP shall add to the list of targets with
silent commands. If no prerequisites are specified, \fImake\fP shall
behave as if the \fB-s\fP option had been specified and no
commands or touch messages associated with any target shall be written
to standard output.
.TP 7
\fB\&.SUFFIXES\fP
Prerequisites of \fB.SUFFIXES\fP shall be appended to the list of
known suffixes and are used in conjunction with the
inference rules (see Inference Rules ). If \fB.SUFFIXES\fP does not
have any prerequisites, the
list of known suffixes shall be cleared.
.sp
.LP
The special targets \fB.IGNORE\fP, \fB.POSIX\fP, \fB.PRECIOUS\fP,
\fB\&.SILENT\fP, and \fB.SUFFIXES\fP shall be specified
without commands.
.LP
Targets with names consisting of a leading period followed by the
uppercase letters \fB"POSIX"\fP 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
.LP
Macro definitions are in the form:
.sp
.RS
.nf

\fIstring1\fP \fB=\fP \fB[\fP\fIstring2\fP\fB]\fP
.fi
.RE
.LP
The macro named \fIstring1\fP is defined as having the value of \fIstring2\fP,
where \fIstring2\fP is defined as all
characters, if any, after the equal sign, up to a comment character
( \fB'#'\fP ) or an unescaped <newline>. Any
<blank>s immediately before or after the equal sign shall be ignored.
.LP
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 IEEE\ Std\ 1003.1-2001, 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.
.LP
Macros can appear anywhere in the makefile. Macro expansions using
the forms $( \fIstring1\fP) or ${ \fIstring1\fP} shall be
replaced by \fIstring2\fP, as follows:
.IP " *" 3
Macros in target lines shall be evaluated when the target line is
read.
.LP
.IP " *" 3
Macros in makefile command lines shall be evaluated when the command
is executed.
.LP
.IP " *" 3
Macros in the string before the equals sign in a macro definition
shall be evaluated when the macro assignment is made.
.LP
.IP " *" 3
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.
.LP
.LP
The parentheses or braces are optional if \fIstring1\fP is a single
character. The macro $$ shall be replaced by the single
character \fB'$'\fP . If \fIstring1\fP in a macro expansion contains
a macro expansion, the results are unspecified.
.LP
Macro expansions using the forms $( \fIstring1\fP \fB[:\fP \fIsubst1\fP
\fB=[\fP \fIsubst2\fP \fB]]\fP) or ${
\fIstring1\fP \fB[:\fP \fIsubst1\fP \fB=[\fP \fIsubst2\fP \fB]]\fP}
can be used to replace all occurrences of \fIsubst1\fP
with \fIsubst2\fP when the macro substitution is performed. The \fIsubst1\fP
to be replaced shall be recognized when it is a
suffix at the end of a word in \fIstring1\fP (where a \fIword\fP,
in this context, is defined to be a string delimited by the
beginning of the line, a <blank>, or a <newline>). If \fIstring1\fP
in a macro expansion contains a macro expansion,
the results are unspecified.
.LP
Macro expansions in \fIstring1\fP of macro definition lines shall
be evaluated when read. Macro expansions in \fIstring2\fP of
macro definition lines shall be performed when the macro identified
by \fIstring1\fP is expanded in a rule or command.
.LP
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 \fImake\fP utility command line, in the order
specified on the command line. It is unspecified whether
the internal macros defined in Internal Macros are accepted from this
source.
.LP
.IP " 2." 4
Macros defined by the \fIMAKEFLAGS\fP environment variable, in the
order specified in the environment variable. It is
unspecified whether the internal macros defined in Internal Macros
are accepted from this
source.
.LP
.IP " 3." 4
The contents of the environment, excluding the \fIMAKEFLAGS\fP and
\fISHELL\fP variables and including the variables with null
values.
.LP
.IP " 4." 4
Macros defined in the inference rules built into \fImake\fP.
.LP
.LP
Macro definitions from these sources shall not override macro definitions
from a lower-numbered source. Macro definitions from a
single source (for example, the \fImake\fP utility command line, the
\fIMAKEFLAGS\fP environment variable, or the other
environment variables) shall override previous macro definitions from
the same source.
.LP
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 \fB-e\fP 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.
.LP
Before the makefile(s) are read, all of the \fImake\fP utility command
line options (except \fB-f\fP and \fB-p\fP) and
\fImake\fP utility command line macro definitions (except any for
the \fIMAKEFLAGS\fP macro), not already included in the
\fIMAKEFLAGS\fP macro, shall be added to the \fIMAKEFLAGS\fP macro,
quoted in an implementation-defined manner such that when
\fIMAKEFLAGS\fP is read by another instance of the \fImake\fP command,
the original macro's value is recovered. Other
implementation-defined options and macros may also be added to the
\fIMAKEFLAGS\fP macro. If this modifies the value of the
\fIMAKEFLAGS\fP macro, or, if the \fIMAKEFLAGS\fP macro is modified
at any subsequent time, the \fIMAKEFLAGS\fP environment
variable shall be modified to match the new value of the \fIMAKEFLAGS\fP
macro. The result of setting \fIMAKEFLAGS\fP in the
Makefile is unspecified.
.LP
Before the makefile(s) are read, all of the \fImake\fP utility command
line macro definitions (except the \fIMAKEFLAGS\fP
macro or the \fISHELL\fP macro) shall be added to the environment
of \fImake\fP. Other implementation-defined variables may also
be added to the environment of \fImake\fP.
.LP
The \fBSHELL\fP macro shall be treated specially. It shall be provided
by \fImake\fP and set to the pathname of the shell
command language interpreter (see \fIsh\fP ). The \fISHELL\fP environment
variable shall not affect the
value of the \fBSHELL\fP macro. If \fBSHELL\fP is defined in the makefile
or is specified on the command line, it shall replace
the original value of the \fBSHELL\fP macro, but shall not affect
the \fISHELL\fP environment variable. Other effects of defining
\fBSHELL\fP in the makefile or on the command line are implementation-defined.
.SS Inference Rules
.LP
Inference rules are formatted as follows:
.sp
.RS
.nf

\fItarget\fP\fB:
<tab>\fP\fIcommand
\fP\fB[\fP\fB<tab>\fP\fIcommand\fP\fB]\fP\fB...
.sp

\fP\fIline that does not begin with\fP \fB<tab>\fP \fIor\fP \fB#
\fP
.fi
.RE
.LP
The application shall ensure that the \fItarget\fP portion is a valid
target name (see Target
Rules ) of the form \fB.s2\fP or \fB.s1.s2\fP (where \fB.s1\fP and
\fB\&.s2\fP are suffixes that have been given as
prerequisites of the \fB.SUFFIXES\fP special target and \fIs1\fP and
\fIs2\fP do not contain any slashes or periods.) 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.
.LP
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 \fIempty rule,\fP described below. Prerequisites
are inferred, as described below.
.LP
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
.nf

\fIrule\fP\fB: ;
\fP
.fi
.RE
.LP
where zero or more <blank>s separate the colon and semicolon.
.LP
The \fImake\fP 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,
\fImake\fP contains a built-in set of inference rules.
Additional rules can be specified in the makefile.
.LP
The special target \fB.SUFFIXES\fP 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 \fB.SUFFIXES\fP
special target in the makefile. A \fB.SUFFIXES\fP
target with no prerequisites shall clear the list of suffixes. An
empty \fB.SUFFIXES\fP target followed by a new \fB.SUFFIXES\fP
list is required to change the order of the suffixes.
.LP
Normally, the user would provide an inference rule for each suffix.
The inference rule to update a target with a suffix
\fB\&.s1\fP from a prerequisite with a suffix \fB.s2\fP is specified
as a target \fB.s2.s1\fP. The internal macros provide the
means to specify general inference rules (see Internal Macros ).
.LP
When no target rule is found to update a target, the inference rules
shall be checked. The suffix of the target ( \fB.s1\fP) to
be built is compared to the list of suffixes specified by the \fB.SUFFIXES\fP
special targets. If the \fB.s1\fP suffix is found
in \fB.SUFFIXES\fP, the inference rules shall be searched in the order
defined for the first \fB.s2.s1\fP rule whose prerequisite
file ( \fB$*.s2\fP) exists. If the target is out-of-date with respect
to this prerequisite, the commands for that inference rule
shall be executed.
.LP
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
\fB\&.s2\fP is the definition of how to build \fItarget\fP
from \fBtarget.s2\fP. The other suffix ( \fB.s1\fP) is treated as
null.
.LP
A
tilde ( \fB'~'\fP ) in the above rules refers to an SCCS file in the
current directory. Thus, the rule \fB.c~.o\fP
would transform an SCCS C-language source file into an object file
( \fB.o\fP). Because the \fBs.\fP of the SCCS files is a
prefix, it is incompatible with \fImake\fP's suffix point of view.
Hence, the \fB'~'\fP is a way of changing any file
reference into an SCCS file reference. 
.SS Libraries
.LP
If a target or prerequisite contains parentheses, it shall be treated
as a member of an archive library. For the \fIlib\fP(
\fImember\fP \fB.o\fP) expression \fIlib\fP refers to the name of
the archive library and \fImember\fP \fB.o\fP to the member
name. The application shall ensure that the member is an object file
with the \fB.o\fP suffix. The modification time of the
expression is the modification time for the member as kept in the
archive library; see \fIar\fP . The
\fB\&.a\fP suffix shall refer to an archive library. The \fB.s2.a\fP
rule shall be used to update a member in the library from a
file with a suffix \fB.s2\fP.
.SS Internal Macros
.LP
The \fImake\fP 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
\fItarget rule\fP, \fIinference rule\fP, \fItarget\fP, and
\fIprerequisite\fP is necessary.
.LP
Target rules are specified by the user in a makefile for a particular
target. Inference rules are user-specified or
\fImake\fP-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.
.LP
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, at which point the
recursion stops. The recursion shall then back up, updating each target
as it goes.
.LP
In the definitions that follow, the word \fItarget\fP refers to one
of:
.IP " *" 3
A target specified in the makefile
.LP
.IP " *" 3
An explicit prerequisite specified in the makefile that becomes the
target when \fImake\fP processes it during recursion
.LP
.IP " *" 3
An implicit prerequisite that becomes a target when \fImake\fP processes
it during recursion
.LP
.LP
In the definitions that follow, the word \fIprerequisite\fP refers
to one of the following:
.IP " *" 3
An explicit prerequisite specified in the makefile for a particular
target
.LP
.IP " *" 3
An implicit prerequisite generated as a result of locating an appropriate
inference rule and corresponding file that matches the
suffix of the target
.LP
.LP
The five internal macros are:
.TP 7
$@
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. 
.LP
For example, in the \fB.c.a\fP inference rule, $@ represents the out-of-date
\fB\&.a\fP file to be built. Similarly, in a
makefile target rule to build \fBlib.a\fP from \fBfile.c\fP, $@ represents
the out-of-date \fBlib.a\fP.
.TP 7
$%
The $% macro shall be evaluated only when the current target is an
archive library member of the form \fIlibname\fP(
\fImember\fP \fB.o\fP). In these cases, $@ shall evaluate to \fIlibname\fP
and $% shall evaluate to \fImember\fP \fB.o\fP. The
$% macro shall be evaluated for both target and inference rules. 
.LP
For example, in a makefile target rule to build \fBlib.a\fP( \fBfile.o\fP),
$% represents \fBfile.o\fP, as opposed to $@,
which represents \fBlib.a\fP.
.TP 7
$?
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. 
.LP
For example, in a makefile target rule to build \fIprog\fP from \fBfile1.o\fP,
\fBfile2.o\fP, and \fBfile3.o\fP, and where
\fIprog\fP is not out-of-date with respect to \fBfile1.o\fP, but is
out-of-date with respect to \fBfile2.o\fP and
\fBfile3.o\fP, $? represents \fBfile2.o\fP and \fBfile3.o\fP.
.TP 7
$<
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 \fB.DEFAULT\fP rule, the $< macro shall evaluate
to the current target name. The meaning of the $<
macro shall be otherwise unspecified. 
.LP
For example, in the \fB.c.a\fP inference rule, $< represents the prerequisite
\fB\&.c\fP file.
.TP 7
$*
The $* macro shall evaluate to the current target name with its suffix
deleted. It shall be evaluated at least for inference
rules. 
.LP
For example, in the \fB.c.a\fP inference rule, $*.o represents the
out-of-date \fB.o\fP file that corresponds to the
prerequisite \fB.c\fP file.
.sp
.LP
Each of the internal macros has an alternative form. When an uppercase
\fB'D'\fP or \fB'F'\fP is appended to any of the
macros, the meaning shall be changed to the \fIdirectory part\fP for
\fB'D'\fP and \fIfilename part\fP for \fB'F'\fP . The
directory part is the path prefix of the file without a trailing slash;
for the current directory, the directory part is
\fB'.'\fP . 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.
.LP
For the target \fIlib\fP( \fImember\fP \fB.o\fP) and the \fBs2.a\fP
rule, the internal macros shall be defined as:
.TP 7
$<
\fImember\fP \fB.s2\fP
.TP 7
$*
\fImember\fP
.TP 7
$@
\fIlib\fP
.TP 7
$?
\fImember\fP \fB.s2\fP
.TP 7
$%
\fImember\fP \fB.o\fP
.sp
.SS Default Rules
.LP
The default rules for \fImake\fP 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 \fBCC\fP,
\fBCFLAGS\fP, \fBYACC\fP, \fBYFLAGS\fP, \fBLEX\fP,
\fBLFLAGS\fP, \fBLDFLAGS\fP, and the \fB.c\fP, \fB.y\fP, and \fB.l\fP
inference rules. Implementations that do not support
FORTRAN may omit \fBFC\fP, \fBFFLAGS\fP, and the \fB.f\fP inference
rules. Implementations may provide additional macros and
rules.
.sp
.RS
.nf

\fISPECIAL TARGETS\fP\fB
.br


\&.SCCS_GET: sccs $(SCCSFLAGS) get $(SCCSGETFLAGS) $@

.sp


\&.SUFFIXES: .o .c .y .l .a .sh .f .c~ .y~ .l~ .sh~ .f~
.sp

\fP\fIMACROS\fP\fB
.br

MAKE=make
AR=ar
ARFLAGS=-rv
YACC=yacc
YFLAGS=
LEX=lex
LFLAGS=
LDFLAGS=
CC=c99
CFLAGS=-O
FC=fort77
FFLAGS=-O 1

GET=get
GFLAGS=
SCCSFLAGS=
SCCSGETFLAGS=-s

.sp

\fP\fISINGLE SUFFIX RULES\fP\fB
.br

\&.c:
    $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $<
.sp

\&.f:
    $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $<
.sp

\&.sh:
    cp $< $@
    chmod a+x $@
.sp


\&.c~:
    $(GET) $(GFLAGS) -p $< > $*.c
    $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $*.c
.sp

\&.f~:
    $(GET) $(GFLAGS) -p $< > $*.f
    $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $*.f
.sp

\&.sh~:
    $(GET) $(GFLAGS) -p $< > $*.sh
    cp $*.sh $@
    chmod a+x $@

.sp

\fP\fIDOUBLE SUFFIX RULES\fP\fB
.br

\&.c.o:
    $(CC) $(CFLAGS) -c $<
.sp

\&.f.o:
    $(FC) $(FFLAGS) -c $<
.sp

\&.y.o:
    $(YACC) $(YFLAGS) $<
    $(CC) $(CFLAGS) -c y.tab.c
    rm -f y.tab.c
    mv y.tab.o $@
.sp

\&.l.o:
    $(LEX) $(LFLAGS) $<
    $(CC) $(CFLAGS) -c lex.yy.c
    rm -f lex.yy.c
    mv lex.yy.o $@
.sp

\&.y.c:
    $(YACC) $(YFLAGS) $<
    mv y.tab.c $@
.sp

\&.l.c:
    $(LEX) $(LFLAGS) $<
    mv lex.yy.c $@
.sp


\&.c~.o:
    $(GET) $(GFLAGS) -p $< > $*.c
    $(CC) $(CFLAGS) -c $*.c
.sp

\&.f~.o:
    $(GET) $(GFLAGS) -p $< > $*.f
    $(FC) $(FFLAGS) -c $*.f
.sp

\&.y~.o:
    $(GET) $(GFLAGS) -p $< > $*.y
    $(YACC) $(YFLAGS) $*.y
    $(CC) $(CFLAGS) -c y.tab.c
    rm -f y.tab.c
    mv y.tab.o $@
.sp

\&.l~.o:
    $(GET) $(GFLAGS) -p $< > $*.l
    $(LEX) $(LFLAGS) $*.l
    $(CC) $(CFLAGS) -c lex.yy.c
    rm -f lex.yy.c
    mv lex.yy.o $@
.sp

\&.y~.c:
    $(GET) $(GFLAGS) -p $< > $*.y
    $(YACC) $(YFLAGS) $*.y
    mv y.tab.c $@
.sp

\&.l~.c:
    $(GET) $(GFLAGS) -p $< > $*.l
    $(LEX) $(LFLAGS) $*.l
    mv lex.yy.c $@

.sp

\&.c.a:
    $(CC) -c $(CFLAGS) $<
    $(AR) $(ARFLAGS) $@ $*.o
    rm -f $*.o
.sp

\&.f.a:
    $(FC) -c $(FFLAGS) $<
    $(AR) $(ARFLAGS) $@ $*.o
    rm -f $*.o
\fP
.fi
.RE
.SH EXIT STATUS
.LP
When the \fB-q\fP option is specified, the \fImake\fP utility shall
exit with one of the following values:
.TP 7
\ 0
Successful completion.
.TP 7
\ 1
The target was not up-to-date.
.TP 7
>1
An error occurred.
.sp
.LP
When the \fB-q\fP option is not specified, the \fImake\fP utility
shall exit with one of the following values:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
If there is a source file (such as \fB./source.c\fP) and there are
two SCCS files corresponding to it ( \fB./s.source.c\fP and
\fB\&./SCCS/s.source.c\fP), on XSI-conformant systems \fImake\fP uses
the SCCS file in the current directory. However, users are
advised to use the underlying SCCS utilities ( \fIadmin\fP, \fIdelta\fP,
\fIget\fP, and so on) or the \fIsccs\fP 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.
.LP
It is incumbent upon portable makefiles to specify the \fB.POSIX\fP
special target in order to guarantee that they are not
affected by local extensions.
.LP
The \fB-k\fP and \fB-S\fP options are both present so that the relationship
between the command line, the \fIMAKEFLAGS\fP
variable, and the makefile can be controlled precisely. If the \fBk\fP
flag is passed in \fIMAKEFLAGS\fP and a command is of the
form:
.sp
.RS
.nf

\fB$(MAKE) -S foo
\fP
.fi
.RE
.LP
then the default behavior is restored for the child \fImake\fP.
.LP
When the \fB-n\fP option is specified, it is always added to \fIMAKEFLAGS
\&.\fP This allows a recursive \fImake\fP \fB-n\fP
\fItarget\fP to be used to see all of the action that would be taken
to update \fItarget\fP.
.LP
Because of widespread historical practice, interpreting a \fB'#'\fP
number sign 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
.nf

\fBCFLAGS = "-D COMMENT_CHAR='#'"
\fP
.fi
.RE
.LP
Many historical \fImake\fP utilities stop chaining together inference
rules when an intermediate target is nonexistent. For
example, it might be possible for a \fImake\fP to determine that both
\fB\&.y.c\fP and \fB.c.o\fP could be used to convert a
\fB\&.y\fP to a \fB.o\fP. Instead, in this case, \fImake\fP requires
the use of a \fB.y.o\fP rule.
.LP
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 IEEE\ Std\ 1003.1-2001.
The default rules include rules for
optional commands in this volume of IEEE\ Std\ 1003.1-2001. Only rules
pertaining to commands that are provided are needed
in an implementation's default set.
.LP
Macros used within other macros are evaluated when the new macro is
used rather than when the new macro is defined.
Therefore:
.sp
.RS
.nf

\fBMACRO =\fP \fIvalue1\fP\fBNEW   = $(MACRO)
MACRO =\fP \fIvalue2\fP\fB
.br

target:
    echo $(NEW)
\fP
.fi
.RE
.LP
would produce \fIvalue2\fP and not \fIvalue1\fP since \fBNEW\fP was
not expanded until it was needed in the \fIecho\fP command line.
.LP
Some historical applications have been known to intermix \fItarget_name\fP
and \fImacro=name\fP 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.
.LP
The following characters in filenames may give trouble: \fB'='\fP,
\fB':'\fP, \fB'`'\fP, \fB'"\fP, and
\fB'@'\fP . For inference rules, the description of $< and $? seem
similar. However, an example shows the minor difference.
In a makefile containing:
.sp
.RS
.nf

\fBfoo.o: foo.h
\fP
.fi
.RE
.LP
if \fBfoo.h\fP is newer than \fBfoo.o\fP, yet \fBfoo.c\fP is older
than \fBfoo.o\fP, the built-in rule to make \fBfoo.o\fP
from \fBfoo.c\fP is used, with $< equal to \fBfoo.c\fP and $? equal
to \fBfoo.h\fP. If \fBfoo.c\fP is also newer than
\fBfoo.o\fP, $< is equal to \fBfoo.c\fP and $? is equal to \fBfoo.h
foo.c\fP.
.SH EXAMPLES
.IP " 1." 4
The following command:
.sp
.RS
.nf

\fBmake
\fP
.fi
.RE
.LP
makes the first target found in the makefile.
.LP
.IP " 2." 4
The following command:
.sp
.RS
.nf

\fBmake junk
\fP
.fi
.RE
.LP
makes the target \fBjunk\fP.
.LP
.IP " 3." 4
The following makefile says that \fBpgm\fP depends on two files, \fBa.o\fP
and \fBb.o\fP, and that they in turn depend on
their corresponding source files ( \fBa.c\fP and \fBb.c\fP), and a
common file \fBincl.h\fP:
.sp
.RS
.nf

\fBpgm: 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
\fP
.fi
.RE
.LP
.IP " 4." 4
An example for making optimized \fB.o\fP files from \fB.c\fP files
is:
.sp
.RS
.nf

\fB\&.c.o:
    c99 -c -O $*.c
\fP
.fi
.RE
.LP
or:
.sp
.RS
.nf

\fB\&.c.o:
    c99 -c -O $<
\fP
.fi
.RE
.LP
.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:
.sp
.RS
.nf

\fBlib: lib(file1.o) lib(file2.o) lib(file3.o)
    @echo lib is now up-to-date
\fP
.fi
.RE
.LP
The \fB.c.a\fP rule is used to make \fBfile1.o\fP, \fBfile2.o\fP,
and \fBfile3.o\fP and insert them into \fBlib\fP.
.LP
The treatment of escaped <newline>s throughout the makefile is historical
practice. For example, the inference rule:
.sp
.RS
.nf

\fB\&.c.o\\
:
\fP
.fi
.RE
.LP
works, and the macro:
.sp
.RS
.nf

\fBf=  bar baz\\
    biz
a:
    echo ==$f==
\fP
.fi
.RE
.LP
echoes \fB"==bar\ baz\ biz=="\fP .
.LP
If $? were:
.sp
.RS
.nf

\fB/usr/include/stdio.h /usr/include/unistd.h foo.h
\fP
.fi
.RE
.LP
then $(?D) would be:
.sp
.RS
.nf

\fB/usr/include /usr/include .
\fP
.fi
.RE
.LP
and $(?F) would be:
.sp
.RS
.nf

\fBstdio.h unistd.h foo.h
\fP
.fi
.RE
.LP
.IP " 6." 4
The contents of the built-in rules can be viewed by running:
.sp
.RS
.nf

\fBmake -p -f /dev/null 2>/dev/null
\fP
.fi
.RE
.LP
.SH RATIONALE
.LP
The \fImake\fP utility described in this volume of IEEE\ Std\ 1003.1-2001
is intended to provide the means for changing
portable source code into executables that can be run on an IEEE\ Std\ 1003.1-2001-conforming
system. It reflects the most
common features present in System V and BSD \fImake\fPs.
.LP
Historically, the \fImake\fP utility has been an especially fertile
ground for vendor and research organization-specific syntax
modifications and extensions. Examples include:
.IP " *" 3
Syntax supporting parallel execution (such as from various multi-processor
vendors, GNU, and others)
.LP
.IP " *" 3
Additional "operators" separating targets and their prerequisites
(System V, BSD, and others)
.LP
.IP " *" 3
Specifying that command lines containing the strings \fB"${MAKE}"\fP
and \fB"$(MAKE)"\fP are executed when the \fB-n\fP
option is specified (GNU and System V)
.LP
.IP " *" 3
Modifications of the meaning of internal macros when referencing libraries
(BSD and others)
.LP
.IP " *" 3
Using a single instance of the shell for all of the command lines
of the target (BSD and others)
.LP
.IP " *" 3
Allowing spaces as well as tabs to delimit command lines (BSD)
.LP
.IP " *" 3
Adding C preprocessor-style "include" and "ifdef" constructs (System
V, GNU, BSD, and others)
.LP
.IP " *" 3
Remote execution of command lines (Sprite and others)
.LP
.IP " *" 3
Specifying additional special targets (BSD, System V, and most others)
.LP
.LP
Additionally, many vendors and research organizations have rethought
the basic concepts of \fImake\fP, creating vastly
extended, as well as completely new, syntaxes. Each of these versions
of \fImake\fP fulfills the needs of a different community of
users; it is unreasonable for this volume of IEEE\ Std\ 1003.1-2001
to require behavior that would be incompatible (and
probably inferior) to historical practice for such a community.
.LP
In similar circumstances, when the industry has enough sufficiently
incompatible formats as to make them irreconcilable, this
volume of IEEE\ Std\ 1003.1-2001 has followed one or both of two courses
of action. Commands have been renamed ( \fIcksum\fP, \fIecho\fP, and
\fIpax\fP) and/or command line options have been provided to select
the desired behavior ( \fIgrep\fP, \fIod\fP, and \fIpax\fP).
.LP
Because the syntax specified for the \fImake\fP utility is, by and
large, a subset of the syntaxes accepted by almost all
versions of \fImake\fP, 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 \fImake\fP \fB-P\fP, to
achieve the portable behavior. Therefore, the special target \fB.POSIX\fP
was added to the makefile, allowing users to specify
"standard" behavior. This special target does not preclude extensions
in the \fImake\fP 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 \fB.POSIX\fP
special target in order to guarantee that they are
not affected by local extensions.
.LP
The portable version of \fImake\fP 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.
.LP
When the \fB-n\fP option is specified, it is always added to \fIMAKEFLAGS
\&.\fP This allows a recursive \fImake\fP \fB-n\fP
\fItarget\fP to be used to see all of the action that would be taken
to update \fItarget\fP.
.LP
The definition of \fIMAKEFLAGS\fP 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.
.LP
Early proposals stated that an "unquoted" number sign was treated
as the start of a comment. The \fImake\fP utility does not
pay any attention to quotes. A number sign starts a comment regardless
of its surroundings.
.LP
The text about "other implementation-defined pathnames may also be
tried" in addition to \fB./makefile\fP and
\fB\&./Makefile\fP is to allow such extensions as \fBSCCS/s.Makefile\fP
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 \fB/etc/Makefile\fP. XSI-conformant systems also try \fB./s.makefile\fP,
\fBSCCS/s.makefile\fP, \fB./s.Makefile\fP, and
\fBSCCS/s.Makefile\fP.
.LP
Early proposals contained the macro \fBNPROC\fP as a means of specifying
that \fImake\fP should use \fIn\fP 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 IEEE\ Std\ 1003.1-2001, but
could be provided as a compatible extension. The macro \fBPARALLEL\fP
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 \fBNPROC\fP and/or \fBPARALLEL\fP as extensions to \fImake\fP.
.LP
The default rules are based on System V. The default \fBCC=\fP value
is \fIc99\fP instead
of \fIcc\fP because this volume of IEEE\ Std\ 1003.1-2001 does not
standardize the utility named \fIcc\fP. Thus, every
conforming application would be required to define \fBCC=\fP \fIc99\fP
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 \fIc99\fP options, no
advantage is conferred in terms of what the script can do. It is a
quality-of-implementation issue as to whether \fIc99\fP is as valuable
as \fIcc\fP.
.LP
The \fB-d\fP option to \fImake\fP is frequently used to produce debugging
information, but is too implementation-defined to
add to this volume of IEEE\ Std\ 1003.1-2001.
.LP
The \fB-p\fP option is not passed in \fIMAKEFLAGS\fP on most historical
implementations and to change this would cause many
implementations to break without sufficiently increased portability.
.LP
Commands that begin with a plus sign ( \fB'+'\fP ) are executed even
if the \fB-n\fP option is present. Based on the GNU
version of \fImake\fP, the behavior of \fB-n\fP when the plus-sign
prefix is encountered has been extended to apply to \fB-q\fP
and \fB-t\fP as well. However, the System V convention of forcing
command execution with \fB-n\fP when the command line of a
target contains either of the strings \fB"$(MAKE)"\fP or \fB"${MAKE}"\fP
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
.nf

\fBsubdir:
    cd subdir; rm all_the_files; $(MAKE)
\fP
.fi
.RE
.LP
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.
.LP
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.
.LP
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.
.LP
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 portions of this volume of IEEE\ Std\ 1003.1-2001.
The default rules include rules for
optional commands in this volume of IEEE\ Std\ 1003.1-2001. Only rules
pertaining to commands that are provided are needed
in the default set of an implementation.
.LP
One point of discussion was whether to drop the default rules list
from this volume of IEEE\ Std\ 1003.1-2001. They
provide convenience, but do not enhance portability of applications.
The prime benefit is in portability of users who wish to type
\fImake\fP \fIcommand\fP and have the command build from a \fBcommand.c\fP
file.
.LP
The historical \fIMAKESHELL\fP feature was omitted. In some implementations
it is used to let a user override the shell to be
used to run \fImake\fP commands. This was confusing; for a portable
\fImake\fP, the shell should be chosen by the makefile writer
or specified on the \fImake\fP command line and not by a user running
\fImake\fP.
.LP
The \fImake\fP 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 \fIyacc\fP programs; for example:
.sp
.RS
.nf

\fBfoo: y.tab.o lex.o main.o
    $(CC) $(CFLAGS) -o $\fP@ \fBt.tab.o lex.o main.o
\fP
.fi
.RE
.LP
In this example, if \fImake\fP chose any arbitrary order, the \fBlex.o\fP
might not be made with the correct \fBy.tab.h\fP.
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 \fImake\fP or the makefile format to accomplish it, as
described previously.
.LP
The algorithm for determining a new entry for target rules is partially
unspecified. Some historical \fImake\fPs allow blank,
empty, or comment lines within the collection of commands marked by
leading <tab>s. A conforming makefile must ensure that
each command starts with a <tab>, but implementations are free to
ignore blank, empty, and comment lines without triggering
the start of a new entry.
.LP
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 \fImake\fP
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 \fBcore\fP files
upon receipt of SIGQUIT, the \fBcore\fP from \fImake\fP
would conflict with a \fBcore\fP 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 \fImake\fP is rerun.
.LP
The \fB.PRECIOUS\fP special target was extended to affect all targets
globally (by specifying no prerequisites). The
\fB\&.IGNORE\fP and \fB.SILENT\fP 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 \fImake\fP
in System V were made to match historical practice from the BSD \fImake\fP.
.LP
Macros are not exported to the environment of commands to be run.
This was never the case in any historical \fImake\fP and
would have serious consequences. The environment is the same as the
environment to \fImake\fP except that \fIMAKEFLAGS\fP and
macros defined on the \fImake\fP command line are added.
.LP
Some implementations do not use \fIsystem\fP() 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\fP().
There is no requirement that \fIsystem\fP() be used specifically,
but merely that the same results be achieved. The
metacharacters typically used to bypass the direct \fIexecve\fP()
execution have been any
of:
.sp
.RS
.nf

\fB=  |  ^  (  )  ;  &  <  >  *  ?  [  ]  :  $  `  '  "  \\  \\n
\fP
.fi
.RE
.LP
The default in some advanced versions of \fImake\fP 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 \fB.ONESHELL\fP
be used as an implementation extension to achieve the
single-shell grouping for a target or group of targets.
.LP
Novice users of \fImake\fP have had difficulty with the historical
need to start commands with a <tab>. Since it is often
difficult to discern differences between <tab>s and <space>s on terminals
or printed listings, confusing bugs can
arise. In early proposals, an attempt was made to correct this problem
by allowing leading <blank>s instead of <tab>s.
However, implementors reported many makefiles that failed in subtle
ways following this change, and it is difficult to implement a
\fImake\fP that unambiguously can differentiate between macro and
command lines. There is extensive historical practice of
allowing leading spaces before macro definitions. Forcing macro lines
into column 1 would be a significant backwards-compatibility
problem for some makefiles. Therefore, historical practice was restored.
.LP
The System V INCLUDE feature was considered, but not included. This
would treat a line that began in the first column and
contained INCLUDE <\fIfilename\fP> as an indication to read <\fIfilename\fP>
at that point in the makefile. This is
difficult to use in a portable way, and it raises concerns about nesting
levels and diagnostics. System V, BSD, GNU, and others
have used different methods for including files.
.LP
The System V dynamic dependency feature was not included. It would
support:
.sp
.RS
.nf

\fBcat: $$@.c
\fP
.fi
.RE
.LP
that would expand to;
.sp
.RS
.nf

\fBcat: cat.c
\fP
.fi
.RE
.LP
This feature exists only in the new version of System V \fImake\fP
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.
.LP
Consideration was given to adding metarules to the POSIX \fImake\fP.
This would make \fB%.o:\ %.c\fP the same as
\fB\&.c.o:\fP. This is quite useful and available from some vendors,
but it would cause too many changes to this \fImake\fP to
support. It would have introduced rule chaining and new substitution
rules. However, the rules for target names have been set to
reserve the \fB'%'\fP and \fB''\fP 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.
.LP
A request was made to extend the suffix delimiter character from a
period to any character. The metarules feature in newer
\fImake\fPs solves this problem in a more general way. This volume
of IEEE\ Std\ 1003.1-2001 is staying with the more
conservative historical definition.
.LP
The standard output format for the \fB-p\fP 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 \fB-p\fP format has been variable across historical
implementations. Therefore, the definition of \fB-p\fP was
only to provide a consistently named option for obtaining \fImake\fP
script debugging information.
.LP
Some historical implementations have not cleared the suffix list with
\fB-r\fP.
.LP
Implementations should be aware that some historical applications
have intermixed \fItarget_name\fP and \fImacro\fP=
\fIvalue\fP 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.
.LP
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 \fImake\fP.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIShell Command Language\fP, \fIar\fP, \fIc99\fP, \fIget\fP,
\fIlex\fP, \fIsccs\fP, \fIsh\fP, \fIyacc\fP, the System Interfaces
volume
of IEEE\ Std\ 1003.1-2001, \fIexec\fP, \fIsystem\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .