make.html

IEEE 1003.1-2003, Single Unix Specification v3

<li>
<p>An example for making optimized <b>.o</b> files from <b>.c</b> files is:</p>

<pre>
<tt>.c.o:
    c99 -c -O $*.c
</tt>
</pre>

<p>or:</p>

<pre>
<tt>.c.o:
    c99 -c -O $&lt;
</tt>
</pre>
</li>

<li>
<p>The most common use of the archive interface follows. Here, it is assumed that the source files are all C-language source:</p>

<pre>
<tt>lib: lib(file1.o) lib(file2.o) lib(file3.o)
    @echo lib is now up-to-date
</tt>
</pre>

<p>The <b>.c.a</b> rule is used to make <b>file1.o</b>, <b>file2.o</b>, and <b>file3.o</b> and insert them into <b>lib</b>.</p>

<p>The treatment of escaped &lt;newline&gt;s throughout the makefile is historical practice. For example, the inference rule:</p>

<pre>
<tt>.c.o\
:
</tt>
</pre>

<p>works, and the macro:</p>

<pre>
<tt>f=  bar baz\
    biz
a:
    echo ==$f==
</tt>
</pre>

<p>echoes <tt>"==bar&nbsp;baz&nbsp;biz=="</tt> .</p>

<p>If $? were:</p>

<pre>
<tt>/usr/include/stdio.h /usr/include/unistd.h foo.h
</tt>
</pre>

<p>then $(?D) would be:</p>

<pre>
<tt>/usr/include /usr/include .
</tt>
</pre>

<p>and $(?F) would be:</p>

<pre>
<tt>stdio.h unistd.h foo.h
</tt>
</pre>
</li>

<li>
<p>The contents of the built-in rules can be viewed by running:</p>

<pre>
<tt>make -p -f /dev/null 2&gt;/dev/null
</tt>
</pre>
</li>
</ol>
</blockquote>

<h4><a name="tag_04_84_18"></a>RATIONALE</h4>

<blockquote>
<p>The <i>make</i> utility described in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 is intended to provide the means for changing
portable source code into executables that can be run on an IEEE&nbsp;Std&nbsp;1003.1-2001-conforming system. It reflects the most
common features present in System V and BSD <i>make</i>s.</p>

<p>Historically, the <i>make</i> utility has been an especially fertile ground for vendor and research organization-specific syntax
modifications and extensions. Examples include:</p>

<ul>
<li>
<p>Syntax supporting parallel execution (such as from various multi-processor vendors, GNU, and others)</p>
</li>

<li>
<p>Additional &quot;operators&quot; separating targets and their prerequisites (System V, BSD, and others)</p>
</li>

<li>
<p>Specifying that command lines containing the strings <tt>"${MAKE}"</tt> and <tt>"$(MAKE)"</tt> are executed when the <b>-n</b>
option is specified (GNU and System V)</p>
</li>

<li>
<p>Modifications of the meaning of internal macros when referencing libraries (BSD and others)</p>
</li>

<li>
<p>Using a single instance of the shell for all of the command lines of the target (BSD and others)</p>
</li>

<li>
<p>Allowing spaces as well as tabs to delimit command lines (BSD)</p>
</li>

<li>
<p>Adding C preprocessor-style &quot;include&quot; and &quot;ifdef&quot; constructs (System V, GNU, BSD, and others)</p>
</li>

<li>
<p>Remote execution of command lines (Sprite and others)</p>
</li>

<li>
<p>Specifying additional special targets (BSD, System V, and most others)</p>
</li>
</ul>

<p>Additionally, many vendors and research organizations have rethought the basic concepts of <i>make</i>, creating vastly
extended, as well as completely new, syntaxes. Each of these versions of <i>make</i> fulfills the needs of a different community of
users; it is unreasonable for this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 to require behavior that would be incompatible (and
probably inferior) to historical practice for such a community.</p>

<p>In similar circumstances, when the industry has enough sufficiently incompatible formats as to make them irreconcilable, this
volume of IEEE&nbsp;Std&nbsp;1003.1-2001 has followed one or both of two courses of action. Commands have been renamed ( <a href=
"../utilities/cksum.html"><i>cksum</i></a>, <a href="../utilities/echo.html"><i>echo</i></a>, and <a href=
"../utilities/pax.html"><i>pax</i></a>) and/or command line options have been provided to select the desired behavior ( <a href=
"../utilities/grep.html"><i>grep</i></a>, <a href="../utilities/od.html"><i>od</i></a>, and <a href=
"../utilities/pax.html"><i>pax</i></a>).</p>

<p>Because the syntax specified for the <i>make</i> utility is, by and large, a subset of the syntaxes accepted by almost all
versions of <i>make</i>, 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 <i>make</i> <b>-P</b>, to
achieve the portable behavior. Therefore, the special target <b>.POSIX</b> was added to the makefile, allowing users to specify
&quot;standard&quot; behavior. This special target does not preclude extensions in the <i>make</i> 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 <b>.POSIX</b> special target in order to guarantee that they are
not affected by local extensions.</p>

