GNU make release 3.77.

1 files changed, 307 insertions, 24 deletions

diff --git a/make.texinfo b/make.texinfo
index 3c7e4d3..05d0746 100644
--- a/make.texinfo
+++ b/make.texinfo
@@ -8,12 +8,12 @@
 @c FSF publishers: format makebook.texi instead of using this file directly.
 
 @set RCSID $Id$
-@set EDITION 0.51
-@set VERSION 3.76 Beta
-@set UPDATED 26 Aug 1997
-@set UPDATE-MONTH Aug 1997
+@set EDITION 0.52
+@set VERSION 3.77
+@set UPDATED 20 May 1998
+@set UPDATE-MONTH May 1998
 @comment The ISBN number might need to change on next publication.
-@set ISBN 1-882114-78-7 @c CHANGE THIS BEFORE PRINTING AGAIN! --roland 9may96
+@set ISBN 1-882114-80-9 @c CHANGE THIS BEFORE PRINTING AGAIN! --psmith 16jul98
 
 @c finalout
 
@@ -27,7 +27,7 @@
 @ifinfo
 @dircategory The GNU make utility
 @direntry
-     * GNU make: (make.info).           The GNU make utility.
+     * Make: (make.info).               The GNU make utility.
 @end direntry
 
 This file documents the GNU Make utility, which determines
@@ -37,7 +37,7 @@ and issues the commands to recompile them.
 This is Edition @value{EDITION}, last updated @value{UPDATED},
 of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}.
 
-Copyright (C) 1988, '89, '90, '91, '92, '93, '94, '95, '96, '97
+Copyright (C) 1988, '89, '90, '91, '92, '93, '94, '95, '96, '97, '98
 	Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
@@ -68,7 +68,7 @@ by the Free Software Foundation.
 @titlepage
 @title GNU Make
 @subtitle A Program for Directing Recompilation
-@subtitle Edition @value{EDITION}, for @code{make} Version @value{VERSION}.
+@subtitle GNU @code{make} Version @value{VERSION}.
 @subtitle @value{UPDATE-MONTH}
 @author Richard M. Stallman and Roland McGrath
 @page
@@ -107,9 +107,9 @@ The GNU @code{make} utility automatically determines which pieces of a
 large program need to be recompiled, and issues the commands to
 recompile them.@refill
 
-This is Edition @value{EDITION} of the @cite{GNU Make Manual},
-last updated @value{UPDATED}
-for @code{make} Version @value{VERSION}.@refill
+This edition of the @cite{GNU Make Manual},
+last updated @value{UPDATED},
+documents GNU @code{make} Version @value{VERSION}.@refill
 
 This manual describes @code{make} and contains the following chapters:@refill
 @end ifinfo
@@ -132,6 +132,7 @@ This manual describes @code{make} and contains the following chapters:@refill
 * Missing::                     What GNU @code{make} lacks from other @code{make}s.
 * Makefile Conventions::        Conventions for makefiles in GNU programs.
 * Quick Reference::             A quick reference for experienced users.
+* Make Errors::                 A list of common errors generated by @code{make}.
 * Complex Makefile::            A real example of a straightforward,
                                  but nontrivial, makefile.
 * Concept Index::               Index of Concepts
@@ -425,17 +426,10 @@ send us the makefile and the exact results @code{make} gave you.  Also
 say what you expected to occur; this will help us decide whether the
 problem was really in the documentation.
 
-Once you've got a precise problem, please send electronic mail either
-through the Internet or via UUCP:
+Once you've got a precise problem, please send electronic mail to:
 
 @example
-@group
-@r{Internet address:}
-    bug-gnu-utils@@prep.ai.mit.edu
-
-@r{UUCP path:}
-    mit-eddie!prep.ai.mit.edu!bug-gnu-utils
-@end group
+    bug-make@@gnu.org
 @end example
 
 @noindent
@@ -3228,6 +3222,14 @@ You can write recursive @code{make} 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} relates to the top-level @code{make}.
 
+For your convenience, GNU @code{make} sets the variable @code{CURDIR} to
+the pathname of the current working directory for you.  If @code{-C} 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}
+will not override this value).  Note that setting this variable has no
+effect on the operation of @code{make}
+
 @menu
 * MAKE Variable::               The special effects of using @samp{$(MAKE)}.
 * Variables/Recursion::         How to communicate variables to a sub-@code{make}.
@@ -3828,6 +3830,10 @@ they have particular specialized uses.  @xref{Automatic, ,Automatic Variables}.
 * Defining::                    An alternate way to set a variable
                                   to a verbatim string.
 * Environment::                 Variable values can come from the environment.
