summaryrefslogtreecommitdiff
path: root/make.texinfo
diff options
context:
space:
mode:
authorPaul Smith <psmith@gnu.org>1998-07-30 20:54:47 +0000
committerPaul Smith <psmith@gnu.org>1998-07-30 20:54:47 +0000
commite2403327e9913bbcbd515f9c38b8f4e26fb9b0d9 (patch)
tree8ac64ff471e0a976daf75ef913c084adba4972fc /make.texinfo
parent65a7296e2c81b04761b3f024572310a02c9de691 (diff)
downloadgunmake-e2403327e9913bbcbd515f9c38b8f4e26fb9b0d9.tar.gz
GNU make release 3.77.
Diffstat (limited to 'make.texinfo')
-rw-r--r--make.texinfo331
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