commit a154bff6788e19bbf66275cbbcafcd17fb6ca775
Author: Dmitry Goncharov <dgoncharov@users.sf.net>
Date:   Sun Jul 3 12:44:56 2022 -0400

    [SV 62706] Restrict second expansion.
    
    Second expand only the prerequisites of the targets being built.
    Avoid second expanding the prerequisites of targets which are not being
    built.
    
    * src/filedef.h (struct file): Add flag snapped.
    (expand_deps): Declare a function to second expand the
    prerequisites of a target.
    * src/file.c (rehash_file): Merge flag snapped.
    (expand_deps): Remove qualifier static. Check flag snapped.
    (snap_deps): Remove the loop which performed second expansion for all
    targets.
    * src/remake.c (update_file_1): Second expand the prerequisites of
    the considered target.
    * doc/make.texi (Secondary Expansion): Document the new behavior.
    * tests/scripts/features/se_explicit: Add tests.
    * tests/scripts/features/se_implicit: Ditto.
    * tests/scripts/features/se_statpat: Ditto.

diff --git a/doc/make.texi b/doc/make.texi
index 943c0941..99d523c5 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -1703,18 +1703,20 @@ 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:
+If that special target is defined, then during the target-update phase, when
+make considers a target, right before make goes through the list of the
+prerequisites of the target, make expands all the prerequisites of the target
+the @emph{second time}. In the case of explicit and static pattern rules this
+@emph{second expansion} is only performed once for a target.  In the case of
+implicit rules, this @emph{second expansion} is performed each time make tries
+this rule during implicit rule search. @xref{Implicit Rule Search}.
+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, 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:
@@ -1794,6 +1796,23 @@ This version allows users to specify source files rather than object
 files, but gives the same resulting prerequisites list as the previous
 example.
 
+Because, @emph{second expansion} is only performed when a target is considered,
+it is possible to use @emph{second expansion} to cause make to perform
+expensive work only for those targets which are being built.
+
+@example
+.SECONDEXPANSION:
+hello.tsk: $$(file <hello.d); $(info $@ from $^)
+bye.tsk: $$(file <bye.d); $(info $@ from $^)
+clean:; -rm -f hello.tsk bye.tsk
+@end example
+
+Assuming there are files @file{hello.d} and @file{bye.d} which contain the
+prerequisites of @file{hello.tsk} and @file{bye.tsk} respectively, @samp{make
+hello.tsk} will @emph{second expand} $$(file <hello.d) and will @emph{not
+second expand} $$(file <bye.d).  @samp{make clean} will @emph{not second
+expand} $$(file <hello.d) or $$(file <bye.d).
+
 Evaluation of automatic variables during the secondary expansion
 phase, especially of the target name variable @code{$$@@}, behaves
 similarly to evaluation within recipes.  However, there are some