+* Target-specific::             Variable values can be defined on a per-target
+                                  basis.
+* Pattern-specific::            Target-specific variable values can be applied
+                                  to a group of targets that match a pattern.
 * Automatic::                   Some special variables have predefined
                                   meanings for use with implicit rules.
 @end menu
@@ -4056,6 +4062,30 @@ Here the value of the variable @code{dir} is @w{@samp{/foo/bar    }}
 (with four trailing spaces), which was probably not the intention.
 (Imagine something like @w{@samp{$(dir)/file}} with this definition!)
 
+@cindex conditional variable assignment
+@cindex variables, conditional assignment
+@cindex ?=
+There is another assignment operator for variables, @samp{?=}.  This
+is called a conditional variable assignment operator, because it only
+has an effect if the variable is not yet defined.  This statement:
+
+@example
+FOO ?= bar
+@end example
+
+@noindent
+is exactly equivalent to this
+(@pxref{Origin Function, ,The @code{origin} Function}):
+
+@example
+ifeq ($(origin FOO), undefined)
+  FOO = bar
+endif
+@end example
+
+Note that a variable set to an empty value is still defined, so
+@samp{?=} will not set that variable.
+
 @node Advanced, Values, Flavors, Using Variables
 @section Advanced Features for Reference to Variables
 @cindex reference to variables
@@ -4353,6 +4383,7 @@ Several variables have constant initial values.
 @cindex variables, setting
 @cindex =
 @cindex :=
+@cindex ?=
 
 To set a variable from the makefile, write a line starting with the
 variable name followed by @samp{=} or @samp{:=}.  Whatever follows the
@@ -4389,6 +4420,24 @@ Several special variables are set
 automatically to a new value for each rule; these are called the
 @dfn{automatic} variables (@pxref{Automatic, ,Automatic Variables}).
 
+If you'd like a variable to be set to a value only if it's not already
+set, then you can use the shorthand operator @samp{?=} instead of
+@samp{=}.  These two settings of the variable @samp{FOO} are identical
+(@pxref{Origin Function, ,The @code{origin} Function}):
+
+@example
+FOO ?= bar
+@end example
+
+@noindent
+and
+
+@example
+ifeq ($(origin FOO), undefined)
+FOO = bar
+endif
+@end example
+
 @node Appending, Override Directive, Setting, Using Variables
 @section Appending More Text to Variables
 @cindex +=
@@ -4646,7 +4695,7 @@ endef
 @noindent
 @xref{Override Directive, ,The @code{override} Directive}.
 
-@node Environment,  , Defining, Using Variables
+@node Environment, Target-specific, Defining, Using Variables
 @section Variables from the Environment
 
 @cindex variables, environment
@@ -4690,6 +4739,113 @@ affect @code{make}.  So @code{make} ignores the environment value of
 usually not set.  @xref{Execution, ,Special handling of SHELL on
 MS-DOS}.)@refill
 
