summaryrefslogtreecommitdiff
path: root/doc/make.texi
diff options
context:
space:
mode:
authorPaul Smith <psmith@gnu.org>2005-10-24 13:01:39 +0000
committerPaul Smith <psmith@gnu.org>2005-10-24 13:01:39 +0000
commit11095a90f120545c915c92b8ebf48f04723d1837 (patch)
tree73dba88903ea90cdac930057fe8619a8a04fb869 /doc/make.texi
parent66459baee27374577d32a78564604ad64228f71d (diff)
downloadgunmake-11095a90f120545c915c92b8ebf48f04723d1837.tar.gz
Make second expansion optional (partial implementation).
I decided this feature was too impacting to make the permanent default behavior. This set of changes makes the default behavior of make the old behavior (no second expansion). If you want second expansion, you must define the .SECONDEXPANSION: special target before the first target that needs it. This set of changes ONLY fixes explicit and static pattern rules to work like this. Implicit rules still have second expansion enabled all the time: I'll work on that next. Note that there is still a backward-incompatibility: now to get the old SysV behavior using $$@ etc. in the prerequisites list you need to set .SECONDEXPANSION: as well.
Diffstat (limited to 'doc/make.texi')
-rw-r--r--doc/make.texi62
1 files changed, 46 insertions, 16 deletions
diff --git a/doc/make.texi b/doc/make.texi
index 526aec6..cc5f061 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -1612,22 +1612,31 @@ static pattern rules, and simple prerequisite definitions.
@cindex secondary expansion
@cindex expansion, secondary
+@findex .SECONDEXPANSION
In the previous section we learned that GNU @code{make} works in two
distinct phases: a read-in phase and a target-update phase
-(@pxref{Reading Makefiles, , How @code{make} Reads a Makefile}).
-There is an extra wrinkle that comes in between those two phases,
-right at the end of the read-in phase: at that time, all the
-prerequisites of all of the targets are expanded a @emph{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 @emph{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:
-
-@example
+(@pxref{Reading Makefiles, , How @code{make} Reads a Makefile}). GNU
+make also has the ability to enable a @emph{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
+@code{.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 @emph{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 @emph{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:
+
+@example
+.SECONDEXPANSION:
ONEVAR = onefile
TWOVAR = twofile
myfile: $(ONEVAR) $$(TWOVAR)
@@ -1651,6 +1660,7 @@ appear, unescaped, in the prerequisites list. One difference becomes
apparent if the variables are reset; consider this example:
@example
+.SECONDEXPANSION:
AVAR = top
onefile: $(AVAR)
twofile: $$(AVAR)
@@ -1670,10 +1680,11 @@ target. This means that you can use variables such as @code{$@@},
expected values, just as in the command script. All you have to do is
defer the expansion by escaping the @code{$}. Also, secondary
expansion occurs for both explicit and implicit (pattern) rules.
-Knowing this, the possible uses for this feature are almost endless.
-For example:
+Knowing this, the possible uses for this feature increase
+dramatically. For example:
@example
+.SECONDEXPANSION:
main_OBJS := main.o try.o test.o
lib_OBJS := lib.o api.o
@@ -1694,6 +1705,7 @@ 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))
@end example
@@ -1723,6 +1735,8 @@ the same target (@code{$$+} with repetitions and @code{$$^}
without). The following example will help illustrate these behaviors:
@example
+.SECONDEXPANSION:
+
foo: foo.1 bar.1 $$< $$^ $$+ # line #1
foo: foo.2 bar.2 $$< $$^ $$+ # line #2
@@ -1763,6 +1777,8 @@ target pattern. The value of the automatic variables is derived in
the same fashion as for static pattern rules. As an example:
@example
+.SECONDEXPANSION:
+
foo: bar
foo foz: fo%: bo%
@@ -1781,6 +1797,8 @@ expansion) to all the patterns in the prerequisites list. As an
example:
@example
+.SECONDEXPANSION:
+
/tmp/foo.o:
%.o: $$(addsuffix /%.c,foo bar) foo.h
@@ -2880,6 +2898,18 @@ intermediate files, except that they are never automatically deleted.
as secondary (i.e., no target is removed because it is considered
intermediate).
+@findex .SECONDEXPANSION
+@item .SECONDEXPANSION
+
+If @code{.SECONDEXPANSION} is mentioned as a target anwyeren in the
+makefile, then all prerequisite lists defined @emph{after} it appears
+will be expanded a second time after all makefiles have been read in.
+@xref{Secondary Expansion, ,Secondary Expansion}.
+
+The prerequisites of the special target @code{.SUFFIXES} are the list
+of suffixes to be used in checking for suffix rules.
+@xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
+
@findex .DELETE_ON_ERROR
@item .DELETE_ON_ERROR
@cindex removing targets on failure