From f7985ab827f64c0d474ed38260169e8bdd2feab8 Mon Sep 17 00:00:00 2001 From: Paul Smith Date: Sun, 21 Apr 2024 12:42:55 -0400 Subject: [PATCH] * make.texi (How to Use Variables): [SV 65536] Rewrite this chapter Re-reading this chapter I decided it was time to introduce a complete rewrite, of at least parts of this. Much of the enhancements added over the years were in the wrong place or not clear. --- doc/.gitignore | 1 + doc/make.texi | 1258 +++++++++++++++++++++++++----------------------- 2 files changed, 665 insertions(+), 594 deletions(-) diff --git a/doc/.gitignore b/doc/.gitignore index 23bba342..c3829dea 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,4 +1,5 @@ manual/ +make.t2d/ make.t2p/ gendocs_template fdl.texi diff --git a/doc/make.texi b/doc/make.texi index cb7420d0..8b0f4506 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -239,13 +239,13 @@ Recursive Use of @code{make} How to Use Variables +* Variable Naming:: Choosing names for variables. * Reference:: How to use the value of a variable. * Flavors:: Variables come in two flavors. -* Advanced:: Advanced features for referencing a variable. +* Expanding:: How text is expanded by @code{make}. * Values:: All the ways variables get their values. * Setting:: How to set a variable in the makefile. -* Appending:: How to append more text to the old value - of a variable. +* Substitution Refs:: Substituting values in variable expansion. * Override Directive:: How to set a variable in the makefile even if the user has set it with a command argument. * Multi-Line:: An alternate way to set a variable @@ -260,18 +260,22 @@ How to Use Variables * Suppressing Inheritance:: Suppress inheritance of variables. * Special Variables:: Variables with special meaning or behavior. +Basics of Variable References + +* Computed Names:: Computing the name of a variable reference. + The Two Flavors of Variables -* Recursive Assignment:: Setting recursively expanded variables. -* Simple Assignment:: Setting simply expanded variables. -* Immediate Assignment:: Setting immediately expanded variables. -* Conditional Assignment:: Assigning variable values conditionally. +* Recursive Variables:: Recursive variables delay expansion. +* Simple Variables:: Simple variables expand immediately. -Advanced Features for Reference to Variables +Setting Variables -* Substitution Refs:: Referencing a variable with - substitutions on the value. -* Computed Names:: Computing the name of the variable to refer to. +* Immediate Assignment:: Recursive variables with immediate expansion. +* Shell Assignment:: Assigning variables to shell output. +* Conditional Assignment:: Assigning variables only if not yet defined. +* Appending Assignment:: How to append to the value of a variable. +* Whitespace in Values:: Leading and trailing whitespace in values. Conditional Parts of Makefiles @@ -430,9 +434,7 @@ from others whenever the others change. @end menu @node Preparing -@ifnottex -@heading Preparing and Running Make -@end ifnottex +@section Preparing and Running Make To use @code{make}, you must write a file called the @dfn{makefile} that describes the relationships among files in your program and provides commands @@ -5028,7 +5030,7 @@ export @var{variable} @end example @noindent -@xref{Appending, ,Appending More Text to Variables}. +@xref{Appending Assignment, ,Appending More Text to Variables}. You may notice that the @code{export} and @code{unexport} directives work in @code{make} in the same way they work in the shell, @code{sh}. @@ -5450,58 +5452,41 @@ do this. @chapter How to Use Variables @cindex variable @cindex value -@cindex recursive variable expansion -@cindex simple variable expansion -A @dfn{variable} is a name defined in a makefile to represent a string -of text, called the variable's @dfn{value}. These values are -substituted by explicit request into targets, prerequisites, recipes, -and other parts of the makefile. (In some other versions of @code{make}, +A makefile @dfn{variable} is a name defined to represent a string of text, +called the variable's @dfn{value}. (In some other versions of @code{make}, variables are called @dfn{macros}.) @cindex macro -Variables and functions in all parts of a makefile are expanded when -read, except for in recipes, the right-hand sides of variable -definitions using @samp{=}, and the bodies of variable definitions -using the @code{define} directive. The value a variable expands to is -that of its most recent definition at the time of expansion. In other -words, variables are dynamically scoped. +Variable values can contain lists of file names, options to pass to compilers, +programs to run, directories to look in for source files, directories to write +output in, or anything else you can imagine. -Variables can represent lists of file names, options to pass to compilers, -programs to run, directories to look in for source files, directories to -write output in, or anything else you can imagine. +There are two different ways, called @dfn{flavors}, that a variable can hold +its value internally (@pxref{Flavors, The Two Flavors of Variables}). The +flavor of the variable is specified by the assignment operator used when it is +defined (@pxref{Setting, ,Setting Variables}). -A variable name may be any sequence of characters not containing -@samp{:}, @samp{#}, @samp{=}, or whitespace. However, variable names -containing characters other than letters, numbers, and underscores -should be considered carefully, as in some shells they cannot be -passed through the environment to a sub-@code{make} -(@pxref{Variables/Recursion, ,Communicating Variables to a -Sub-@code{make}}). Variable names beginning with @samp{.} and an -uppercase letter may be given special meaning in future versions of -@code{make}. +When a variable is @dfn{referenced} in targets, prerequisites, recipes, and +other parts of the makefile (@pxref{Reference, ,Basics of Variable +References}), the reference is replaced with the value of the variable. This +is called @dfn{expanding} the variable (@pxref{Expanding, ,How Expansion +Works}). A variable reference is not always expanded immediately as the +makefile is parsed; expansion can be deferred until later depending on the +context. @xref{Reading Makefiles, ,How @code{make} Reads a Makefile}. -Variable names are case-sensitive. The names @samp{foo}, @samp{FOO}, -and @samp{Foo} all refer to different variables. - -It is traditional to use upper case letters in variable names, but we -recommend using lower case letters for variable names that serve internal -purposes in the makefile, and reserving upper case for parameters that -control implicit rules or for parameters that the user should override with -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 Variables}. +When a variable reference is expanded, the value it expands to is that of its +most recent definition at the time of expansion. In other words, variables +in @code{make} are @dfn{dynamically scoped}. @menu +* Variable Naming:: Choosing names for variables. * Reference:: How to use the value of a variable. * Flavors:: Variables come in two flavors. -* Advanced:: Advanced features for referencing a variable. +* Expanding:: How text is expanded by @code{make}. * Values:: All the ways variables get their values. * Setting:: How to set a variable in the makefile. -* Appending:: How to append more text to the old value - of a variable. +* Substitution Refs:: Substituting values in variable expansion. * Override Directive:: How to set a variable in the makefile even if the user has set it with a command argument. * Multi-Line:: An alternate way to set a variable @@ -5517,6 +5502,38 @@ they have particular specialized uses. @xref{Automatic Variables}. * Special Variables:: Variables with special meaning or behavior. @end menu +@node Variable Naming +@section Names of Variables +@cindex names of variables +@cindex variables, names of + +A variable name may be any sequence of characters not containing @samp{:}, +@samp{#}, @samp{=}, or whitespace. + +Variable names are case-sensitive. For instance the names @samp{foo}, +@samp{FOO}, and @samp{Foo} all refer to different variables. + +It is traditional to use upper case letters in variable names, but we +recommend using lower case letters for variable names that serve internal +purposes in the makefile, and reserving upper case for parameters that +control implicit rules or for parameters that the user should override with +command options. @xref{Overriding, ,Overriding Variables}. + +Although GNU Make allows most characters to be part of a variable name, shells +generally only support variable names containing letters, numbers, and +underscores. Consider this when defining variables that need to be exported +to the shell. @xref{Variables/Recursion, ,Communicating Variables to a +Sub-@code{make}}. + +Variable names beginning with @samp{.} followed by uppercase letters are +reserved by the POSIX standard. GNU Make reserves variable names beginning +with @samp{.} and containing uppercase letters and non-alphabetic characters. +These variables may be given special meaning in future versions of GNU Make. + +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 Variables}. + @node Reference @section Basics of Variable References @cindex variables, how to reference @@ -5524,11 +5541,21 @@ they have particular specialized uses. @xref{Automatic Variables}. @cindex @code{$}, in variable reference @cindex dollar sign (@code{$}), in variable reference -To substitute a variable's value, write a dollar sign followed by the name -of the variable in parentheses or braces: either @samp{$(foo)} or -@samp{$@{foo@}} is a valid reference to the variable @code{foo}. This -special significance of @samp{$} is why you must write @samp{$$} to have -the effect of a single dollar sign in a file name or recipe. +To reference a variable's value, write a dollar sign (@samp{$}) followed by +the name of the variable in parentheses or braces: both @code{$(foo)} and +@code{$@{foo@}} are references to the variable @samp{foo}. + +If the variable name consists of a single character then the parenthesis or +braces can be omitted. Thus @code{$A} is a reference to the variable +@samp{A}. We recommend using parenthesis or braces even for single-letter +variable names to avoid confusion (e.g., @code{$foo} refers to the variable +@samp{f} followed by the string @samp{oo} which may not be clear) unless +omitting them gives significant readability improvements. One place where +readability is often improved by omitting parentheses and braces is with +automatic variables (@pxref{Automatic Variables}). + +This special behavior of @samp{$} is why you must write @samp{$$} to have the +effect of a single dollar sign in a makefile. Variable references can be used in any context: targets, prerequisites, recipes, most directives, and new variable values. Here is an @@ -5545,413 +5572,10 @@ $(objects) : defs.h @end group @end example -Variable references work by strict textual substitution. Thus, the rule - -@example -@group -foo = c -prog.o : prog.$(foo) - $(foo)$(foo) -$(foo) prog.$(foo) -@end group -@end example - -@noindent -could be used to compile a C program @file{prog.c}. Since spaces before -the variable value are ignored in variable assignments, the value of -@code{foo} is precisely @samp{c}. (Don't actually write your makefiles -this way!) - -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 can lead to confusion (e.g., -@samp{$foo} refers to the variable @code{f} followed by the string -@code{oo}) so we recommend using parentheses or braces around all -variables, even single-letter variables, unless omitting them gives -significant readability improvements. One place where readability is -often improved is automatic variables (@pxref{Automatic Variables}). - -@node Flavors -@section The Two Flavors of Variables -@cindex flavors of variables -@cindex recursive variable expansion -@cindex variables, flavors -@cindex recursively expanded variables -@cindex variables, recursively expanded - -There are different ways that a variable in GNU @code{make} can get a value; -we call them the @dfn{flavors} of variables. The flavors are distinguished in -how they handle the values they are assigned in the makefile, and in how those -values are managed when the variable is later used and expanded. - @menu -* Recursive Assignment:: Setting recursively expanded variables. -* Simple Assignment:: Setting simply expanded variables. -* Immediate Assignment:: Setting immediately expanded variables. -* Conditional Assignment:: Assigning variable values conditionally. +* Computed Names:: Computing the name of a variable reference. @end menu -@node Recursive Assignment -@subsection Recursively Expanded Variable Assignment -@cindex = -The first flavor of variable is a @dfn{recursively expanded} variable. -Variables of this sort are defined by lines using @samp{=} -(@pxref{Setting, ,Setting Variables}) or by the @code{define} directive -(@pxref{Multi-Line, ,Defining Multi-Line Variables}). The value you specify -is installed verbatim; if it contains references to other variables, -these references are expanded whenever this variable is substituted (in -the course of expanding some other string). When this happens, it is -called @dfn{recursive expansion}. - -For example, - -@example -foo = $(bar) -bar = $(ugh) -ugh = Huh? - -all:;echo $(foo) -@end example - -@noindent -will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which -expands to @samp{$(ugh)} which finally expands to @samp{Huh?}. - -This flavor of variable is the only sort supported by most other -versions of @code{make}. It has its advantages and its disadvantages. -An advantage (most would say) is that: - -@example -CFLAGS = $(include_dirs) -O -include_dirs = -Ifoo -Ibar -@end example - -@noindent -will do what was intended: when @samp{CFLAGS} is expanded in a recipe, -it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you -cannot append something on the end of a variable, as in - -@example -CFLAGS = $(CFLAGS) -O -@end example - -@noindent -because it will cause an infinite loop in the variable expansion. -(Actually @code{make} detects the infinite loop and reports an error.) -@cindex loops in variable expansion -@cindex variables, loops in expansion - -Another disadvantage is that any functions -(@pxref{Functions, ,Functions for Transforming Text}) -referenced in the definition will be executed every time the variable is -expanded. This makes @code{make} run slower; worse, it causes the -@code{wildcard} and @code{shell} functions to give unpredictable results -because you cannot easily control when they are called, or even how many -times. - -@node Simple Assignment -@subsection Simply Expanded Variable Assignment -To avoid the problems and inconveniences of recursively expanded -variables, there is another flavor: simply expanded variables. - -@cindex simply expanded variables -@cindex variables, simply expanded -@cindex := -@cindex ::= -@dfn{Simply expanded variables} are defined by lines using @samp{:=} -or @samp{::=} (@pxref{Setting, ,Setting Variables}). Both forms are -equivalent in GNU @code{make}; however only the @samp{::=} form is -described by the POSIX standard (support for @samp{::=} is added to -the POSIX standard for POSIX Issue 8). - -The value of a simply expanded variable is scanned once, expanding any -references to other variables and functions, when the variable is -defined. Once that expansion is complete the value of the variable is -never expanded again: when the variable is used the value is copied -verbatim as the expansion. If the value contained variable references -the result of the expansion will contain their values @emph{as of the -time this variable was defined}. Therefore, - -@example -@group -x := foo -y := $(x) bar -x := later -@end group -@end example - -@noindent -is equivalent to - -@example -@group -y := foo bar -x := later -@end group -@end example - -Here is a somewhat more complicated example, illustrating the use of -@samp{:=} in conjunction with the @code{shell} function. -(@xref{Shell Function, , The @code{shell} Function}.) This example -also shows use of the variable @code{MAKELEVEL}, which is changed -when it is passed down from level to level. -(@xref{Variables/Recursion, , Communicating Variables to a -Sub-@code{make}}, for information about @code{MAKELEVEL}.) - -@example -@group -ifeq (0,$@{MAKELEVEL@}) -whoami := $(shell whoami) -host-type := $(shell arch) -MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@} -endif -@end group -@end example - -@noindent -An advantage of this use of @samp{:=} is that a typical -`descend into a directory' recipe then looks like this: - -@example -@group -$@{subdirs@}: - $@{MAKE@} -C $@@ all -@end group -@end example - -Simply expanded variables generally make complicated makefile programming -more predictable because they work like variables in most programming -languages. They allow you to redefine a variable using its own value (or -its value processed in some way by one of the expansion functions) and to -use the expansion functions much more efficiently -(@pxref{Functions, ,Functions for Transforming Text}). - -@cindex spaces, in variable values -@cindex whitespace, in variable values -@cindex variables, spaces in values -You can also use them to introduce controlled leading whitespace into -variable values. Leading whitespace characters are discarded from your -input before substitution of variable references and function calls; -this means you can include leading spaces in a variable value by -protecting them with variable references, like this: - -@example -@group -nullstring := -space := $(nullstring) # end of the line -@end group -@end example - -@noindent -Here the value of the variable @code{space} is precisely one space. The -comment @w{@samp{# end of the line}} is included here just for clarity. -Since trailing space characters are @emph{not} stripped from variable -values, just a space at the end of the line would have the same effect -(but be rather hard to read). If you put whitespace at the end of a -variable value, it is a good idea to put a comment like that at the end -of the line to make your intent clear. Conversely, if you do @emph{not} -want any whitespace characters at the end of your variable value, you -must remember not to put a random comment on the end of the line after -some whitespace, such as this: - -@example -dir := /foo/bar # directory to put the frobs in -@end example - -@noindent -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!) - -@node Immediate Assignment -@subsection Immediately Expanded Variable Assignment -@cindex immediate variable assignment -@cindex variables, immediate assignment -@cindex :::= - -Another form of assignment allows for immediate expansion, but unlike simple -assignment the resulting variable is recursive: it will be re-expanded again -on every use. In order to avoid unexpected results, after the value is -immediately expanded it will automatically be quoted: all instances of -@code{$} in the value after expansion will be converted into @code{$$}. This -type of assignment uses the @samp{:::=} operator. For example, - -@example -@group -var = first -OUT :::= $(var) -var = second -@end group -@end example - -@noindent -results in the @code{OUT} variable containing the text @samp{first}, while here: - -@example -@group -var = one$$two -OUT :::= $(var) -var = three$$four -@end group -@end example - -@noindent -results in the @code{OUT} variable containing the text @samp{one$$two}. The -value is expanded when the variable is assigned, so the result is the -expansion of the first value of @code{var}, @samp{one$two}; then the value is -re-escaped before the assignment is complete giving the final result of -@samp{one$$two}. - -The variable @code{OUT} is thereafter considered a recursive variable, so it -will be re-expanded when it is used. - -This seems functionally equivalent to the @samp{:=} / @samp{::=} operators, -but there are a few differences: - -First, after assignment the variable is a normal recursive variable; when you -append to it with @samp{+=} the value on the right-hand side is not expanded -immediately. If you prefer the @samp{+=} operator to expand the right-hand -side immediately you should use the @samp{:=} / @samp{::=} assignment instead. - -Second, these variables are slightly less efficient than simply expanded -variables since they do need to be re-expanded when they are used, rather than -merely copied. However since all variable references are escaped this -expansion simply un-escapes the value, it won't expand any variables or run -any functions. - -Here is another example: - -@example -@group -var = one$$two -OUT :::= $(var) -OUT += $(var) -var = three$$four -@end group -@end example - -After this, the value of @code{OUT} is the text @samp{one$$two $(var)}. When -this variable is used it will be expanded and the result will be -@samp{one$two three$four}. - -This style of assignment is equivalent to the traditional BSD @code{make} -@samp{:=} operator; as you can see it works slightly differently than the GNU -@code{make} @samp{:=} operator. The @code{:::=} operator is added to the -POSIX specification in Issue 8 to provide portability. - -@node Conditional Assignment -@subsection Conditional Variable Assignment -@cindex conditional variable assignment -@cindex variables, conditional assignment -@cindex ?= -@cindex ?:= -@cindex ?::= -@cindex ?:::= -@cindex ?!= - -Any assignment operator can be prefixed with a conditional operator, @samp{?}. -If this modifier is provided then the assignment will proceed normally, but -@emph{only if} the variable is not already defined. - -If the variable is already defined, the assignment is ignored and the -right-hand side (value) of the assignment is not processed. - -For example 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 - -More generally a statement of the form: - -@example -NAME ? VALUE -@end example - -will do nothing if the variable @samp{NAME} is defined, and will perform the -operation @code{NAME VALUE} for any assignment operation @samp{} if -@samp{NAME} is not defined. - -Note that a variable set to an empty value is still defined, so assignments -modified with @samp{?} will not set that variable. - -@node Advanced -@section Advanced Features for Reference to Variables -@cindex reference to variables - -This section describes some advanced features you can use to reference -variables in more flexible ways. - -@menu -* Substitution Refs:: Referencing a variable with - substitutions on the value. -* Computed Names:: Computing the name of the variable to refer to. -@end menu - -@node Substitution Refs -@subsection Substitution References -@cindex modified variable reference -@cindex substitution variable reference -@cindex variables, modified reference -@cindex variables, substitution reference - -@cindex variables, substituting suffix in -@cindex suffix, substituting in variables -A @dfn{substitution reference} substitutes the value of a variable with -alterations that you specify. It has the form -@samp{$(@var{var}:@var{a}=@var{b})} (or -@samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value -of the variable @var{var}, replace every @var{a} at the end of a word with -@var{b} in that value, and substitute the resulting string. - -When we say ``at the end of a word'', we mean that @var{a} must appear -either followed by whitespace or at the end of the value in order to be -replaced; other occurrences of @var{a} in the value are unaltered. For -example: - -@example -foo := a.o b.o l.a c.o -bar := $(foo:.o=.c) -@end example - -@noindent -sets @samp{bar} to @samp{a.c b.c l.a c.c}. @xref{Setting, ,Setting Variables}. - -A substitution reference is shorthand for the @code{patsubst} -expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}): -@samp{$(@var{var}:@var{a}=@var{b})} is equivalent to -@samp{$(patsubst %@var{a},%@var{b},@var{var})}. We provide -substitution references as well as @code{patsubst} for compatibility -with other implementations of @code{make}. - -Another type of substitution reference lets you use the full power of -the @code{patsubst} function. It has the same form -@samp{$(@var{var}:@var{a}=@var{b})} described above, except that now -@var{a} must contain a single @samp{%} character. This case is -equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}. -@xref{Text Functions, ,Functions for String Substitution and Analysis}, -for a description of the @code{patsubst} function. For example: - -@example -@group -foo := a.o b.o l.a c.o -bar := $(foo:%.o=%.c) -@end group -@end example - -@noindent -sets @samp{bar} to @samp{a.c b.c l.a c.c}. - @node Computed Names @subsection Computed Variable Names @cindex nested variable reference @@ -5962,13 +5586,11 @@ sets @samp{bar} to @samp{a.c b.c l.a c.c}. @cindex @code{$}, in variable name @cindex dollar sign (@code{$}), in variable name -Computed variable names are an advanced concept, very useful in more -sophisticated makefile programming. In simple situations you need not -consider them, but they can be extremely useful. - -Variables may be referenced inside the name of a variable. This is -called a @dfn{computed variable name} or a @dfn{nested variable -reference}. For example, +Most of the time static variable names are sufficient, but in more complex +situations it can be extremely useful to dynamically construct variable names. +This can be achieved by using a variable reference inside a reference to a +variable. This is referred to as a @dfn{computed variable name} or a +@dfn{nested variable reference}. For example, @example x = y @@ -5977,14 +5599,14 @@ a := $($(x)) @end example @noindent -defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands -to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands -to @samp{z}. Here the name of the variable to reference is not stated -explicitly; it is computed by expansion of @samp{$(x)}. The reference -@samp{$(x)} here is nested within the outer variable reference. +defines the variable @samp{a} to have the value @code{z}, in this way: +@code{make} first expands @code{$(x)} to the value @code{y}, which means +@code{$($(x))} expands to @code{$(y)}, and @code{$(y)} expands to the string +@code{z}. Thus the name of the variable to reference is not stated +explicitly; it is computed by expansion of @samp{$(x)}. The previous example shows two levels of nesting, but any number of levels -is possible. For example, here are three levels: +are possible. For example, here are three levels: @example x = y @@ -5994,9 +5616,9 @@ a := $($($(x))) @end example @noindent -Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))} -expands to @samp{$(y)} which in turn expands to @samp{z}; now we have -@samp{$(z)}, which becomes @samp{u}. +Here the innermost @code{$(x)} expands to @samp{y}, so @code{$($(x))} +expands to @code{$(y)} which in turn expands to @samp{z}; now we have +@code{$(z)}, which expands to @samp{u}. References to recursively-expanded variables within a variable name are re-expanded in the usual fashion. For example: @@ -6009,8 +5631,8 @@ a := $($(x)) @end example @noindent -defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))} -which becomes @samp{$(z)} which becomes @samp{Hello}. +defines @samp{a} as @code{Hello}: @code{$($(x))} becomes @code{$($(y))} +which becomes @code{$(z)} which becomes @samp{Hello}. Nested variable references can also contain modified references and function invocations (@pxref{Functions, ,Functions for Transforming Text}), just like @@ -6030,10 +5652,10 @@ a := $($($(z))) @noindent eventually defines @code{a} as @samp{Hello}. It is doubtful that anyone would ever want to write a nested reference as convoluted as this one, but -it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes -@samp{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from -@code{x} and changes it by substitution to @samp{variable2}, so that the -entire string becomes @samp{$(variable2)}, a simple variable reference +it works: @code{$($($(z)))} expands to @code{$($(y))} which becomes +@code{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from +@samp{x} and changes it by substitution to @samp{variable2}, so that the +entire string becomes @code{$(variable2)}, a simple variable reference whose value is @samp{Hello}. A computed variable name need not consist entirely of a single variable @@ -6071,9 +5693,9 @@ dirs := $($(a1)_$(df)) @end example @noindent -will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs}, -@code{a_files} or @code{1_files} depending on the settings of @code{use_a} -and @code{use_dirs}. +will give @samp{dirs} the same value as @samp{a_dirs}, @samp{1_dirs}, +@samp{a_files} or @samp{1_files} depending on the settings of @samp{use_a} +and @samp{use_dirs}. Computed variable names can also be used in substitution references: @@ -6087,13 +5709,13 @@ sources := $($(a1)_objects:.o=.c) @end example @noindent -defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c}, -depending on the value of @code{a1}. +defines @samp{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c}, +depending on the value of @samp{a1}. -The only restriction on this sort of use of nested variable references -is that they cannot specify part of the name of a function to be called. -This is because the test for a recognized function name is done before -the expansion of nested references. For example, +The only restriction on this sort of use of nested variable references is that +they cannot specify part of the name of a function to be called. This is +because the test for a recognized function name is done before the expansion +of nested references. For example, @example @group @@ -6114,14 +5736,14 @@ foo := $($(func) $(bar)) @end example @noindent -attempts to give @samp{foo} the value of the variable @samp{sort a d b g -q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c} -as the argument to either the @code{sort} or the @code{strip} function. -This restriction could be removed in the future if that change is shown -to be a good idea. +attempts to give @samp{foo} the value of the variable @samp{sort a d b g q c} +or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c} as the +argument to either the @samp{sort} or the @samp{strip} function. This +restriction could be removed in the future if that change is shown to be a +good idea. -You can also use computed variable names in the left-hand side of a -variable assignment, or in a @code{define} directive, as in: +You can also use computed variable names in the left-hand side of a variable +assignment, or in a @samp{define} directive, as in: @example dir = foo @@ -6140,6 +5762,198 @@ Note that @dfn{nested variable references} are quite different from (@pxref{Flavors, ,The Two Flavors of Variables}), though both are used together in complex ways when doing makefile programming. +@node Flavors +@section The Two Flavors of Variables +@cindex flavors of variables +@cindex variables, flavors + +There are two different ways that a variable in GNU Make can behave when a +reference is expanded; we call them the @dfn{flavors} of variables. + +The assignment operator used to set the variable's value (@pxref{Setting, , +Setting Variables}) determines both the way in which the value is handled +during assignment, and also the flavor of the variable's value after +assignment. Although there are a number of different assignment operators, +all variables will end up as one of the two flavors. + +@menu +* Recursive Variables:: Recursive variables delay expansion. +* Simple Variables:: Simple variables expand immediately. +@end menu + +@node Recursive Variables +@subsection Recursively Expanded Variable Assignment +@cindex recursive variable expansion +@cindex recursively expanded variables +@cindex variables, recursively expanded + +The first flavor of variable is a @dfn{recursively expanded} variable. This +is the standard type of variable supported by all versions of @code{make} and +defined by POSIX. + +When a recursively expanded variable is expanded due to a variable reference, +the value of the variable is also expanded. This is called @dfn{recursive +expansion}. + +Consider this makefile: + +@example +foo = $(bar) +bar = $(ugh) +ugh = Huh? + +all: ; @@echo $(foo) +@end example + +After @code{make} parses this makefile the value of the variable @code{foo} +will be the string @samp{$(bar)}, the value of the variable @code{bar} will be +the string @samp{$(ugh)}, and the value of the variable @code{ugh} will be the +string @samp{Huh?}. + +If you run @code{make} with this makefile, it will print @samp{Huh?}: the +variable reference @samp{$(foo)} expands to @samp{$(bar)} which expands to +@samp{$(ugh)} which finally expands to @samp{Huh?}. + +The big advantage of this flavor of variable is that it can refer to variables +which have not been defined yet. This means: + +@example +CFLAGS = $(include_dirs) -O +include_dirs = -Ifoo -Ibar +@end example + +@noindent +will do what was intended, even though when @code{CFLAGS} was set the variable +@samp{include_dirs} was not set yet: when @code{CFLAGS} is expanded in a +recipe it will expand to the value of @code{include_dirs} at that time, +yielding @samp{-Ifoo -Ibar -O}. + +This flavor also allows variables to contain references to automatic variables +(@pxref{Automatic Variables}); since automatic variables are not set until a +recipe is going to be run it would not work if the variable's value was +expanded when the variable was assigned. + +There are also a number of disadvantages. The first one is that programmers +are not used to this type of assignment and may be confused. In a makefile +like this: + +@example +@group +CFLAGS = -g +DEBUG_FLAGS = $(CFLAGS) + +CFLAGS = -O2 +OPT_FLAGS = $(CFLAGS) +@end group +@end example + +@noindent +when @code{DEBUG_FLAGS} and @code{OPT_FLAGS} are expanded later they will +@emph{both} contain the value @samp{-O2}; each assignment to @code{CFLAGS} +overwrites the previous assignment and whatever the last value was, will be +seen when references to @samp{$(CFLAGS)} are expanded. + +Another disadvantage is that you cannot reference a variable in its own value; +for instance this: +@cindex loops in variable expansion +@cindex variables, loops in expansion + +@example +CFLAGS = $(CFLAGS) -O +@end example + +@noindent +will generate an error due to an infinite loop in the variable expansion. If +you want to append to the end of the variable you can use the @samp{+=} +assignment operator (@pxref{Appending Assignment, , Appending More Text to +Variables}) to deal with this. The fact that a ``recursively expanded'' +variable cannot contain a recursive reference to itself is one of those +idiosyncratic proofs that naming is hard in computer science. + +A third disadvantage is that the value will be re-expanded every time the +variable is referenced. If the expansion of that variable is expensive--for +example if it contains functions (@pxref{Functions, ,Functions for +Transforming Text}) which are expensive to execute--this can impact the +performance of @code{make}. It may also cause functions like @code{wildcard} +and @code{shell} to give unpredictable results since you cannot easily control +when they are called, or how many times. + +@node Simple Variables +@subsection Simply Expanded Variable Assignment +To avoid the problems and inconveniences of recursively expanded variables, +GNU Make provides another flavor of variable value: @dfn{simply expanded +variables}. + +The value of a simply expanded variable is expanded only once, immediately +when the variable is assigned in the makefile. All references to variables +and functions in its value are resolved at the time the variable is assigned. +When the variable is later expanded it is not re-expanded (thus it is not +``recursive''): the stored value is used verbatim as the result of the +expansion. + +If we write the example from the previous section using simply expanded +variables (note the use of @samp{:=} for assignment), we will get more +traditional behavior: + +@example +@group +CFLAGS = -g +DEBUG_FLAGS := $(CFLAGS) + +CFLAGS = -O2 +OPT_FLAGS := $(CFLAGS) +@end group +@end example + +Now the value of @code{DEBUG_FLAGS} will be @samp{-g} while the value of +@code{OPT_FLAGS} is @samp{-O2} as expected. + +Simply expanded variables simplify makefile programming because they work like +variables in most other programming languages. They allow you to redefine a +variable using its own value. And they make the use of functions more +efficient since they are expanded only one time, not each time the variable is +referenced. + +@node Expanding +@section How Expansion Works +@cindex expanding variables +@cindex variables, expanding + +The process of @dfn{expanding} a string in @code{make} means, to replace each +variable reference (@pxref{Reference, ,Basics of Variable References}) with +the value of that variable. All text which is not part of a variable +reference is preserved in the result. + +Expansion proceeds from @emph{right to left} and from @emph{inside out}. For +example, given the following text: + +@example +save the $(shell $(date)) for $(event) +@end example + +@noindent +the expansion would keep the static string @samp{save the } (starting from +right to left), then expand the variable named @code{date} (going from inside +out) and use the result as the argument to the GNU Make function @code{shell} +(@pxref{Shell Function, ,The @code{shell} Function}). The output of that +shell command is appended into the result of the expansion. Then the static +string @samp{ for } is added, and finally the expansion of the variable +@code{event}. + +The expansion of a variable that has not been defined is not an error: instead +it silently expands to an empty string. This behavior is required by POSIX; +however it can be controlled in GNU Make (@pxref{Warnings, ,Makefile +Warnings}). + +Although expansion always proceeds in the same way, deciding @emph{when} text +is expanded depends on the context in which it's used: often text is expanded +as the makefile is parsed. In other situations the expansion is delayed (for +example the text of a recipe is not expanded until the recipe is invoked). +@xref{Reading Makefiles, ,How @code{make} Reads a Makefile}. + +Also, deciding how to interpret the value of a variable during expansion +depends on the type of variable. @xref{Flavors, ,The Two Flavors of Variables}. + @node Values @section How Variables Get Their Values @cindex variables, how they get their values @@ -6149,13 +5963,13 @@ Variables can get values in several different ways: @itemize @bullet @item -You can specify an overriding value when you run @code{make}. -@xref{Overriding, ,Overriding Variables}. +You can specify an overriding value on the command line when you run +@code{make}. @xref{Overriding, ,Overriding Variables}. @item -You can specify a value in the makefile, either -with an assignment (@pxref{Setting, ,Setting Variables}) or with a -verbatim definition (@pxref{Multi-Line, ,Defining Multi-Line Variables}). +You can specify a value in the makefile, either with an assignment +(@pxref{Setting, ,Setting Variables}) or with a verbatim definition +(@pxref{Multi-Line, ,Defining Multi-Line Variables}). @item You can specify a short-lived value with the @code{let} function @@ -6163,16 +5977,16 @@ You can specify a short-lived value with the @code{let} function (@pxref{Foreach Function}). @item -Variables in the environment become @code{make} variables. -@xref{Environment, ,Variables from the Environment}. +Variables and their values in the environment when @code{make} is invoked are +imported as @code{make} variables. @xref{Environment, ,Variables from the +Environment}. @item -Several @dfn{automatic} variables are given new values for each rule. -Each of these has a single conventional use. -@xref{Automatic Variables}. +Several variables are given new values for each rule that @code{make} invokes, +before the recipe for that rule is expanded. @xref{Automatic Variables}. @item -Several variables have constant initial values. +Several variables have default initial values. @xref{Implicit Variables, ,Variables Used by Implicit Rules}. @end itemize @@ -6183,13 +5997,13 @@ Several variables have constant initial values. @cindex = @cindex := @cindex ::= -@cindex :::= -@cindex != -To set a variable from the makefile, write a line starting with the variable -name followed by one of the assignment operators @samp{=}, @samp{:=}, -@samp{::=}, or @samp{:::=}. Whatever follows the operator and any initial -whitespace on the line becomes the value. For example, +A makefile variable is set by writing a line starting with the variable name +followed by one of the assignment operators @code{=}, @code{:=}, @code{::=}, +@code{:::=}, or @code{!=}. Whitespace can optionally come before the variable +name, between the variable name and the operator, and after the operator but +before the value, and is discarded. Whatever text follows becomes the value +of the variable. For example: @example objects = main.o foo.o bar.o utils.o @@ -6197,51 +6011,182 @@ objects = main.o foo.o bar.o utils.o @noindent defines a variable named @code{objects} to contain the value @samp{main.o -foo.o bar.o utils.o}. Whitespace around the variable name and immediately -after the @samp{=} is ignored. +foo.o bar.o utils.o}. The whitespace before and after the assignment operator +is ignored. -Variables defined with @samp{=} are @dfn{recursively expanded} variables. -Variables defined with @samp{:=} or @samp{::=} are @dfn{simply expanded} -variables; these definitions can contain variable references which will be -expanded before the definition is made. Variables defined with @samp{:::=} -are @dfn{immediately expanded} variables. The different assignment operators -are described in @xref{Flavors, ,The Two Flavors of Variables}. +If there is ambiguity between the end of the variable name and the start of +the assignment operator (@pxref{Setting, ,Setting Variables}), GNU Make always +prefers the operator. For example: -The variable name may contain function and variable references, which -are expanded when the line is read to find the actual variable name to use. +@example +FOO?=bar +@end example -There is no limit on the length of the value of a variable except the -amount of memory on the computer. You can split the value of a -variable into multiple physical lines for readability +@noindent +will always be parsed into the tokens @samp{FOO}, @samp{?=}, and @samp{bar}. +On the other hand, this: + +@example +FOO? = bar +@end example + +@noindent +will be parsed as @samp{FOO?}, @samp{=}, and @samp{bar}. For this reason, +among others, it's a best practice to always add whitespace around operators +when setting @code{make} variables. + +There is no limit on the length of the value of a variable, except the amount +of memory on the computer. You can split the value of a variable into +multiple physical lines, for readability, by adding backslashes (@pxref{Splitting Lines, ,Splitting Long Lines}). -Most variable names are considered to have the empty string as a value if you -have never set them. Several variables have built-in initial values 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 while running the recipe for a rule; these are -called the @dfn{automatic} variables (@pxref{Automatic Variables}). +The assignment operator controls two things: first, how the value (the +string after the operator) is handled when the variable is set, and second how +the value is handled when the variable is expanded (i.e., its flavor: +@pxref{Flavors, The Two Flavors of Variables}). -The shell assignment operator @samp{!=} can be used to execute a -shell script and set a variable to its output. This operator first -evaluates the right-hand side, then passes that result to the shell -for execution. If the result of the execution ends in a newline, that -one newline is removed; all other newlines are replaced by spaces. -The resulting string is then placed into the named -recursively-expanded variable. For example: +The @samp{=} operator creates a @emph{recursively expanded} variable. The +value of the variable @emph{is not} expanded when the variable is defined: the +right hand side of the assignment operator is used verbatim as the value of +the variable. + +The @samp{:=} and @samp{::=} operators create a @emph{simply expanded} +variable. The value of the variable @emph{is} expanded when the variable is +defined. These operators are interchangeable: @samp{:=} is specific to GNU +Make while @samp{::=} has the same behavior and is specified by POSIX. + +The @samp{:::=} operator creates a @emph{recursively expanded} variable, like +@samp{=}. The value of the variable @emph{is} expanded when the variable is +defined, like @samp{:=} / @samp{::=}. After the expansion, the resulting +value is @emph{escaped} by substituting each dollar sign in the value with two +dollar signs (@samp{$$}). @xref{Immediate Assignment, ,Immediately Expanded +Variable Assignment}. + +The shell assignment operator @samp{!=} creates a @emph{recursively expanded} +variable. The value of the variable is obtained by passing the expanded +right-hand side to the shell as a command, and collecting its output. +@xref{Shell Assignment, Shell Variable Assignment}. + +Each of these assignment operators can also be prefixed with a question mark +(@samp{?}) to make them @dfn{conditional}. The right-hand side is only +considered if the variable is not yet set. If it is set, the value of the +assignment is ignored. @xref{Conditional Assignment, ,Conditional Variable +Assignment}. + +Finally, more text can be added to an already-set variable value using the +appending assignment operator @samp{+=}. @xref{Appending Assignment, +,Appending More Text to Variables}. + +@menu +* Immediate Assignment:: Recursive variables with immediate expansion. +* Shell Assignment:: Assigning variables to shell output. +* Conditional Assignment:: Assigning variables only if not yet defined. +* Appending Assignment:: How to append to the value of a variable. +* Whitespace in Values:: Leading and trailing whitespace in values. +@end menu + +@node Immediate Assignment +@subsection Immediately Expanded Variable Assignment +@cindex immediate variable assignment +@cindex variables, immediate assignment +@cindex :::= + +The @samp{:::=} assignment operator allows for immediate expansion, but unlike +simple assignment the resulting variable is recursive and will be re-expanded +again on every use. In order to avoid unexpected results, after the value is +immediately expanded it will automatically be quoted: all instances of +@samp{$} in the value after expansion will be converted into @samp{$$}. This +type of assignment uses the @samp{:::=} operator. For example, + +@example +@group +var = first +OUT :::= $(var) +var = second +@end group +@end example + +@noindent +results in the @code{OUT} variable containing the text @samp{first}, while here: + +@example +@group +var = one$$two +OUT :::= $(var) +var = three +@end group +@end example + +@noindent +results in the @code{OUT} variable containing the text @samp{one$$two}. The +value is expanded when the variable is assigned, so the result is the +expansion of the first value of @code{var}, @samp{one$two}; then the value is +re-escaped before the assignment is complete giving the final result of +@samp{one$$two}. + +This is generally equivalent to the GNU Make @samp{:=} / @samp{::=} assignment +operators, but there are a few differences: + +First, since the variable is a recursive variable when appending to it with +the @samp{+=} operator the value on the right-hand side is not expanded +immediately as it would be using @samp{:=} / @samp{::=}. + +Second, expansion of these variables is slightly less efficient since they +will be re-expanded when they are referenced. However since all dollar signs +are escaped the expansion simply un-escapes the value, it won't expand any +variables or run any functions. + +Here is another example: + +@example +@group +var = one$$two +OUT :::= $(var) +OUT += $(var) +var = three$$four +@end group +@end example + +After this, the value of @code{OUT} is the text @samp{one$$two $(var)}. When +this variable is used it will be expanded and the result will be +@samp{one$two three$four}. + +This style of assignment is equivalent to the traditional BSD @code{make} +@samp{:=} assignment operator, and different from GNU Make's @samp{:=} +assignment operator. The @samp{:::=} assignment operator was added to POSIX +to provide portability. + +@node Shell Assignment +@subsection Shell Variable Assignment +@cindex shell variable assignment +@cindex variables, shell assignment +@cindex != + +The shell assignment operator @samp{!=} creates a @emph{recursively expanded} +variable. The value of the variable is computed by first expanding the +right-hand side of the assignment then invoking a shell and passing the +expanded value to the shell as a script to run. The output generated by the +shell (to standard out) is used as the value of the variable. + +If the last character of output is a newline, that character is removed; all +other newlines are replaced by spaces. For example: @example hash != printf '\043' file_list != find . -name '*.c' @end example -If the result of the execution could produce a @code{$}, and you don't -intend what follows that to be interpreted as a make variable or -function reference, then you must replace every @code{$} with -@code{$$} as part of the execution. Alternatively, you can set a -simply expanded variable to the result of running a program using the -@code{shell} function call. @xref{Shell Function, , The @code{shell} -Function}. For example: +Because the variable is recursively expanded you must take care to ensure +that, if the shell script outputs dollar signs which you don't want to be +expanded by @code{make} when the variable is expanded, you escape them with +two dollar signs. + +The @samp{!=} operator is portable to some other versions of @code{make} and +is defined in the latest POSIX specifications. + +Alternatively, you can set a simply expanded variable to the result of running +a program using the @code{shell} function call. @xref{Shell Function, , The +@code{shell} Function}. For example: @example hash := $(shell printf '\043') @@ -6249,60 +6194,58 @@ var := $(shell find . -name "*.c") @end example As with the @code{shell} function, the exit status of the just-invoked -shell script is stored in the @code{.SHELLSTATUS} variable. +shell script is stored in the @code{.SHELLSTATUS} variable when assigning with +@samp{!=}. -@node Conditionalizing -@section Conditionally Assigning to Variables +@node Conditional Assignment +@subsection Conditional Variable Assignment +@cindex conditional variable assignment +@cindex variables, conditional assignment @cindex ?= @cindex ?:= @cindex ?::= @cindex ?:::= @cindex ?!= -Sometimes you want to set a variable but only if it's not already defined. -One way to do this is to test using the @code{origin} function (@pxref{Origin -Function}), like this: +Any non-appending assignment operator (@samp{=}, @samp{:=}, @samp{::=}, +@samp{:::=}, @samp{!=}) can be prefixed with a conditional modifier, @samp{?}. +When this modifier is used, the assignment will proceed normally according to +the base assignment operator, @emph{only if} the variable is not already +defined. + +If the variable is already defined, the assignment is ignored and the +right-hand side (value) of the assignment is not processed. + +For example this statement: @example -ifeq ($(origin FOO), undefined) - FOO = value -endif -@end example - -However this is a lot to type, and read, and so GNU Make provides a way to -conditionally assign variables, only if they are not already defined. - -To do this, prepend the conditional modifier @samp{?} to the assignment -operator. In this form @code{make} will first check to see if the variable is -defined; only if it is not will it proceed to execute the assignment (using -whichever operator you specified). - -Instead of the above example, you get identical behavior by writing: - -@example -FOO ?= value -@end example - -And of course, you can also use: - -@example -FOO ?:= value +FOO ?= bar @end example @noindent -rather than writing: +is equivalent to this (@pxref{Origin Function, ,The @code{origin} Function}): @example ifeq ($(origin FOO), undefined) - FOO := value + FOO = bar endif @end example -The other assignment operators @samp{::=}, @samp{:::=}, and @samp{!=} can also -be used. +More generally a statement of the form: -@node Appending -@section Appending More Text to Variables +@example +NAME ? VALUE +@end example + +will do nothing if the variable @code{NAME} is defined, and will perform the +operation @samp{NAME VALUE} for any assignment operation @samp{} if +@code{NAME} is not defined. + +Note that a variable set to an empty value is still considered to be defined, +so assignments modified with @samp{?} will not set that variable. + +@node Appending Assignment +@subsection Appending More Text to Variables @cindex += @cindex appending to variables @cindex variables, appending to @@ -6426,6 +6369,133 @@ the reference to @code{includes}, so if that variable gets defined at any later point, a reference like @samp{$(CFLAGS)} still uses its value. +@node Whitespace in Values +@subsection Whitespace in Variable Values +@cindex spaces, in variable values +@cindex whitespace, in variable values +@cindex variables, spaces in values + +As described above, leading whitespace (whitespace between the assignment +operator and the first non-whitespace character of the value) is discarded. +All whitespace after this is preserved, @emph{including} trailing spaces. + +Unwanted trailing whitespace can cause your makefile to behave in unexpected +ways: consider a variable reference such as @samp{$(dir)/file.c} if the +variable @samp{dir} had an unexpected trailing space in its value. If your +text editor has settings to automatically strip all trailing spaces from files +when they are saved, or to make trailing whitespace visible somehow, it's a +good idea to enable these facilities for makefiles. + +You may occasionally need to define a variable value that begins with +whitespace. To force whitespace at the beginning of a value you can use a +variable reference that expands to the empty string. For example: + +@example +@group +emptystring := +space := $(emptystring) $(emptystring) +@end group +@end example + +The space between the assignment operator and the variable reference +@samp{$(emptystring)} will be discarded, then the rest of the string is +expanded. The @samp{emptystring} variables expand to no text, leaving just +the space as the value. + +The second reference to @samp{$(emptystring)} is used to avoid having the +trailing space stripped by editors and to make the intent simpler to +understand. You don't have to use a second variable reference; you could also +use a comment such as: + +@example +@group +emptystring := +space := $(emptystring) #<-one space +@end group +@end example + +@noindent +to achieve the same effect. + +Conversely, if you do @emph{not} want any whitespace at the end of the +variable value you must not put whitespace plus a comment on the end of the +variable value, such as this: + +@example +dir := /foo/bar # directory to put the frobs in +@end example + +@noindent +Here the value of the variable @code{dir} is @w{@samp{/foo/bar }} (with +four trailing spaces), which was probably not the intention. For this reason +adding comments to the end of variable assignment lines is discouraged in +makefiles, and using preceding comment lines is preferred; for example: + +@example +@group +# directory to put the frobs in +dir := /foo/bar +@end group +@end example + +Another option is to make extensive use of the @code{strip} function +(@pxref{Text Functions}) to ensure variable expansions have no leading or +trailing whitespace. + +@node Substitution Refs +@section Substitution References +@cindex modified variable reference +@cindex substitution variable reference +@cindex variables, modified reference +@cindex variables, substitution reference + +@cindex variables, substituting suffix in +@cindex suffix, substituting in variables +A @dfn{substitution reference} substitutes the value of a variable with +alterations that you specify. It has the form +@samp{$(@var{var}:@var{a}=@var{b})} (or +@samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value +of the variable @var{var}, replace every @var{a} at the end of a word with +@var{b} in that value, and substitute the resulting string. + +When we say ``at the end of a word'', we mean that @var{a} must appear +either followed by whitespace or at the end of the value in order to be +replaced; other occurrences of @var{a} in the value are unaltered. For +example: + +@example +foo := a.o b.o l.a c.o +bar := $(foo:.o=.c) +@end example + +@noindent +sets @samp{bar} to @samp{a.c b.c l.a c.c}. @xref{Setting, ,Setting Variables}. + +A substitution reference is shorthand for the @code{patsubst} +expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}): +@samp{$(@var{var}:@var{a}=@var{b})} is equivalent to +@samp{$(patsubst %@var{a},%@var{b},@var{var})}. We provide +substitution references as well as @code{patsubst} for compatibility +with other implementations of @code{make}. + +Another type of substitution reference lets you use the full power of +the @code{patsubst} function. It has the same form +@samp{$(@var{var}:@var{a}=@var{b})} described above, except that now +@var{a} must contain a single @samp{%} character. This case is +equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}. +@xref{Text Functions, ,Functions for String Substitution and Analysis}, +for a description of the @code{patsubst} function. For example: + +@example +@group +foo := a.o b.o l.a c.o +bar := $(foo:%.o=%.c) +@end group +@end example + +@noindent +sets @samp{bar} to @samp{a.c b.c l.a c.c}. + @node Override Directive @section The @code{override} Directive @findex override @@ -6457,7 +6527,7 @@ override @var{variable} += @var{more text} @end example @noindent -@xref{Appending, ,Appending More Text to Variables}. +@xref{Appending Assignment, ,Appending More Text to Variables}. Variable assignments marked with the @code{override} flag have a higher priority than all other assignments, except another @@ -6759,7 +6829,7 @@ For example: @noindent will assign @code{CFLAGS} the value of @samp{-O} for all targets -matching the pattern @code{%.o}. +matching the pattern @samp{%.o}. If a target matches more than one pattern, the matching pattern-specific variables with longer stems are interpreted first. This results in more @@ -6818,7 +6888,7 @@ prog: private EXTRA_CFLAGS = -L/usr/local/lib prog: a.o b.o @end example -Due to the @code{private} modifier, @code{a.o} and @code{b.o} will not +Due to the @code{private} modifier, @samp{a.o} and @samp{b.o} will not inherit the @code{EXTRA_CFLAGS} variable assignment from the @code{prog} target. @@ -7207,17 +7277,17 @@ foo: $(objects) $(CC) -o foo $(objects) $(normal_libs) @end example -Equivalent results can be obtained in another way by conditionalizing a -variable assignment and then using the variable unconditionally: +Equivalent results can be obtained in another way by conditionally assigning a +variable and then using the variable unconditionally: @example libs_for_gcc = -lgnu normal_libs = ifeq ($(CC),gcc) - libs=$(libs_for_gcc) + libs = $(libs_for_gcc) else - libs=$(normal_libs) + libs = $(normal_libs) endif foo: $(objects) @@ -12865,7 +12935,7 @@ mandated by @cite{IEEE Standard 1003.2-1992} (POSIX.2). @item The @samp{+=} syntax to append to the value of a variable comes from SunOS -4 @code{make}. @xref{Appending, , Appending More Text to Variables}. +4 @code{make}. @xref{Appending Assignment, , Appending More Text to Variables}. @item The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list