+@node Target-specific, Pattern-specific, Environment, Using Variables
+@section Target-specific Variable Values
+@cindex target-specific variables
+@cindex variables, target-specific
+
+Variable values in @code{make} are usually global; that is, they are the
+same regardless of where they are evaluated (unless they're reset, of
+course).  One exception to that is automatic variables
+(@pxref{Automatic, ,Automatic Variables}).
+
+The other exception is @dfn{target-specific variable values}.  This
+feature allows you to define different values for the same variable,
+based on the target that @code{make} is currently building.  As with
+automatic variables, these values are only available within the context
+of a target's command script (and in other target-specific assignments).
+
+Set a target-specific variable value like this:
+
+@example
+@var{target} @dots{} : @var{variable-assignment}
+@end example
+
+@noindent
+or like this:
+
+@example
+@var{target} @dots{} : override @var{variable-assignment}
+@end example
+
+Multiple @var{target} values create a target-specific variable value for
+each member of the target list individually.
+
+The @var{variable-assignment} can be any valid form of assignment;
+recursive (@samp{=}), static (@samp{:=}), appending (@samp{+=}), or
+conditional (@samp{?=}).  All variables that appear within the
+@var{variable-assignment} are evaluated within the context of the
+target: thus, any previously-defined target-specific variable values
+will be in effect.  Note that this variable is actually distinct from
+any ``global'' value: the two variables do not have to have the same
+flavor (recursive vs. static).
+
+Target-specific variables have the same priority as any other makefile
+variable.  Variables provided on the command-line (and in the
+environment if the @samp{-e} option is in force) will take precedence.
+Specifying the @code{override} directive will allow the target-specific
+variable value to be preferred.
+
+There is one more special feature of target-specific variables: when you
+define a target-specific variable, that variable value is also in effect
+for all dependencies of this target (unless those dependencies override
+it with their own target-specific variable value).  So, for example, a
+statement like this:
+
+@example
+prog : CFLAGS = -g
+prog : prog.o foo.o bar.o
+@end example
+
+@noindent
+will set @code{CFLAGS} to @samp{-g} in the command script for
+@file{prog}, but it will also set @code{CFLAGS} to @samp{-g} in the
+command scripts that create @file{prog.o}, @file{foo.o}, and
+@file{bar.o}, and any command scripts which create their dependencies.
+
+@node Pattern-specific,  , Target-specific, Using Variables
+@section Pattern-specific Variable Values
+@cindex pattern-specific variables
+@cindex variables, pattern-specific
+
+In addition to target-specific variable values (@pxref{Target-specific,
+,Target-specific Variable Values}), GNU @code{make} supports
+pattern-specific variable values.  In this form, a variable is defined
+for any target that matches the pattern specified.  Variables defined in
+this way are searched after any target-specific variables defined
+explicitly for that target, and before target-specific variables defined
+for the parent target.
+
+Set a pattern-specific variable value like this:
+
+@example
+@var{pattern} @dots{} : @var{variable-assignment}
+@end example
+
+@noindent
+or like this:
+
+@example
+@var{pattern} @dots{} : override @var{variable-assignment}
+@end example
+
+@noindent
+where @var{pattern} is a %-pattern.  As with target-specific variable
+values, multiple @var{pattern} values create a pattern-specific variable
+value for each pattern individually.  The @var{variable-assignment} can
+be any valid form of assignment.  Any command-line variable setting will
+take precedence, unless @code{override} is specified.
+
+For example:
+
+@example
+%.o : CFLAGS = -O
+@end example
+
+@noindent
+will assign @code{CFLAGS} the value of @samp{-O} for all targets
+matching the pattern @code{%.o}.
+
 @node Conditionals, Functions, Using Variables, Top
 @chapter Conditional Parts of Makefiles
 
@@ -6396,7 +6552,10 @@ pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern
 Rules}).  The @samp{-r} option also clears out the default list of
 suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix
 Rules}).  But you can still define your own suffixes with a rule for
-@code{.SUFFIXES}, and then define your own suffix rules.
+@code{.SUFFIXES}, and then define your own suffix rules.  Note that only
+@emph{rules} are affected by the @code{-r} option; default variables
+remain in effect (@pxref{Implicit Variables, ,Variables Used by Implicit
+Rules}).
 
 @item -s
 @cindex @code{-s}
@@ -8546,7 +8705,7 @@ special treatment.
 @comment included by standards.texi.
 @include make-stds.texi
 
-@node Quick Reference, Complex Makefile, Makefile Conventions, Top
+@node Quick Reference, Make Errors, Makefile Conventions, Top
 @appendix Quick Reference
 
 This appendix summarizes the directives, text manipulation functions,
@@ -8821,12 +8980,136 @@ The targets given to @code{make} on the command line.  Setting this
 variable has no effect on the operation of @code{make}.@*
 @xref{Goals, ,Arguments to Specify the Goals}.
 
+@item CURDIR
+
+Set to the pathname of the current working directory (after all
+@code{-C} options are processed, if any).  Setting this variable has no
+effect on the operation of @code{make}.@*
+@xref{Recursion, ,Recursive Use of @code{make}}.
+
 @item SUFFIXES
 
 The default list of suffixes before @code{make} reads any makefiles.
 @end table
 
