1252 lines
43 KiB
HTML
1252 lines
43 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<!-- This HTML file has been created by texi2html 1.54
|
|
from ../texi/make.texinfo on 19 July 2000 -->
|
|
|
|
<TITLE>GNU make - Writing the Commands in Rules</TITLE>
|
|
<link href="make_6.html" rel=Next>
|
|
<link href="make_4.html" rel=Previous>
|
|
<link href="make_toc.html" rel=ToC>
|
|
|
|
</HEAD>
|
|
<BODY>
|
|
<p>Go to the <A HREF="make_1.html">first</A>, <A HREF="make_4.html">previous</A>, <A HREF="make_6.html">next</A>, <A HREF="make_19.html">last</A> section, <A HREF="make_toc.html">table of contents</A>.
|
|
<P><HR><P>
|
|
|
|
|
|
<H1><A NAME="SEC44" HREF="make_toc.html#TOC44">Writing the Commands in Rules</A></H1>
|
|
<P>
|
|
<A NAME="IDX264"></A>
|
|
<A NAME="IDX265"></A>
|
|
<A NAME="IDX266"></A>
|
|
|
|
</P>
|
|
<P>
|
|
The commands of a rule consist of shell command lines to be executed one
|
|
by one. Each command line must start with a tab, except that the first
|
|
command line may be attached to the target-and-prerequisites line with a
|
|
semicolon in between. Blank lines and lines of just comments may appear
|
|
among the command lines; they are ignored. (But beware, an apparently
|
|
"blank" line that begins with a tab is <EM>not</EM> blank! It is an
|
|
empty command; see section <A HREF="make_5.html#SEC56">Using Empty Commands</A>.)
|
|
|
|
</P>
|
|
<P>
|
|
Users use many different shell programs, but commands in makefiles are
|
|
always interpreted by <TT>`/bin/sh'</TT> unless the makefile specifies
|
|
otherwise. See section <A HREF="make_5.html#SEC46">Command Execution</A>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX267"></A>
|
|
<A NAME="IDX268"></A>
|
|
<A NAME="IDX269"></A>
|
|
The shell that is in use determines whether comments can be written on
|
|
command lines, and what syntax they use. When the shell is
|
|
<TT>`/bin/sh'</TT>, a <SAMP>`#'</SAMP> starts a comment that extends to the end of
|
|
the line. The <SAMP>`#'</SAMP> does not have to be at the beginning of a line.
|
|
Text on a line before a <SAMP>`#'</SAMP> is not part of the comment.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC45" HREF="make_toc.html#TOC45">Command Echoing</A></H2>
|
|
<P>
|
|
<A NAME="IDX270"></A>
|
|
<A NAME="IDX271"></A>
|
|
<A NAME="IDX272"></A>
|
|
<A NAME="IDX273"></A>
|
|
<A NAME="IDX274"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Normally <CODE>make</CODE> prints each command line before it is executed.
|
|
We call this <STRONG>echoing</STRONG> because it gives the appearance that you
|
|
are typing the commands yourself.
|
|
|
|
</P>
|
|
<P>
|
|
When a line starts with <SAMP>`@'</SAMP>, the echoing of that line is suppressed.
|
|
The <SAMP>`@'</SAMP> is discarded before the command is passed to the shell.
|
|
Typically you would use this for a command whose only effect is to print
|
|
something, such as an <CODE>echo</CODE> command to indicate progress through
|
|
the makefile:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
@echo About to make distribution files
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX275"></A>
|
|
<A NAME="IDX276"></A>
|
|
<A NAME="IDX277"></A>
|
|
<A NAME="IDX278"></A>
|
|
When <CODE>make</CODE> is given the flag <SAMP>`-n'</SAMP> or <SAMP>`--just-print'</SAMP>
|
|
it only echoes commands, it won't execute them. See section <A HREF="make_9.html#SEC92">Summary of Options</A>. In this case and only this case, even the
|
|
commands starting with <SAMP>`@'</SAMP> are printed. This flag is useful for
|
|
finding out which commands <CODE>make</CODE> thinks are necessary without
|
|
actually doing them.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX279"></A>
|
|
<A NAME="IDX280"></A>
|
|
<A NAME="IDX281"></A>
|
|
<A NAME="IDX282"></A>
|
|
The <SAMP>`-s'</SAMP> or <SAMP>`--silent'</SAMP>
|
|
flag to <CODE>make</CODE> prevents all echoing, as if all commands
|
|
started with <SAMP>`@'</SAMP>. A rule in the makefile for the special target
|
|
<CODE>.SILENT</CODE> without prerequisites has the same effect
|
|
(see section <A HREF="make_4.html#SEC36">Special Built-in Target Names</A>).
|
|
<CODE>.SILENT</CODE> is essentially obsolete since <SAMP>`@'</SAMP> is more flexible.
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC46" HREF="make_toc.html#TOC46">Command Execution</A></H2>
|
|
<P>
|
|
<A NAME="IDX283"></A>
|
|
<A NAME="IDX284"></A>
|
|
<A NAME="IDX285"></A>
|
|
<A NAME="IDX286"></A>
|
|
|
|
</P>
|
|
<P>
|
|
When it is time to execute commands to update a target, they are executed
|
|
by making a new subshell for each line. (In practice, <CODE>make</CODE> may
|
|
take shortcuts that do not affect the results.)
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX287"></A>
|
|
<STRONG>Please note:</STRONG> this implies that shell commands such as <CODE>cd</CODE>
|
|
that set variables local to each process will not affect the following
|
|
command lines. <A NAME="DOCF2" HREF="make_foot.html#FOOT2">(2)</A> If you want to use <CODE>cd</CODE>
|
|
to affect the next command, put the two on a single line with a
|
|
semicolon between them. Then <CODE>make</CODE> will consider them a single
|
|
command and pass them, together, to a shell which will execute them in
|
|
sequence. For example:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
foo : bar/lose
|
|
cd bar; gobble lose > ../foo
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX288"></A>
|
|
<A NAME="IDX289"></A>
|
|
<A NAME="IDX290"></A>
|
|
<A NAME="IDX291"></A>
|
|
<A NAME="IDX292"></A>
|
|
<A NAME="IDX293"></A>
|
|
If you would like to split a single shell command into multiple lines of
|
|
text, you must use a backslash at the end of all but the last subline.
|
|
Such a sequence of lines is combined into a single line, by deleting the
|
|
backslash-newline sequences, before passing it to the shell. Thus, the
|
|
following is equivalent to the preceding example:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
foo : bar/lose
|
|
cd bar; \
|
|
gobble lose > ../foo
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX294"></A>
|
|
The program used as the shell is taken from the variable <CODE>SHELL</CODE>.
|
|
By default, the program <TT>`/bin/sh'</TT> is used.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX295"></A>
|
|
On MS-DOS, if <CODE>SHELL</CODE> is not set, the value of the variable
|
|
<CODE>COMSPEC</CODE> (which is always set) is used instead.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX296"></A>
|
|
The processing of lines that set the variable <CODE>SHELL</CODE> in Makefiles
|
|
is different on MS-DOS. The stock shell, <TT>`command.com'</TT>, is
|
|
ridiculously limited in its functionality and many users of <CODE>make</CODE>
|
|
tend to install a replacement shell. Therefore, on MS-DOS, <CODE>make</CODE>
|
|
examines the value of <CODE>SHELL</CODE>, and changes its behavior based on
|
|
whether it points to a Unix-style or DOS-style shell. This allows
|
|
reasonable functionality even if <CODE>SHELL</CODE> points to
|
|
<TT>`command.com'</TT>.
|
|
|
|
</P>
|
|
<P>
|
|
If <CODE>SHELL</CODE> points to a Unix-style shell, <CODE>make</CODE> on MS-DOS
|
|
additionally checks whether that shell can indeed be found; if not, it
|
|
ignores the line that sets <CODE>SHELL</CODE>. In MS-DOS, GNU <CODE>make</CODE>
|
|
searches for the shell in the following places:
|
|
|
|
</P>
|
|
|
|
<OL>
|
|
<LI>
|
|
|
|
In the precise place pointed to by the value of <CODE>SHELL</CODE>. For
|
|
example, if the makefile specifies <SAMP>`SHELL = /bin/sh'</SAMP>, <CODE>make</CODE>
|
|
will look in the directory <TT>`/bin'</TT> on the current drive.
|
|
|
|
<LI>
|
|
|
|
In the current directory.
|
|
|
|
<LI>
|
|
|
|
In each of the directories in the <CODE>PATH</CODE> variable, in order.
|
|
|
|
</OL>
|
|
|
|
<P>
|
|
In every directory it examines, <CODE>make</CODE> will first look for the
|
|
specific file (<TT>`sh'</TT> in the example above). If this is not found,
|
|
it will also look in that directory for that file with one of the known
|
|
extensions which identify executable files. For example <TT>`.exe'</TT>,
|
|
<TT>`.com'</TT>, <TT>`.bat'</TT>, <TT>`.btm'</TT>, <TT>`.sh'</TT>, and some others.
|
|
|
|
</P>
|
|
<P>
|
|
If any of these attempts is successful, the value of <CODE>SHELL</CODE> will
|
|
be set to the full pathname of the shell as found. However, if none of
|
|
these is found, the value of <CODE>SHELL</CODE> will not be changed, and thus
|
|
the line that sets it will be effectively ignored. This is so
|
|
<CODE>make</CODE> will only support features specific to a Unix-style shell if
|
|
such a shell is actually installed on the system where <CODE>make</CODE> runs.
|
|
|
|
</P>
|
|
<P>
|
|
Note that this extended search for the shell is limited to the cases
|
|
where <CODE>SHELL</CODE> is set from the Makefile; if it is set in the
|
|
environment or command line, you are expected to set it to the full
|
|
pathname of the shell, exactly as things are on Unix.
|
|
|
|
</P>
|
|
<P>
|
|
The effect of the above DOS-specific processing is that a Makefile that
|
|
says <SAMP>`SHELL = /bin/sh'</SAMP> (as many Unix makefiles do), will work
|
|
on MS-DOS unaltered if you have e.g. <TT>`sh.exe'</TT> installed in some
|
|
directory along your <CODE>PATH</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX297"></A>
|
|
Unlike most variables, the variable <CODE>SHELL</CODE> is never set from the
|
|
environment. This is because the <CODE>SHELL</CODE> environment variable is
|
|
used to specify your personal choice of shell program for interactive
|
|
use. It would be very bad for personal choices like this to affect the
|
|
functioning of makefiles. See section <A HREF="make_6.html#SEC68">Variables from the Environment</A>. However, on MS-DOS and MS-Windows the value of
|
|
<CODE>SHELL</CODE> in the environment <STRONG>is</STRONG> used, since on those systems
|
|
most users do not set this variable, and therefore it is most likely set
|
|
specifically to be used by <CODE>make</CODE>. On MS-DOS, if the setting of
|
|
<CODE>SHELL</CODE> is not suitable for <CODE>make</CODE>, you can set the variable
|
|
<CODE>MAKESHELL</CODE> to the shell that <CODE>make</CODE> should use; this will
|
|
override the value of <CODE>SHELL</CODE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC47" HREF="make_toc.html#TOC47">Parallel Execution</A></H2>
|
|
<P>
|
|
<A NAME="IDX298"></A>
|
|
<A NAME="IDX299"></A>
|
|
<A NAME="IDX300"></A>
|
|
<A NAME="IDX301"></A>
|
|
<A NAME="IDX302"></A>
|
|
<A NAME="IDX303"></A>
|
|
|
|
</P>
|
|
<P>
|
|
GNU <CODE>make</CODE> knows how to execute several commands at once.
|
|
Normally, <CODE>make</CODE> will execute only one command at a time, waiting
|
|
for it to finish before executing the next. However, the <SAMP>`-j'</SAMP> or
|
|
<SAMP>`--jobs'</SAMP> option tells <CODE>make</CODE> to execute many commands
|
|
simultaneously.
|
|
</P>
|
|
<P>
|
|
On MS-DOS, the <SAMP>`-j'</SAMP> option has no effect, since that system doesn't
|
|
support multi-processing.
|
|
|
|
</P>
|
|
<P>
|
|
If the <SAMP>`-j'</SAMP> option is followed by an integer, this is the number of
|
|
commands to execute at once; this is called the number of <STRONG>job slots</STRONG>.
|
|
If there is nothing looking like an integer after the <SAMP>`-j'</SAMP> option,
|
|
there is no limit on the number of job slots. The default number of job
|
|
slots is one, which means serial execution (one thing at a time).
|
|
|
|
</P>
|
|
<P>
|
|
One unpleasant consequence of running several commands simultaneously is
|
|
that output generated by the commands appears whenever each command
|
|
sends it, so messages from different commands may be interspersed.
|
|
|
|
</P>
|
|
<P>
|
|
Another problem is that two processes cannot both take input from the
|
|
same device; so to make sure that only one command tries to take input
|
|
from the terminal at once, <CODE>make</CODE> will invalidate the standard
|
|
input streams of all but one running command. This means that
|
|
attempting to read from standard input will usually be a fatal error (a
|
|
<SAMP>`Broken pipe'</SAMP> signal) for most child processes if there are
|
|
several.
|
|
<A NAME="IDX304"></A>
|
|
<A NAME="IDX305"></A>
|
|
|
|
</P>
|
|
<P>
|
|
It is unpredictable which command will have a valid standard input stream
|
|
(which will come from the terminal, or wherever you redirect the standard
|
|
input of <CODE>make</CODE>). The first command run will always get it first, and
|
|
the first command started after that one finishes will get it next, and so
|
|
on.
|
|
|
|
</P>
|
|
<P>
|
|
We will change how this aspect of <CODE>make</CODE> works if we find a better
|
|
alternative. In the mean time, you should not rely on any command using
|
|
standard input at all if you are using the parallel execution feature; but
|
|
if you are not using this feature, then standard input works normally in
|
|
all commands.
|
|
|
|
</P>
|
|
<P>
|
|
Finally, handling recursive <CODE>make</CODE> invocations raises issues. For
|
|
more information on this, see
|
|
section <A HREF="make_5.html#SEC53">Communicating Options to a Sub-<CODE>make</CODE></A>.
|
|
|
|
</P>
|
|
<P>
|
|
If a command fails (is killed by a signal or exits with a nonzero
|
|
status), and errors are not ignored for that command
|
|
(see section <A HREF="make_5.html#SEC48">Errors in Commands</A>),
|
|
the remaining command lines to remake the same target will not be run.
|
|
If a command fails and the <SAMP>`-k'</SAMP> or <SAMP>`--keep-going'</SAMP>
|
|
option was not given
|
|
(see section <A HREF="make_9.html#SEC92">Summary of Options</A>),
|
|
<CODE>make</CODE> aborts execution. If make
|
|
terminates for any reason (including a signal) with child processes
|
|
running, it waits for them to finish before actually exiting.
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX306"></A>
|
|
<A NAME="IDX307"></A>
|
|
<A NAME="IDX308"></A>
|
|
<A NAME="IDX309"></A>
|
|
<A NAME="IDX310"></A>
|
|
<A NAME="IDX311"></A>
|
|
When the system is heavily loaded, you will probably want to run fewer jobs
|
|
than when it is lightly loaded. You can use the <SAMP>`-l'</SAMP> option to tell
|
|
<CODE>make</CODE> to limit the number of jobs to run at once, based on the load
|
|
average. The <SAMP>`-l'</SAMP> or <SAMP>`--max-load'</SAMP>
|
|
option is followed by a floating-point number. For
|
|
example,
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
-l 2.5
|
|
</PRE>
|
|
|
|
<P>
|
|
will not let <CODE>make</CODE> start more than one job if the load average is
|
|
above 2.5. The <SAMP>`-l'</SAMP> option with no following number removes the
|
|
load limit, if one was given with a previous <SAMP>`-l'</SAMP> option.
|
|
</P>
|
|
<P>
|
|
More precisely, when <CODE>make</CODE> goes to start up a job, and it already has
|
|
at least one job running, it checks the current load average; if it is not
|
|
lower than the limit given with <SAMP>`-l'</SAMP>, <CODE>make</CODE> waits until the load
|
|
average goes below that limit, or until all the other jobs finish.
|
|
|
|
</P>
|
|
<P>
|
|
By default, there is no load limit.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC48" HREF="make_toc.html#TOC48">Errors in Commands</A></H2>
|
|
<P>
|
|
<A NAME="IDX312"></A>
|
|
<A NAME="IDX313"></A>
|
|
<A NAME="IDX314"></A>
|
|
|
|
</P>
|
|
<P>
|
|
After each shell command returns, <CODE>make</CODE> looks at its exit status.
|
|
If the command completed successfully, the next command line is executed
|
|
in a new shell; after the last command line is finished, the rule is
|
|
finished.
|
|
|
|
</P>
|
|
<P>
|
|
If there is an error (the exit status is nonzero), <CODE>make</CODE> gives up on
|
|
the current rule, and perhaps on all rules.
|
|
|
|
</P>
|
|
<P>
|
|
Sometimes the failure of a certain command does not indicate a problem.
|
|
For example, you may use the <CODE>mkdir</CODE> command to ensure that a
|
|
directory exists. If the directory already exists, <CODE>mkdir</CODE> will
|
|
report an error, but you probably want <CODE>make</CODE> to continue regardless.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX315"></A>
|
|
To ignore errors in a command line, write a <SAMP>`-'</SAMP> at the beginning of
|
|
the line's text (after the initial tab). The <SAMP>`-'</SAMP> is discarded before
|
|
the command is passed to the shell for execution.
|
|
|
|
</P>
|
|
<P>
|
|
For example,
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
clean:
|
|
-rm -f *.o
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX316"></A>
|
|
|
|
</P>
|
|
<P>
|
|
This causes <CODE>rm</CODE> to continue even if it is unable to remove a file.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX317"></A>
|
|
<A NAME="IDX318"></A>
|
|
<A NAME="IDX319"></A>
|
|
When you run <CODE>make</CODE> with the <SAMP>`-i'</SAMP> or <SAMP>`--ignore-errors'</SAMP>
|
|
flag, errors are ignored in all commands of all rules. A rule in the
|
|
makefile for the special target <CODE>.IGNORE</CODE> has the same effect, if
|
|
there are no prerequisites. These ways of ignoring errors are obsolete
|
|
because <SAMP>`-'</SAMP> is more flexible.
|
|
|
|
</P>
|
|
<P>
|
|
When errors are to be ignored, because of either a <SAMP>`-'</SAMP> or the
|
|
<SAMP>`-i'</SAMP> flag, <CODE>make</CODE> treats an error return just like success,
|
|
except that it prints out a message that tells you the status code
|
|
the command exited with, and says that the error has been ignored.
|
|
|
|
</P>
|
|
<P>
|
|
When an error happens that <CODE>make</CODE> has not been told to ignore,
|
|
it implies that the current target cannot be correctly remade, and neither
|
|
can any other that depends on it either directly or indirectly. No further
|
|
commands will be executed for these targets, since their preconditions
|
|
have not been achieved.
|
|
|
|
</P>
|
|
|
|
<P>
|
|
<A NAME="IDX320"></A>
|
|
<A NAME="IDX321"></A>
|
|
Normally <CODE>make</CODE> gives up immediately in this circumstance, returning a
|
|
nonzero status. However, if the <SAMP>`-k'</SAMP> or <SAMP>`--keep-going'</SAMP>
|
|
flag is specified, <CODE>make</CODE>
|
|
continues to consider the other prerequisites of the pending targets,
|
|
remaking them if necessary, before it gives up and returns nonzero status.
|
|
For example, after an error in compiling one object file, <SAMP>`make -k'</SAMP>
|
|
will continue compiling other object files even though it already knows
|
|
that linking them will be impossible. See section <A HREF="make_9.html#SEC92">Summary of Options</A>.
|
|
|
|
</P>
|
|
<P>
|
|
The usual behavior assumes that your purpose is to get the specified
|
|
targets up to date; once <CODE>make</CODE> learns that this is impossible, it
|
|
might as well report the failure immediately. The <SAMP>`-k'</SAMP> option says
|
|
that the real purpose is to test as many of the changes made in the
|
|
program as possible, perhaps to find several independent problems so
|
|
that you can correct them all before the next attempt to compile. This
|
|
is why Emacs' <CODE>compile</CODE> command passes the <SAMP>`-k'</SAMP> flag by
|
|
default.
|
|
<A NAME="IDX322"></A>
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX323"></A>
|
|
<A NAME="IDX324"></A>
|
|
<A NAME="IDX325"></A>
|
|
<A NAME="IDX326"></A>
|
|
Usually when a command fails, if it has changed the target file at all,
|
|
the file is corrupted and cannot be used--or at least it is not
|
|
completely updated. Yet the file's timestamp says that it is now up to
|
|
date, so the next time <CODE>make</CODE> runs, it will not try to update that
|
|
file. The situation is just the same as when the command is killed by a
|
|
signal; see section <A HREF="make_5.html#SEC49">Interrupting or Killing <CODE>make</CODE></A>. So generally the right thing to do is to
|
|
delete the target file if the command fails after beginning to change
|
|
the file. <CODE>make</CODE> will do this if <CODE>.DELETE_ON_ERROR</CODE> appears
|
|
as a target. This is almost always what you want <CODE>make</CODE> to do, but
|
|
it is not historical practice; so for compatibility, you must explicitly
|
|
request it.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC49" HREF="make_toc.html#TOC49">Interrupting or Killing <CODE>make</CODE></A></H2>
|
|
<P>
|
|
<A NAME="IDX327"></A>
|
|
<A NAME="IDX328"></A>
|
|
<A NAME="IDX329"></A>
|
|
<A NAME="IDX330"></A>
|
|
<A NAME="IDX331"></A>
|
|
<A NAME="IDX332"></A>
|
|
|
|
</P>
|
|
<P>
|
|
If <CODE>make</CODE> gets a fatal signal while a command is executing, it may
|
|
delete the target file that the command was supposed to update. This is
|
|
done if the target file's last-modification time has changed since
|
|
<CODE>make</CODE> first checked it.
|
|
|
|
</P>
|
|
<P>
|
|
The purpose of deleting the target is to make sure that it is remade from
|
|
scratch when <CODE>make</CODE> is next run. Why is this? Suppose you type
|
|
<KBD>Ctrl-c</KBD> while a compiler is running, and it has begun to write an
|
|
object file <TT>`foo.o'</TT>. The <KBD>Ctrl-c</KBD> kills the compiler, resulting
|
|
in an incomplete file whose last-modification time is newer than the source
|
|
file <TT>`foo.c'</TT>. But <CODE>make</CODE> also receives the <KBD>Ctrl-c</KBD> signal
|
|
and deletes this incomplete file. If <CODE>make</CODE> did not do this, the next
|
|
invocation of <CODE>make</CODE> would think that <TT>`foo.o'</TT> did not require
|
|
updating--resulting in a strange error message from the linker when it
|
|
tries to link an object file half of which is missing.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX333"></A>
|
|
You can prevent the deletion of a target file in this way by making the
|
|
special target <CODE>.PRECIOUS</CODE> depend on it. Before remaking a target,
|
|
<CODE>make</CODE> checks to see whether it appears on the prerequisites of
|
|
<CODE>.PRECIOUS</CODE>, and thereby decides whether the target should be deleted
|
|
if a signal happens. Some reasons why you might do this are that the
|
|
target is updated in some atomic fashion, or exists only to record a
|
|
modification-time (its contents do not matter), or must exist at all
|
|
times to prevent other sorts of trouble.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC50" HREF="make_toc.html#TOC50">Recursive Use of <CODE>make</CODE></A></H2>
|
|
<P>
|
|
<A NAME="IDX334"></A>
|
|
<A NAME="IDX335"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Recursive use of <CODE>make</CODE> means using <CODE>make</CODE> as a command in a
|
|
makefile. This technique is useful when you want separate makefiles for
|
|
various subsystems that compose a larger system. For example, suppose you
|
|
have a subdirectory <TT>`subdir'</TT> which has its own makefile, and you would
|
|
like the containing directory's makefile to run <CODE>make</CODE> on the
|
|
subdirectory. You can do it by writing this:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
subsystem:
|
|
cd subdir && $(MAKE)
|
|
</PRE>
|
|
|
|
<P>
|
|
or, equivalently, this (see section <A HREF="make_9.html#SEC92">Summary of Options</A>):
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
subsystem:
|
|
$(MAKE) -C subdir
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX336"></A>
|
|
<A NAME="IDX337"></A>
|
|
|
|
</P>
|
|
<P>
|
|
You can write recursive <CODE>make</CODE> commands just by copying this example,
|
|
but there are many things to know about how they work and why, and about
|
|
how the sub-<CODE>make</CODE> relates to the top-level <CODE>make</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
For your convenience, GNU <CODE>make</CODE> sets the variable <CODE>CURDIR</CODE> to
|
|
the pathname of the current working directory for you. If <CODE>-C</CODE> is
|
|
in effect, it will contain the path of the new directory, not the
|
|
original. The value has the same precedence it would have if it were
|
|
set in the makefile (by default, an environment variable <CODE>CURDIR</CODE>
|
|
will not override this value). Note that setting this variable has no
|
|
effect on the operation of <CODE>make</CODE>
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC51" HREF="make_toc.html#TOC51">How the <CODE>MAKE</CODE> Variable Works</A></H3>
|
|
<P>
|
|
<A NAME="IDX338"></A>
|
|
<A NAME="IDX339"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Recursive <CODE>make</CODE> commands should always use the variable <CODE>MAKE</CODE>,
|
|
not the explicit command name <SAMP>`make'</SAMP>, as shown here:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
subsystem:
|
|
cd subdir && $(MAKE)
|
|
</PRE>
|
|
|
|
<P>
|
|
The value of this variable is the file name with which <CODE>make</CODE> was
|
|
invoked. If this file name was <TT>`/bin/make'</TT>, then the command executed
|
|
is <SAMP>`cd subdir && /bin/make'</SAMP>. If you use a special version of
|
|
<CODE>make</CODE> to run the top-level makefile, the same special version will be
|
|
executed for recursive invocations.
|
|
<A NAME="IDX340"></A>
|
|
|
|
</P>
|
|
<P>
|
|
As a special feature, using the variable <CODE>MAKE</CODE> in the commands of
|
|
a rule alters the effects of the <SAMP>`-t'</SAMP> (<SAMP>`--touch'</SAMP>), <SAMP>`-n'</SAMP>
|
|
(<SAMP>`--just-print'</SAMP>), or <SAMP>`-q'</SAMP> (<SAMP>`--question'</SAMP>) option.
|
|
Using the <CODE>MAKE</CODE> variable has the same effect as using a <SAMP>`+'</SAMP>
|
|
character at the beginning of the command line. See section <A HREF="make_9.html#SEC88">Instead of Executing the Commands</A>.
|
|
</P>
|
|
<P>
|
|
Consider the command <SAMP>`make -t'</SAMP> in the above example. (The
|
|
<SAMP>`-t'</SAMP> option marks targets as up to date without actually running
|
|
any commands; see section <A HREF="make_9.html#SEC88">Instead of Executing the Commands</A>.) Following the usual
|
|
definition of <SAMP>`-t'</SAMP>, a <SAMP>`make -t'</SAMP> command in the example would
|
|
create a file named <TT>`subsystem'</TT> and do nothing else. What you
|
|
really want it to do is run <SAMP>`cd subdir && make -t'</SAMP>; but that would
|
|
require executing the command, and <SAMP>`-t'</SAMP> says not to execute
|
|
commands.<A NAME="IDX341"></A>
|
|
<A NAME="IDX342"></A>
|
|
<A NAME="IDX343"></A>
|
|
|
|
</P>
|
|
<P>
|
|
The special feature makes this do what you want: whenever a command
|
|
line of a rule contains the variable <CODE>MAKE</CODE>, the flags <SAMP>`-t'</SAMP>,
|
|
<SAMP>`-n'</SAMP> and <SAMP>`-q'</SAMP> do not apply to that line. Command lines
|
|
containing <CODE>MAKE</CODE> are executed normally despite the presence of a
|
|
flag that causes most commands not to be run. The usual
|
|
<CODE>MAKEFLAGS</CODE> mechanism passes the flags to the sub-<CODE>make</CODE>
|
|
(see section <A HREF="make_5.html#SEC53">Communicating Options to a Sub-<CODE>make</CODE></A>), so your request to touch the files, or print the
|
|
commands, is propagated to the subsystem.
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC52" HREF="make_toc.html#TOC52">Communicating Variables to a Sub-<CODE>make</CODE></A></H3>
|
|
<P>
|
|
<A NAME="IDX344"></A>
|
|
<A NAME="IDX345"></A>
|
|
<A NAME="IDX346"></A>
|
|
<A NAME="IDX347"></A>
|
|
<A NAME="IDX348"></A>
|
|
<A NAME="IDX349"></A>
|
|
<A NAME="IDX350"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Variable values of the top-level <CODE>make</CODE> can be passed to the
|
|
sub-<CODE>make</CODE> through the environment by explicit request. These
|
|
variables are defined in the sub-<CODE>make</CODE> as defaults, but do not
|
|
override what is specified in the makefile used by the sub-<CODE>make</CODE>
|
|
makefile unless you use the <SAMP>`-e'</SAMP> switch (see section <A HREF="make_9.html#SEC92">Summary of Options</A>).
|
|
</P>
|
|
<P>
|
|
To pass down, or <STRONG>export</STRONG>, a variable, <CODE>make</CODE> adds the variable
|
|
and its value to the environment for running each command. The
|
|
sub-<CODE>make</CODE>, in turn, uses the environment to initialize its table
|
|
of variable values. See section <A HREF="make_6.html#SEC68">Variables from the Environment</A>.
|
|
|
|
</P>
|
|
<P>
|
|
Except by explicit request, <CODE>make</CODE> exports a variable only if it
|
|
is either defined in the environment initially or set on the command
|
|
line, and if its name consists only of letters, numbers, and underscores.
|
|
Some shells cannot cope with environment variable names consisting of
|
|
characters other than letters, numbers, and underscores.
|
|
|
|
</P>
|
|
<P>
|
|
The special variables <CODE>SHELL</CODE> and <CODE>MAKEFLAGS</CODE> are always
|
|
exported (unless you unexport them).
|
|
<CODE>MAKEFILES</CODE> is exported if you set it to anything.
|
|
|
|
</P>
|
|
<P>
|
|
<CODE>make</CODE> automatically passes down variable values that were defined
|
|
on the command line, by putting them in the <CODE>MAKEFLAGS</CODE> variable.
|
|
See the next section.
|
|
|
|
</P>
|
|
<P>
|
|
Variables are <EM>not</EM> normally passed down if they were created by
|
|
default by <CODE>make</CODE> (see section <A HREF="make_10.html#SEC96">Variables Used by Implicit Rules</A>). The sub-<CODE>make</CODE> will define these for
|
|
itself.
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX351"></A>
|
|
If you want to export specific variables to a sub-<CODE>make</CODE>, use the
|
|
<CODE>export</CODE> directive, like this:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
export <VAR>variable</VAR> ...
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX352"></A>
|
|
If you want to <EM>prevent</EM> a variable from being exported, use the
|
|
<CODE>unexport</CODE> directive, like this:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
unexport <VAR>variable</VAR> ...
|
|
</PRE>
|
|
|
|
<P>
|
|
As a convenience, you can define a variable and export it at the same
|
|
time by doing:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
export <VAR>variable</VAR> = value
|
|
</PRE>
|
|
|
|
<P>
|
|
has the same result as:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
<VAR>variable</VAR> = value
|
|
export <VAR>variable</VAR>
|
|
</PRE>
|
|
|
|
<P>
|
|
and
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
export <VAR>variable</VAR> := value
|
|
</PRE>
|
|
|
|
<P>
|
|
has the same result as:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
<VAR>variable</VAR> := value
|
|
export <VAR>variable</VAR>
|
|
</PRE>
|
|
|
|
<P>
|
|
Likewise,
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
export <VAR>variable</VAR> += value
|
|
</PRE>
|
|
|
|
<P>
|
|
is just like:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
<VAR>variable</VAR> += value
|
|
export <VAR>variable</VAR>
|
|
</PRE>
|
|
|
|
<P>
|
|
See section <A HREF="make_6.html#SEC65">Appending More Text to Variables</A>.
|
|
|
|
</P>
|
|
<P>
|
|
You may notice that the <CODE>export</CODE> and <CODE>unexport</CODE> directives
|
|
work in <CODE>make</CODE> in the same way they work in the shell, <CODE>sh</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
If you want all variables to be exported by default, you can use
|
|
<CODE>export</CODE> by itself:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
export
|
|
</PRE>
|
|
|
|
<P>
|
|
This tells <CODE>make</CODE> that variables which are not explicitly mentioned
|
|
in an <CODE>export</CODE> or <CODE>unexport</CODE> directive should be exported.
|
|
Any variable given in an <CODE>unexport</CODE> directive will still <EM>not</EM>
|
|
be exported. If you use <CODE>export</CODE> by itself to export variables by
|
|
default, variables whose names contain characters other than
|
|
alphanumerics and underscores will not be exported unless specifically
|
|
mentioned in an <CODE>export</CODE> directive.
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX353"></A>
|
|
The behavior elicited by an <CODE>export</CODE> directive by itself was the
|
|
default in older versions of GNU <CODE>make</CODE>. If your makefiles depend
|
|
on this behavior and you want to be compatible with old versions of
|
|
<CODE>make</CODE>, you can write a rule for the special target
|
|
<CODE>.EXPORT_ALL_VARIABLES</CODE> instead of using the <CODE>export</CODE> directive.
|
|
This will be ignored by old <CODE>make</CODE>s, while the <CODE>export</CODE>
|
|
directive will cause a syntax error.<A NAME="IDX354"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Likewise, you can use <CODE>unexport</CODE> by itself to tell <CODE>make</CODE>
|
|
<EM>not</EM> to export variables by default. Since this is the default
|
|
behavior, you would only need to do this if <CODE>export</CODE> had been used
|
|
by itself earlier (in an included makefile, perhaps). You
|
|
<STRONG>cannot</STRONG> use <CODE>export</CODE> and <CODE>unexport</CODE> by themselves to
|
|
have variables exported for some commands and not for others. The last
|
|
<CODE>export</CODE> or <CODE>unexport</CODE> directive that appears by itself
|
|
determines the behavior for the entire run of <CODE>make</CODE>.
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX355"></A>
|
|
<A NAME="IDX356"></A>
|
|
As a special feature, the variable <CODE>MAKELEVEL</CODE> is changed when it
|
|
is passed down from level to level. This variable's value is a string
|
|
which is the depth of the level as a decimal number. The value is
|
|
<SAMP>`0'</SAMP> for the top-level <CODE>make</CODE>; <SAMP>`1'</SAMP> for a sub-<CODE>make</CODE>,
|
|
<SAMP>`2'</SAMP> for a sub-sub-<CODE>make</CODE>, and so on. The incrementation
|
|
happens when <CODE>make</CODE> sets up the environment for a command.
|
|
</P>
|
|
<P>
|
|
The main use of <CODE>MAKELEVEL</CODE> is to test it in a conditional
|
|
directive (see section <A HREF="make_7.html#SEC71">Conditional Parts of Makefiles</A>); this
|
|
way you can write a makefile that behaves one way if run recursively and
|
|
another way if run directly by you.
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX357"></A>
|
|
You can use the variable <CODE>MAKEFILES</CODE> to cause all sub-<CODE>make</CODE>
|
|
commands to use additional makefiles. The value of <CODE>MAKEFILES</CODE> is
|
|
a whitespace-separated list of file names. This variable, if defined in
|
|
the outer-level makefile, is passed down through the environment; then
|
|
it serves as a list of extra makefiles for the sub-<CODE>make</CODE> to read
|
|
before the usual or specified ones. See section <A HREF="make_3.html#SEC16">The Variable <CODE>MAKEFILES</CODE></A>.
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC53" HREF="make_toc.html#TOC53">Communicating Options to a Sub-<CODE>make</CODE></A></H3>
|
|
<P>
|
|
<A NAME="IDX358"></A>
|
|
<A NAME="IDX359"></A>
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX360"></A>
|
|
Flags such as <SAMP>`-s'</SAMP> and <SAMP>`-k'</SAMP> are passed automatically to the
|
|
sub-<CODE>make</CODE> through the variable <CODE>MAKEFLAGS</CODE>. This variable is
|
|
set up automatically by <CODE>make</CODE> to contain the flag letters that
|
|
<CODE>make</CODE> received. Thus, if you do <SAMP>`make -ks'</SAMP> then
|
|
<CODE>MAKEFLAGS</CODE> gets the value <SAMP>`ks'</SAMP>.
|
|
</P>
|
|
<P>
|
|
As a consequence, every sub-<CODE>make</CODE> gets a value for <CODE>MAKEFLAGS</CODE>
|
|
in its environment. In response, it takes the flags from that value and
|
|
processes them as if they had been given as arguments.
|
|
See section <A HREF="make_9.html#SEC92">Summary of Options</A>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX361"></A>
|
|
<A NAME="IDX362"></A>
|
|
<A NAME="IDX363"></A>
|
|
Likewise variables defined on the command line are passed to the
|
|
sub-<CODE>make</CODE> through <CODE>MAKEFLAGS</CODE>. Words in the value of
|
|
<CODE>MAKEFLAGS</CODE> that contain <SAMP>`='</SAMP>, <CODE>make</CODE> treats as variable
|
|
definitions just as if they appeared on the command line.
|
|
See section <A HREF="make_9.html#SEC90">Overriding Variables</A>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX364"></A>
|
|
<A NAME="IDX365"></A>
|
|
<A NAME="IDX366"></A>
|
|
<A NAME="IDX367"></A>
|
|
<A NAME="IDX368"></A>
|
|
<A NAME="IDX369"></A>
|
|
<A NAME="IDX370"></A>
|
|
<A NAME="IDX371"></A>
|
|
<A NAME="IDX372"></A>
|
|
<A NAME="IDX373"></A>
|
|
<A NAME="IDX374"></A>
|
|
<A NAME="IDX375"></A>
|
|
<A NAME="IDX376"></A>
|
|
<A NAME="IDX377"></A>
|
|
The options <SAMP>`-C'</SAMP>, <SAMP>`-f'</SAMP>, <SAMP>`-o'</SAMP>, and <SAMP>`-W'</SAMP> are not put
|
|
into <CODE>MAKEFLAGS</CODE>; these options are not passed down.
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX378"></A>
|
|
<A NAME="IDX379"></A>
|
|
<A NAME="IDX380"></A>
|
|
<A NAME="IDX381"></A>
|
|
The <SAMP>`-j'</SAMP> option is a special case (see section <A HREF="make_5.html#SEC47">Parallel Execution</A>).
|
|
If you set it to some numeric value <SAMP>`N'</SAMP> and your operating system
|
|
supports it (most any UNIX system will; others typically won't), the
|
|
parent <CODE>make</CODE> and all the sub-<CODE>make</CODE>s will communicate to
|
|
ensure that there are only <SAMP>`N'</SAMP> jobs running at the same time
|
|
between them all. Note that any job that is marked recursive
|
|
(see section <A HREF="make_9.html#SEC88">Instead of Executing the Commands</A>)
|
|
doesn't count against the total jobs (otherwise we could get <SAMP>`N'</SAMP>
|
|
sub-<CODE>make</CODE>s running and have no slots left over for any real work!)
|
|
|
|
</P>
|
|
<P>
|
|
If your operating system doesn't support the above communication, then
|
|
<SAMP>`-j 1'</SAMP> is always put into <CODE>MAKEFLAGS</CODE> instead of the value you
|
|
specified. This is because if the <SAMP>`-j'</SAMP> option were passed down
|
|
to sub-<CODE>make</CODE>s, you would get many more jobs running in parallel
|
|
than you asked for. If you give <SAMP>`-j'</SAMP> with no numeric argument,
|
|
meaning to run as many jobs as possible in parallel, this is passed
|
|
down, since multiple infinities are no more than one.
|
|
</P>
|
|
<P>
|
|
If you do not want to pass the other flags down, you must change the
|
|
value of <CODE>MAKEFLAGS</CODE>, like this:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
subsystem:
|
|
cd subdir && $(MAKE) MAKEFLAGS=
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX382"></A>
|
|
The command line variable definitions really appear in the variable
|
|
<CODE>MAKEOVERRIDES</CODE>, and <CODE>MAKEFLAGS</CODE> contains a reference to this
|
|
variable. If you do want to pass flags down normally, but don't want to
|
|
pass down the command line variable definitions, you can reset
|
|
<CODE>MAKEOVERRIDES</CODE> to empty, like this:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
MAKEOVERRIDES =
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX383"></A>
|
|
<A NAME="IDX384"></A>
|
|
This is not usually useful to do. However, some systems have a small
|
|
fixed limit on the size of the environment, and putting so much
|
|
information into the value of <CODE>MAKEFLAGS</CODE> can exceed it. If you
|
|
see the error message <SAMP>`Arg list too long'</SAMP>, this may be the problem.
|
|
<A NAME="IDX385"></A>
|
|
<A NAME="IDX386"></A>
|
|
(For strict compliance with POSIX.2, changing <CODE>MAKEOVERRIDES</CODE> does
|
|
not affect <CODE>MAKEFLAGS</CODE> if the special target <SAMP>`.POSIX'</SAMP> appears
|
|
in the makefile. You probably do not care about this.)
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX387"></A>
|
|
A similar variable <CODE>MFLAGS</CODE> exists also, for historical
|
|
compatibility. It has the same value as <CODE>MAKEFLAGS</CODE> except that it
|
|
does not contain the command line variable definitions, and it always
|
|
begins with a hyphen unless it is empty (<CODE>MAKEFLAGS</CODE> begins with a
|
|
hyphen only when it begins with an option that has no single-letter
|
|
version, such as <SAMP>`--warn-undefined-variables'</SAMP>). <CODE>MFLAGS</CODE> was
|
|
traditionally used explicitly in the recursive <CODE>make</CODE> command, like
|
|
this:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
subsystem:
|
|
cd subdir && $(MAKE) $(MFLAGS)
|
|
</PRE>
|
|
|
|
<P>
|
|
but now <CODE>MAKEFLAGS</CODE> makes this usage redundant. If you want your
|
|
makefiles to be compatible with old <CODE>make</CODE> programs, use this
|
|
technique; it will work fine with more modern <CODE>make</CODE> versions too.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX388"></A>
|
|
<A NAME="IDX389"></A>
|
|
<A NAME="IDX390"></A>
|
|
<A NAME="IDX391"></A>
|
|
The <CODE>MAKEFLAGS</CODE> variable can also be useful if you want to have
|
|
certain options, such as <SAMP>`-k'</SAMP> (see section <A HREF="make_9.html#SEC92">Summary of Options</A>), set each time you run <CODE>make</CODE>. You simply put a value for
|
|
<CODE>MAKEFLAGS</CODE> in your environment. You can also set <CODE>MAKEFLAGS</CODE> in
|
|
a makefile, to specify additional flags that should also be in effect for
|
|
that makefile. (Note that you cannot use <CODE>MFLAGS</CODE> this way. That
|
|
variable is set only for compatibility; <CODE>make</CODE> does not interpret a
|
|
value you set for it in any way.)
|
|
|
|
</P>
|
|
<P>
|
|
When <CODE>make</CODE> interprets the value of <CODE>MAKEFLAGS</CODE> (either from the
|
|
environment or from a makefile), it first prepends a hyphen if the value
|
|
does not already begin with one. Then it chops the value into words
|
|
separated by blanks, and parses these words as if they were options given
|
|
on the command line (except that <SAMP>`-C'</SAMP>, <SAMP>`-f'</SAMP>, <SAMP>`-h'</SAMP>,
|
|
<SAMP>`-o'</SAMP>, <SAMP>`-W'</SAMP>, and their long-named versions are ignored; and there
|
|
is no error for an invalid option).
|
|
|
|
</P>
|
|
<P>
|
|
If you do put <CODE>MAKEFLAGS</CODE> in your environment, you should be sure not
|
|
to include any options that will drastically affect the actions of
|
|
<CODE>make</CODE> and undermine the purpose of makefiles and of <CODE>make</CODE>
|
|
itself. For instance, the <SAMP>`-t'</SAMP>, <SAMP>`-n'</SAMP>, and <SAMP>`-q'</SAMP> options, if
|
|
put in one of these variables, could have disastrous consequences and would
|
|
certainly have at least surprising and probably annoying effects.
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC54" HREF="make_toc.html#TOC54">The <SAMP>`--print-directory'</SAMP> Option</A></H3>
|
|
<P>
|
|
<A NAME="IDX392"></A>
|
|
<A NAME="IDX393"></A>
|
|
<A NAME="IDX394"></A>
|
|
|
|
</P>
|
|
<P>
|
|
If you use several levels of recursive <CODE>make</CODE> invocations, the
|
|
<SAMP>`-w'</SAMP> or <SAMP>`--print-directory'</SAMP> option can make the output a
|
|
lot easier to understand by showing each directory as <CODE>make</CODE>
|
|
starts processing it and as <CODE>make</CODE> finishes processing it. For
|
|
example, if <SAMP>`make -w'</SAMP> is run in the directory <TT>`/u/gnu/make'</TT>,
|
|
<CODE>make</CODE> will print a line of the form:
|
|
</P>
|
|
|
|
<PRE>
|
|
make: Entering directory `/u/gnu/make'.
|
|
</PRE>
|
|
|
|
<P>
|
|
before doing anything else, and a line of the form:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
make: Leaving directory `/u/gnu/make'.
|
|
</PRE>
|
|
|
|
<P>
|
|
when processing is completed.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX395"></A>
|
|
<A NAME="IDX396"></A>
|
|
<A NAME="IDX397"></A>
|
|
<A NAME="IDX398"></A>
|
|
<A NAME="IDX399"></A>
|
|
<A NAME="IDX400"></A>
|
|
<A NAME="IDX401"></A>
|
|
<A NAME="IDX402"></A>
|
|
<A NAME="IDX403"></A>
|
|
<A NAME="IDX404"></A>
|
|
Normally, you do not need to specify this option because <SAMP>`make'</SAMP>
|
|
does it for you: <SAMP>`-w'</SAMP> is turned on automatically when you use the
|
|
<SAMP>`-C'</SAMP> option, and in sub-<CODE>make</CODE>s. <CODE>make</CODE> will not
|
|
automatically turn on <SAMP>`-w'</SAMP> if you also use <SAMP>`-s'</SAMP>, which says to
|
|
be silent, or if you use <SAMP>`--no-print-directory'</SAMP> to explicitly
|
|
disable it.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC55" HREF="make_toc.html#TOC55">Defining Canned Command Sequences</A></H2>
|
|
<P>
|
|
<A NAME="IDX405"></A>
|
|
<A NAME="IDX406"></A>
|
|
|
|
</P>
|
|
<P>
|
|
When the same sequence of commands is useful in making various targets, you
|
|
can define it as a canned sequence with the <CODE>define</CODE> directive, and
|
|
refer to the canned sequence from the rules for those targets. The canned
|
|
sequence is actually a variable, so the name must not conflict with other
|
|
variable names.
|
|
|
|
</P>
|
|
<P>
|
|
Here is an example of defining a canned sequence of commands:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
define run-yacc
|
|
yacc $(firstword $^)
|
|
mv y.tab.c $@
|
|
endef
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="IDX407"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Here <CODE>run-yacc</CODE> is the name of the variable being defined;
|
|
<CODE>endef</CODE> marks the end of the definition; the lines in between are the
|
|
commands. The <CODE>define</CODE> directive does not expand variable references
|
|
and function calls in the canned sequence; the <SAMP>`$'</SAMP> characters,
|
|
parentheses, variable names, and so on, all become part of the value of the
|
|
variable you are defining.
|
|
See section <A HREF="make_6.html#SEC67">Defining Variables Verbatim</A>,
|
|
for a complete explanation of <CODE>define</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
The first command in this example runs Yacc on the first prerequisite of
|
|
whichever rule uses the canned sequence. The output file from Yacc is
|
|
always named <TT>`y.tab.c'</TT>. The second command moves the output to the
|
|
rule's target file name.
|
|
|
|
</P>
|
|
<P>
|
|
To use the canned sequence, substitute the variable into the commands of a
|
|
rule. You can substitute it like any other variable
|
|
(see section <A HREF="make_6.html#SEC58">Basics of Variable References</A>).
|
|
Because variables defined by <CODE>define</CODE> are recursively expanded
|
|
variables, all the variable references you wrote inside the <CODE>define</CODE>
|
|
are expanded now. For example:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
foo.c : foo.y
|
|
$(run-yacc)
|
|
</PRE>
|
|
|
|
<P>
|
|
<SAMP>`foo.y'</SAMP> will be substituted for the variable <SAMP>`$^'</SAMP> when it occurs in
|
|
<CODE>run-yacc</CODE>'s value, and <SAMP>`foo.c'</SAMP> for <SAMP>`$@'</SAMP>.
|
|
</P>
|
|
<P>
|
|
This is a realistic example, but this particular one is not needed in
|
|
practice because <CODE>make</CODE> has an implicit rule to figure out these
|
|
commands based on the file names involved
|
|
(see section <A HREF="make_10.html#SEC93">Using Implicit Rules</A>).
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX408"></A>
|
|
<A NAME="IDX409"></A>
|
|
<A NAME="IDX410"></A>
|
|
In command execution, each line of a canned sequence is treated just as
|
|
if the line appeared on its own in the rule, preceded by a tab. In
|
|
particular, <CODE>make</CODE> invokes a separate subshell for each line. You
|
|
can use the special prefix characters that affect command lines
|
|
(<SAMP>`@'</SAMP>, <SAMP>`-'</SAMP>, and <SAMP>`+'</SAMP>) on each line of a canned sequence.
|
|
See section <A HREF="make_5.html#SEC44">Writing the Commands in Rules</A>.
|
|
For example, using this canned sequence:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
define frobnicate
|
|
@echo "frobnicating target $@"
|
|
frob-step-1 $< -o $@-step-1
|
|
frob-step-2 $@-step-1 -o $@
|
|
endef
|
|
</PRE>
|
|
|
|
<P>
|
|
<CODE>make</CODE> will not echo the first line, the <CODE>echo</CODE> command.
|
|
But it <EM>will</EM> echo the following two command lines.
|
|
|
|
</P>
|
|
<P>
|
|
On the other hand, prefix characters on the command line that refers to
|
|
a canned sequence apply to every line in the sequence. So the rule:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
frob.out: frob.in
|
|
@$(frobnicate)
|
|
</PRE>
|
|
|
|
<P>
|
|
does not echo <EM>any</EM> commands.
|
|
(See section <A HREF="make_5.html#SEC45">Command Echoing</A>, for a full explanation of <SAMP>`@'</SAMP>.)
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC56" HREF="make_toc.html#TOC56">Using Empty Commands</A></H2>
|
|
<P>
|
|
<A NAME="IDX411"></A>
|
|
<A NAME="IDX412"></A>
|
|
|
|
</P>
|
|
<P>
|
|
It is sometimes useful to define commands which do nothing. This is done
|
|
simply by giving a command that consists of nothing but whitespace. For
|
|
example:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
target: ;
|
|
</PRE>
|
|
|
|
<P>
|
|
defines an empty command string for <TT>`target'</TT>. You could also use a
|
|
line beginning with a tab character to define an empty command string,
|
|
but this would be confusing because such a line looks empty.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX413"></A>
|
|
You may be wondering why you would want to define a command string that
|
|
does nothing. The only reason this is useful is to prevent a target
|
|
from getting implicit commands (from implicit rules or the
|
|
<CODE>.DEFAULT</CODE> special target; see section <A HREF="make_10.html#SEC93">Using Implicit Rules</A> and
|
|
see section <A HREF="make_10.html#SEC105">Defining Last-Resort Default Rules</A>).
|
|
</P>
|
|
|
|
<P>
|
|
You may be inclined to define empty command strings for targets that are
|
|
not actual files, but only exist so that their prerequisites can be
|
|
remade. However, this is not the best way to do that, because the
|
|
prerequisites may not be remade properly if the target file actually does exist.
|
|
See section <A HREF="make_4.html#SEC33">Phony Targets</A>, for a better way to do this.
|
|
|
|
</P>
|
|
<P><HR><P>
|
|
<p>Go to the <A HREF="make_1.html">first</A>, <A HREF="make_4.html">previous</A>, <A HREF="make_6.html">next</A>, <A HREF="make_19.html">last</A> section, <A HREF="make_toc.html">table of contents</A>.
|
|
</BODY>
|
|
</HTML>
|