Fresh Fish 8/FreshFishVol8-CD1.bin/gnu/info/make.info-3

GNU Info File | 1994-11-12 | 51KB | 928 lines

This is Info file make.info, produced by Makeinfo-1.55 from the input
file ./make.texinfo.
   This file documents the GNU Make utility, which determines
automatically which pieces of a large program need to be recompiled,
and issues the commands to recompile them.
   This is Edition 0.47, last updated 1 November 1994, of `The GNU Make
Manual', for `make', Version 3.72 Beta.
   Copyright (C) 1988, '89, '90, '91, '92, '93, '94 Free Software
Foundation, Inc.
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.
File: make.info,  Node: Parallel,  Next: Errors,  Prev: Execution,  Up: Commands
Parallel Execution
==================
   GNU `make' knows how to execute several commands at once.  Normally,
`make' will execute only one command at a time, waiting for it to
finish before executing the next.  However, the `-j' or `--jobs' option
tells `make' to execute many commands simultaneously.
   If the `-j' option is followed by an integer, this is the number of
commands to execute at once; this is called the number of "job slots".
If there is nothing looking like an integer after the `-j' 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).
   One unpleasant consequence of running several commands
simultaneously is that output from all of the commands comes when the
commands send it, so messages from different commands may be
interspersed.
   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, `make' 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 `Broken pipe'
signal) for most child processes if there are several.
   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 `make').  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.
   We will change how this aspect of `make' 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.
   If a command fails (is killed by a signal or exits with a nonzero
status), and errors are not ignored for that command (*note Errors in
Commands: Errors.), the remaining command lines to remake the same
target will not be run.  If a command fails and the `-k' or
`--keep-going' option was not given (*note Summary of Options: Options
Summary.), `make' aborts execution.  If make terminates for any reason
(including a signal) with child processes running, it waits for them to
finish before actually exiting.
   When the system is heavily loaded, you will probably want to run
fewer jobs than when it is lightly loaded.  You can use the `-l' option
to tell `make' to limit the number of jobs to run at once, based on the
load average.  The `-l' or `--max-load' option is followed by a
floating-point number.  For example,
     -l 2.5
will not let `make' start more than one job if the load average is
above 2.5.  The `-l' option with no following number removes the load
limit, if one was given with a previous `-l' option.
   More precisely, when `make' 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 `-l', `make' waits until the load
average goes below that limit, or until all the other jobs finish.
   By default, there is no load limit.
File: make.info,  Node: Errors,  Next: Interrupts,  Prev: Parallel,  Up: Commands
Errors in Commands
==================
   After each shell command returns, `make' 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.
   If there is an error (the exit status is nonzero), `make' gives up on
the current rule, and perhaps on all rules.
   Sometimes the failure of a certain command does not indicate a
problem.  For example, you may use the `mkdir' command to ensure that a
directory exists.  If the directory already exists, `mkdir' will report
an error, but you probably want `make' to continue regardless.
   To ignore errors in a command line, write a `-' at the beginning of
the line's text (after the initial tab).  The `-' is discarded before
the command is passed to the shell for execution.
   For example,
     clean:
             -rm -f *.o
This causes `rm' to continue even if it is unable to remove a file.
   When you run `make' with the `-i' or `--ignore-errors' flag, errors
are ignored in all commands of all rules.  A rule in the makefile for
the special target `.IGNORE' has the same effect, if there are no
dependencies.  These ways of ignoring errors are obsolete because `-'
is more flexible.
   When errors are to be ignored, because of either a `-' or the `-i'
flag, `make' 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.
   When an error happens that `make' 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.
   Normally `make' gives up immediately in this circumstance, returning
a nonzero status.  However, if the `-k' or `--keep-going' flag is
specified, `make' continues to consider the other dependencies 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, `make -k' will continue compiling other object files even
though it already knows that linking them will be impossible.  *Note
Summary of Options: Options Summary.
   The usual behavior assumes that your purpose is to get the specified
targets up to date; once `make' learns that this is impossible, it
might as well report the failure immediately.  The `-k' 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' `compile' command passes the `-k' flag by default.
   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 `make' runs, it will not try to update that
file.  The situation is just the same as when the command is killed by a
signal; *note Interrupts::..  So generally the right thing to do is to
delete the target file if the command fails after beginning to change
the file.  `make' will do this if `.DELETE_ON_ERROR' appears as a
target.  This is almost always what you want `make' to do, but it is
not historical practice; so for compatibility, you must explicitly
request it.
File: make.info,  Node: Interrupts,  Next: Recursion,  Prev: Errors,  Up: Commands
Interrupting or Killing `make'
=============================