-@node Complex Makefile, Concept Index, Quick Reference, Top
+@node Make Errors, Complex Makefile, Quick Reference, Top
+@comment  node-name,  next,  previous,  up
+@appendix Errors Generated by Make
+
+Here is a list of the most common errors you might see generated by
+@code{make}, and some information about what they mean and how to fix
+them.
+
+Sometimes @code{make} errors are not fatal, especially in the presence
+of a @code{-} prefix on a command script line, or the @code{-k} command
+line option.  Errors that are fatal are prefixed with the string
+@code{***}.
+
+Error messages are all either prefixed with the name of the program
+(usually @samp{make}), or, if the error is found in a makefile, the name
+of the file and linenumber containing the problem.
+
+In the table below, these common prefixes are left off.
+
+@table @samp
+
+@item [@var{foo}] Error @var{NN}
+@itemx [@var{foo}] @var{signal description}
+These errors are not really @code{make} errors at all.  They mean that a
+program that @code{make} invoked as part of a command script returned a
+non-0 error code (@samp{Error @var{NN}}), which @code{make} interprets
+as failure, or it exited in some other abnormal fashion (with a
+signal of some type).
+
+If no @code{***} is attached to the message, then the subprocess failed
+but the rule in the makefile was prefixed with the @code{-} special
+character, so @code{make} ignored the error.
+
+@item missing separator.  Stop.
+This is @code{make}'s generic ``Huh?'' error message.  It means that
+@code{make} was completely unsuccessful at parsing this line of your
+makefile.  It basically means ``syntax error''.
+
+One of the most common reasons for this message is that you (or perhaps
+your oh-so-helpful editor, as is the case with many MS-Windows editors)
+have attempted to indent your command scripts with spaces instead of a
+TAB character.  Remember that every line in the command script must
+begin with a TAB character.  Eight spaces do not count.
+
+@item commands commence before first target.  Stop.
+@itemx missing rule before commands.  Stop.
+This means the first thing in the makefile seems to be part of a command
+script: it begins with a TAB character and doesn't appear to be a legal
+@code{make} command (such as a variable assignment).  Command scripts
+must always be associated with a target.
+
+The second form is generated if the line has a semicolon as the first
+non-whitespace character; @code{make} interprets this to mean you left
+out the "target: dependency" section of a rule.
+
+@item No rule to make target `@var{xxx}'.
+@itemx No rule to make target `@var{xxx}', needed by `@var{yyy}'.
+This means that @code{make} decided it needed to build a target, but
+then couldn't find any instructions in the makefile on how to do that,
+either explicit or implicit (including in the default rules database).
+
+If you want that file to be built, you will need to add a rule to your
+makefile describing how that target can be built.  Other possible
+sources of this problem are typos in the makefile (if that filename is
+wrong) or a corrupted source tree (if that file is not supposed to be
+built, but rather only a dependency).
+
+@item No targets specified and no makefile found.  Stop.
+@itemx No targets.  Stop.
+The former means that you didn't provide any targets to be built on the
+command line, and @code{make} couldn't find any makefiles to read in.
+The latter means that some makefile was found, but it didn't contain any
+default target and none was given on the command line.  GNU @code{make}
+has nothing to do in these situations.
+
+@item Makefile `@var{xxx}' was not found.
+@itemx Included makefile `@var{xxx}' was not found.
+A makefile specified on the command line (first form) or included
+(second form) was not found.
+
+@item warning: overriding commands for target `@var{xxx}'
+@itemx warning: ignoring old commands for target `@var{xxx}'
+GNU @code{make} allows commands to be specified only once per target
+(except for double-colon rules).  If you give commands for a target
+which already has been defined to have commands, this warning is issued
+and the second set of commands will overwrite the first set.
+
+@item Circular @var{xxx} <- @var{yyy} dependency dropped.
+This means that @code{make} detected a loop in the dependency graph:
+after tracing the dependency @var{yyy} of target @var{xxx}, and its
+dependencies, etc., one of them depended on @var{xxx} again.
+
+@item Recursive variable `@var{xxx}' references itself (eventually).  Stop.
+This means you've defined a normal (recursive) @code{make} variable
+@var{xxx} that, when its expanded, will refer to itself (@var{xxx}).
+This is not allowed; either use simply-expanded variables (@code{:=}) or
+use the append operator (@code{+=}).
+
+@item Unterminated variable reference.  Stop.
+This means you forgot to provide the proper closing parenthesis
+or brace in your variable or function reference.
+
+@item insufficient arguments to function `@var{xxx}'.  Stop.
+This means you haven't provided the requisite number of arguments for
+this function.  See the documentation of the function for a description
+of its arguments.
+
+@item missing target pattern.  Stop.
+@itemx multiple target patterns.  Stop.
+@itemx target pattern contains no `%'.  Stop.
+These are generated for malformed static pattern rules.  The first means
+there's no pattern in the target section of the rule, the second means
+there are multiple patterns in the target section, and the third means
+the target doesn't contain a pattern character (@code{%}).
+
+@end table
+
+@node Complex Makefile, Concept Index, Make Errors, Top
 @appendix Complex Makefile Example
 
 Here is the makefile for the GNU @code{tar} program.  This is a