diff options
Diffstat (limited to 'doc/make.texi')
| -rw-r--r-- | doc/make.texi | 66 |
1 files changed, 42 insertions, 24 deletions
diff --git a/doc/make.texi b/doc/make.texi index 2efcca0..3c01e0a 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -308,7 +308,7 @@ Defining and Redefining Pattern Rules * Pattern Intro:: An introduction to pattern rules. * Pattern Examples:: Examples of pattern rules. -* Automatic:: How to use automatic variables in the +* Automatic Variables:: How to use automatic variables in the commands of implicit rules. * Pattern Match:: How patterns match. * Match-Anything Rules:: Precautions you should take prior to @@ -1776,7 +1776,7 @@ print: *.c This rule uses @file{print} as an empty target file; see @ref{Empty Targets, ,Empty Target Files to Record Events}. (The automatic variable @samp{$?} is used to print only those files that have changed; see -@ref{Automatic, ,Automatic Variables}.)@refill +@ref{Automatic Variables}.)@refill Wildcard expansion does not happen when you define a variable. Thus, if you write this: @@ -2171,7 +2171,7 @@ Therefore, you must write the commands with care so that they will look for the prerequisite in the directory where @code{make} finds it. This is done with the @dfn{automatic variables} such as @samp{$^} -(@pxref{Automatic, ,Automatic Variables}). +(@pxref{Automatic Variables}). For instance, the value of @samp{$^} is a list of all the prerequisites of the rule, including the names of the directories in which they were found, and the value of @@ -2514,7 +2514,7 @@ print: foo.c bar.c With this rule, @samp{make print} will execute the @code{lpr} command if either source file has changed since the last @samp{make print}. The automatic variable @samp{$?} is used to print only those files that have -changed (@pxref{Automatic, ,Automatic Variables}). +changed (@pxref{Automatic Variables}). @node Special Targets, Multiple Targets, Empty Targets, Rules @section Special Built-in Target Names @@ -2724,7 +2724,7 @@ mentioned. Similar commands work for all the targets. The commands do not need to be absolutely identical, since the automatic variable @samp{$@@} can be used to substitute the particular target to be remade into the -commands (@pxref{Automatic, ,Automatic Variables}). For example: +commands (@pxref{Automatic Variables}). For example: @example @group @@ -2912,7 +2912,7 @@ $(objects): %.o: %.c @noindent Here @samp{$<} is the automatic variable that holds the name of the prerequisite and @samp{$@@} is the automatic variable that holds the name -of the target; see @ref{Automatic, , Automatic Variables}. +of the target; see @ref{Automatic Variables}. Each target specified must match the target pattern; a warning is issued for each target that does not. If you have a list of files, only some of @@ -4234,7 +4234,7 @@ command options (@pxref{Overriding, ,Overriding Variables}). A few variables have names that are a single punctuation character or just a few characters. These are the @dfn{automatic variables}, and -they have particular specialized uses. @xref{Automatic, ,Automatic Variables}. +they have particular specialized uses. @xref{Automatic Variables}. @menu * Reference:: How to use the value of a variable. @@ -4303,7 +4303,7 @@ A dollar sign followed by a character other than a dollar sign, open-parenthesis or open-brace treats that single character as the variable name. Thus, you could reference the variable @code{x} with @samp{$x}. However, this practice is strongly discouraged, except in -the case of the automatic variables (@pxref{Automatic, ,Automatic Variables}). +the case of the automatic variables (@pxref{Automatic Variables}). @node Flavors, Advanced, Reference, Using Variables @section The Two Flavors of Variables @@ -4787,7 +4787,7 @@ Variables in the environment become @code{make} variables. @item Several @dfn{automatic} variables are given new values for each rule. Each of these has a single conventional use. -@xref{Automatic, ,Automatic Variables}. +@xref{Automatic Variables}. @item Several variables have constant initial values. @@ -4835,7 +4835,7 @@ that are not empty, but you can set them in the usual ways (@pxref{Implicit Variables, ,Variables Used by Implicit Rules}). Several special variables are set automatically to a new value for each rule; these are called the -@dfn{automatic} variables (@pxref{Automatic, ,Automatic Variables}). +@dfn{automatic} variables (@pxref{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 @@ -5173,7 +5173,7 @@ MS-DOS}.)@refill 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}). +(@pxref{Automatic Variables}). The other exception is @dfn{target-specific variable values}. This feature allows you to define different values for the same variable, @@ -5194,6 +5194,13 @@ or like this: @var{target} @dots{} : override @var{variable-assignment} @end example +@noindent +or like this: + +@example +@var{target} @dots{} : export @var{variable-assignment} +@end example + Multiple @var{target} values create a target-specific variable value for each member of the target list individually. @@ -5515,7 +5522,7 @@ beginning or the end of the conditional.@refill @code{make} evaluates conditionals when it reads a makefile. Consequently, you cannot use automatic variables in the tests of conditionals because they are not defined until commands are run -(@pxref{Automatic, , Automatic Variables}). +(@pxref{Automatic Variables}). To prevent intolerable confusion, it is not permitted to start a conditional in one makefile and end it in another. However, you may @@ -6517,7 +6524,7 @@ makefile (@pxref{Override Directive, ,The @code{override} Directive}). if @var{variable} is an automatic variable defined for the execution of the commands for each rule -(@pxref{Automatic, , Automatic Variables}). +(@pxref{Automatic Variables}). @end table This information is primarily useful (other than for your curiosity) to @@ -8185,7 +8192,7 @@ Variables}, and @ref{Functions, ,Functions for Transforming Text}. @menu * Pattern Intro:: An introduction to pattern rules. * Pattern Examples:: Examples of pattern rules. -* Automatic:: How to use automatic variables in the +* Automatic Variables:: How to use automatic variables in the commands of implicit rules. * Pattern Match:: How patterns match. * Match-Anything Rules:: Precautions you should take prior to @@ -8263,7 +8270,7 @@ rule with prerequisites that must be made by chaining other implicit rules. @cindex pattern rules, order of @cindex order of pattern rules -@node Pattern Examples, Automatic, Pattern Intro, Pattern Rules +@node Pattern Examples, Automatic Variables, Pattern Intro, Pattern Rules @subsection Pattern Rule Examples Here are some examples of pattern rules actually predefined in @@ -8279,7 +8286,7 @@ files:@refill defines a rule that can make any file @file{@var{x}.o} from @file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and @samp{$<} to substitute the names of the target file and the source file -in each case where the rule applies (@pxref{Automatic, ,Automatic Variables}).@refill +in each case where the rule applies (@pxref{Automatic Variables}).@refill Here is a second built-in rule: @@ -8320,7 +8327,7 @@ and the file @file{scan.o} from @file{scan.c}, while @file{foo} is linked from @file{parse.tab.o}, @file{scan.o}, and its other prerequisites, and it will execute happily ever after.)@refill -@node Automatic, Pattern Match, Pattern Examples, Pattern Rules +@node Automatic Variables, Pattern Match, Pattern Examples, Pattern Rules @subsection Automatic Variables @cindex automatic variables @cindex variables, automatic @@ -8337,6 +8344,17 @@ is executed, based on the target and prerequisites of the rule. In this example, you would use @samp{$@@} for the object file name and @samp{$<} for the source file name. +@cindex automatic variables in prerequisites +@cindex prerequisites, and automatic variables +It's very important that you recognize the limited scope in which +automatic variable values are available: they only have values within +the command script. In particular, you cannot use them anywhere +within the target or prerequisite lists of a rule; they have no value +there and will expand to the empty string. A common mistake is +attempting to use @code{$@@} within the prerequisites list in a rule; +this will not work. However, see below for information on the +SysV-style @code{$$@@} variables. + Here is a table of automatic variables: @table @code @@ -8551,7 +8569,7 @@ compatibility with SysV makefiles. In a native GNU @code{make} file there are other ways to accomplish the same results. This feature is disabled if the special pseudo target @code{.POSIX} is defined. -@node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules +@node Pattern Match, Match-Anything Rules, Automatic Variables, Pattern Rules @subsection How Patterns Match @cindex stem @@ -8930,7 +8948,7 @@ update status as the file @var{t}. When the commands of a pattern rule are executed for @var{t}, the automatic variables are set corresponding to the target and prerequisites. -@xref{Automatic, ,Automatic Variables}. +@xref{Automatic Variables}. @node Archives, Features, Implicit Rules, Top @chapter Using @code{make} to Update Archive Files @@ -9033,7 +9051,7 @@ Here @code{make} has envisioned the file @file{bar.o} as an intermediate file. @xref{Chained Rules, ,Chains of Implicit Rules}. Implicit rules such as this one are written using the automatic variable -@samp{$%}. @xref{Automatic, ,Automatic Variables}. +@samp{$%}. @xref{Automatic Variables}. An archive member name in an archive cannot contain a directory name, but it may be useful in a makefile to pretend that it does. If you write an @@ -9196,13 +9214,13 @@ invocations of @code{make}. @item The automatic variable @code{$%} is set to the member name -in an archive reference. @xref{Automatic, ,Automatic Variables}. +in an archive reference. @xref{Automatic Variables}. @item The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%}, and @code{$?} have corresponding forms like @code{$(@@F)} and @code{$(@@D)}. We have generalized this to @code{$^} as an obvious -extension. @xref{Automatic, ,Automatic Variables}.@refill +extension. @xref{Automatic Variables}.@refill @item Substitution variable references. @@ -9254,7 +9272,7 @@ same time. @xref{Chained Rules, ,Chains of Implicit Rules}. @item The automatic variable @code{$^} containing a list of all prerequisites of the current target. We did not invent this, but we have no idea who -did. @xref{Automatic, ,Automatic Variables}. The automatic variable +did. @xref{Automatic Variables}. The automatic variable @code{$+} is a simple extension of @code{$^}. @item @@ -9711,7 +9729,7 @@ Evaluate the variable @var{var} replacing any references to @code{$(1)}, @end table Here is a summary of the automatic variables. -@xref{Automatic, ,Automatic Variables}, +@xref{Automatic Variables}, for full information. @table @code |