(make.info.gz) Secondary Expansion
Info Catalog
(make.info.gz) Reading Makefiles
(make.info.gz) Makefiles
3.10 Secondary Expansion
========================
In the previous section we learned that GNU `make' works in two
distinct phases: a read-in phase and a target-update phase ( How
`make' Reads a Makefile Reading Makefiles.). GNU make also has the
ability to enable a _second expansion_ of the prerequisites (only) for
some or all targets defined in the makefile. In order for this second
expansion to occur, the special target `.SECONDEXPANSION' must be
defined before the first prerequisite list that makes use of this
feature.
If that special target is defined then in between the two phases
mentioned above, right at the end of the read-in phase, all the
prerequisites of the targets defined after the special target are
expanded a _second time_. In most circumstances this secondary
expansion will have no effect, since all variable and function
references will have been expanded during the initial parsing of the
makefiles. In order to take advantage of the secondary expansion phase
of the parser, then, it's necessary to _escape_ the variable or
function reference in the makefile. In this case the first expansion
merely un-escapes the reference but doesn't expand it, and expansion is
left to the secondary expansion phase. For example, consider this
makefile:
.SECONDEXPANSION:
ONEVAR = onefile
TWOVAR = twofile
myfile: $(ONEVAR) $$(TWOVAR)
After the first expansion phase the prerequisites list of the
`myfile' target will be `onefile' and `$(TWOVAR)'; the first
(unescaped) variable reference to ONEVAR is expanded, while the second
(escaped) variable reference is simply unescaped, without being
recognized as a variable reference. Now during the secondary expansion
the first word is expanded again but since it contains no variable or
function references it remains the static value `onefile', while the
second word is now a normal reference to the variable TWOVAR, which is
expanded to the value `twofile'. The final result is that there are
two prerequisites, `onefile' and `twofile'.
Obviously, this is not a very interesting case since the same result
could more easily have been achieved simply by having both variables
appear, unescaped, in the prerequisites list. One difference becomes
apparent if the variables are reset; consider this example:
.SECONDEXPANSION:
AVAR = top
onefile: $(AVAR)
twofile: $$(AVAR)
AVAR = bottom
Here the prerequisite of `onefile' will be expanded immediately, and
resolve to the value `top', while the prerequisite of `twofile' will
not be full expanded until the secondary expansion and yield a value of
`bottom'.
This is marginally more exciting, but the true power of this feature
only becomes apparent when you discover that secondary expansions
always take place within the scope of the automatic variables for that
target. This means that you can use variables such as `$@', `$*', etc.
during the second expansion and they will have their expected values,
just as in the command script. All you have to do is defer the
expansion by escaping the `$'. Also, secondary expansion occurs for
both explicit and implicit (pattern) rules. Knowing this, the possible
uses for this feature increase dramatically. For example:
.SECONDEXPANSION:
main_OBJS := main.o try.o test.o
lib_OBJS := lib.o api.o
main lib: $$($$@_OBJS)
Here, after the initial expansion the prerequisites of both the
`main' and `lib' targets will be `$($@_OBJS)'. During the secondary
expansion, the `$@' variable is set to the name of the target and so
the expansion for the `main' target will yield `$(main_OBJS)', or
`main.o try.o test.o', while the secondary expansion for the `lib'
target will yield `$(lib_OBJS)', or `lib.o api.o'.
You can also mix functions here, as long as they are properly
escaped:
main_SRCS := main.c try.c test.c
lib_SRCS := lib.c api.c
.SECONDEXPANSION:
main lib: $$(patsubst %.c,%.o,$$($$@_SRCS))
This version allows users to specify source files rather than object
files, but gives the same resulting prerequisites list as the previous
example.
Evaluation of automatic variables during the secondary expansion
phase, especially of the target name variable `$$@', behaves similarly
to evaluation within command scripts. However, there are some subtle
differences and "corner cases" which come into play for the different
types of rule definitions that `make' understands. The subtleties of
using the different automatic variables are described below.
Secondary Expansion of Explicit Rules
-------------------------------------
During the secondary expansion of explicit rules, `$$@' and `$$%'
evaluate, respectively, to the file name of the target and, when the
target is an archive member, the target member name. The `$$<'
variable evaluates to the first prerequisite in the first rule for this
target. `$$^' and `$$+' evaluate to the list of all prerequisites of
rules _that have already appeared_ for the same target (`$$+' with
repetitions and `$$^' without). The following example will help
illustrate these behaviors:
.SECONDEXPANSION:
foo: foo.1 bar.1 $$< $$^ $$+ # line #1
foo: foo.2 bar.2 $$< $$^ $$+ # line #2
foo: foo.3 bar.3 $$< $$^ $$+ # line #3
In the first prerequisite list, all three variables (`$$<', `$$^',
and `$$+') expand to the empty string. In the second, they will have
values `foo.1', `foo.1 bar.1', and `foo.1 bar.1' respectively. In the
third they will have values `foo.1', `foo.1 bar.1 foo.2 bar.2', and
`foo.1 bar.1 foo.2 bar.2' respectively.
Rules undergo secondary expansion in makefile order, except that the
rule with the command script is always evaluated last.
The variables `$$?' and `$$*' are not available and expand to the
empty string.
Secondary Expansion of Static Pattern Rules
-------------------------------------------
Rules for secondary expansion of static pattern rules are identical to
those for explicit rules, above, with one exception: for static pattern
rules the `$$*' variable is set to the pattern stem. As with explicit
rules, `$$?' is not available and expands to the empty string.
Secondary Expansion of Implicit Rules
-------------------------------------
As `make' searches for an implicit rule, it substitutes the stem and
then performs secondary expansion for every rule with a matching target
pattern. The value of the automatic variables is derived in the same
fashion as for static pattern rules. As an example:
.SECONDEXPANSION:
foo: bar
foo foz: fo%: bo%
%oo: $$< $$^ $$+ $$*
When the implicit rule is tried for target `foo', `$$<' expands to
`bar', `$$^' expands to `bar boo', `$$+' also expands to `bar boo', and
`$$*' expands to `f'.
Note that the directory prefix (D), as described in Implicit
Rule Search Algorithm Implicit Rule Search, is appended (after
expansion) to all the patterns in the prerequisites list. As an
example:
.SECONDEXPANSION:
/tmp/foo.o:
%.o: $$(addsuffix /%.c,foo bar) foo.h
The prerequisite list after the secondary expansion and directory
prefix reconstruction will be `/tmp/foo/foo.c /tmp/var/bar/foo.c
foo.h'. If you are not interested in this reconstruction, you can use
`$$*' instead of `%' in the prerequisites list.
Info Catalog
(make.info.gz) Reading Makefiles
(make.info.gz) Makefiles
automatically generated byinfo2html