<p>The portable version of <i>make</i> 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>

<p>When the <b>-n</b> option is specified, it is always added to <i>MAKEFLAGS .</i> This allows a recursive <i>make</i> <b>-n</b>
<i>target</i> to be used to see all of the action that would be taken to update <i>target</i>.</p>

<p>The definition of <i>MAKEFLAGS</i> 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>

<p>Early proposals stated that an &quot;unquoted&quot; number sign was treated as the start of a comment. The <i>make</i> utility does not
pay any attention to quotes. A number sign starts a comment regardless of its surroundings.</p>

<p>The text about &quot;other implementation-defined pathnames may also be tried&quot; in addition to <b>./makefile</b> and
<b>./Makefile</b> is to allow such extensions as <b>SCCS/s.Makefile</b> 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 <b>/etc/Makefile</b>. XSI-conformant systems also try <b>./s.makefile</b>, <b>SCCS/s.makefile</b>, <b>./s.Makefile</b>, and
<b>SCCS/s.Makefile</b>.</p>

<p>Early proposals contained the macro <b>NPROC</b> as a means of specifying that <i>make</i> should use <i>n</i> 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&nbsp;Std&nbsp;1003.1-2001, but
could be provided as a compatible extension. The macro <b>PARALLEL</b> 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 <b>NPROC</b> and/or <b>PARALLEL</b> as extensions to <i>make</i>.</p>

<p>The default rules are based on System V. The default <b>CC=</b> value is <a href="../utilities/c99.html"><i>c99</i></a> instead
of <i>cc</i> because this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 does not standardize the utility named <i>cc</i>. Thus, every
conforming application would be required to define <b>CC=</b> <a href="../utilities/c99.html"><i>c99</i></a> to expect to run.
There is no advantage conferred by the hope that the makefile might hit the &quot;preferred&quot; compiler because this cannot be
guaranteed to work. Also, since the portable makescript can only use the <a href="../utilities/c99.html"><i>c99</i></a> options, no
advantage is conferred in terms of what the script can do. It is a quality-of-implementation issue as to whether <a href=
"../utilities/c99.html"><i>c99</i></a> is as valuable as <i>cc</i>.</p>

<p>The <b>-d</b> option to <i>make</i> is frequently used to produce debugging information, but is too implementation-defined to
add to this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>

<p>The <b>-p</b> option is not passed in <i>MAKEFLAGS</i> on most historical implementations and to change this would cause many
implementations to break without sufficiently increased portability.</p>

<p>Commands that begin with a plus sign ( <tt>'+'</tt> ) are executed even if the <b>-n</b> option is present. Based on the GNU
version of <i>make</i>, the behavior of <b>-n</b> when the plus-sign prefix is encountered has been extended to apply to <b>-q</b>
and <b>-t</b> as well. However, the System V convention of forcing command execution with <b>-n</b> when the command line of a
target contains either of the strings <tt>"$(MAKE)"</tt> or <tt>"${MAKE}"</tt> 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:</p>

<pre>
<tt>subdir:
    cd subdir; rm all_the_files; $(MAKE)
</tt>
</pre>

<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>

<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>

<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>

<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 portions of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001. The default rules include rules for
optional commands in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001. Only rules pertaining to commands that are provided are needed
in the default set of an implementation.</p>

<p>One point of discussion was whether to drop the default rules list from this volume of IEEE&nbsp;Std&nbsp;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
<i>make</i> <i>command</i> and have the command build from a <b>command.c</b> file.</p>

<p>The historical <i>MAKESHELL</i> feature was omitted. In some implementations it is used to let a user override the shell to be
used to run <i>make</i> commands. This was confusing; for a portable <i>make</i>, the shell should be chosen by the makefile writer
or specified on the <i>make</i> command line and not by a user running <i>make</i>.</p>

<p>The <i>make</i> 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 <a href=
"../utilities/yacc.html"><i>yacc</i></a> programs; for example:</p>

<pre>
<tt>foo: y.tab.o lex.o main.o
    $(CC) $(CFLAGS) -o $</tt>@ <tt>t.tab.o lex.o main.o
</tt>
</pre>

<p>In this example, if <i>make</i> chose any arbitrary order, the <b>lex.o</b> might not be made with the correct <b>y.tab.h</b>.
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 <i>make</i> or the makefile format to accomplish it, as
described previously.</p>

<p>The algorithm for determining a new entry for target rules is partially unspecified. Some historical <i>make</i>s allow blank,
empty, or comment lines within the collection of commands marked by leading &lt;tab&gt;s. A conforming makefile must ensure that
each command starts with a &lt;tab&gt;, but implementations are free to ignore blank, empty, and comment lines without triggering
the start of a new entry.</p>

<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 <i>make</i> 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 <b>core</b> files upon receipt of SIGQUIT, the <b>core</b> from <i>make</i>
would conflict with a <b>core</b> 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 <i>make</i> is rerun.</p>

<p>The <b>.PRECIOUS</b> special target was extended to affect all targets globally (by specifying no prerequisites). The
<b>.IGNORE</b> and <b>.SILENT</b> 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 entir