diff options
Diffstat (limited to 'make.texinfo')
| -rw-r--r-- | make.texinfo | 331 |
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 |