make: Secondary Expansion

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