Limitations of Make: VPATH target lookup (Was: Re: Can't `make install' Autoconf 2.53b if makeinfo is missing + an OSF make issue)

[Alexandre Duret-Lutz]

>>> "adl" == Alexandre Duret-Lutz <address@hidden> writes:

 adl> I've seen two VPATH oddities that are not yet documented
 adl> in Autoconf; I'll submit a patch for this ASAP.

Here it is.  Ok to commit?

2002-07-30  Alexandre Duret-Lutz  <address@hidden>

        * doc/autoconf.texi (Limitations of Make): Add a 'target lookup'
        subentry in the 'VPATH' entry.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.653
diff -u -r1.653 autoconf.texi
--- doc/autoconf.texi   30 Jul 2002 00:42:58 -0000      1.653
+++ doc/autoconf.texi   30 Jul 2002 21:32:19 -0000
@@ -7405,6 +7405,8 @@
 Prepend directory @var{dir} to the search path.  This is used to include
 the language-specific files before any third-party macros.
 
address@hidden table
+
 @cindex @file{autom4te.cfg}
 As an example, if Autoconf is installed in its default location,
 @file{/usr/local}, running @samp{autom4te -l m4sugar foo.m4} is
@@ -10705,6 +10707,99 @@
 
 The above @command{command} will be run on the empty @file{foo/bar}
 directory that was created in the current directory.
+
address@hidden target lookup
address@hidden @code{VPATH}, resolving target pathnames
+
+GNU make uses a rather complex algortihm to decide when it should use
+files found via a @code{VPATH} search.  @xref{Search Algorithm,,
+How Directory Searches are Performed, make, The GNU Make Manual}.
+
+If a target need to be rebuild, GNU make discards the filename found
+during the @code{VPATH} search for this target, and build the file
+locally using the filename given in the Makefile.  If a target does
+not need to be rebuild, GNU make uses the filename found during the
address@hidden search.
+
+Other make implementations, like BSD make, are easier to describe: the
+filename found during the @code{VPATH} search will be used whether the
+target needs to be rebuilt or not.  Therefore new files are created
+locally, but existing files are updated at their @code{VPATH} location.
+
+When attempting a @code{VPATH} build for an autoconfiscated package
+(e.g, @code{mkdir build; ../configure}), this means the GNU make will
+build everything locally in the @file{build} directory, while BSD make
+will build new files locally and update existing files in the source
+directory.
+
address@hidden
+% @kbd{cat Makefile}
+VPATH = ..
+all: foo.x bar.x
+foo.x bar.x: newer.x
+        @@echo Building $@@
+% @kbd{touch ../bar.x}
+% @kbd{touch ../newer.x}
+% @kbd{make}        # GNU make
+Building foo.x
+Building bar.x
+% @kbd{pmake}       # BSD make
+Building foo.x
+Building ../bar.x
address@hidden example
+
+Another point worth to mention is that once GNU make has decided to
+ignore a @code{VPATH} filename (e.g. it ignored @file{../bar.x} in the
+above example) it will continue to ignore it when the target occurs as a
+prerequisite of another rule.
+
+The following example shows that GNU make with not lookup @file{bar.x}
+in @code{VPATH} before performing the @code{.x.y} rule, because it
+ignored the @code{VPATH} result of @file{bar.x} while running the
address@hidden: newer.x} rule.
+
address@hidden
+% @kbd{cat Makefile}
+VPATH = ..
+all: bar.y
+bar.x: newer.x
+        @@echo Building $@@
+.SUFFIXES: .x .y
+.x.y:
+        cp $< $@@
+% @kbd{touch ../bar.x}
+% @kbd{touch ../newer.x}
+% @kbd{make}        # GNU make
+Building bar.x
+cp bar.x bar.y
+cp: cannot stat `bar.x': No such file or directory
+make: *** [bar.y] Error 1
+% @kbd{pmake}       # BSD make
+Building ../bar.x
+cp ../bar.x bar.y
address@hidden example
+
+Note that if you drop away the command from the @code{bar.x: newer.x}
+rule, things will magically start to work: GNU make knows that
address@hidden hasn't been updated, therefore it doesn't discard the
+result from @code{VPATH} (@file{../bar.x}) in succeedding uses.
+
address@hidden
+% @kbd{cat Makefile}
+VPATH = ..
+all: bar.y
+bar.x: newer.x
+.SUFFIXES: .x .y
+.x.y:
+        cp $< $@@
+% @kbd{touch ../bar.x}
+% @kbd{touch ../newer.x}
+% @kbd{make}        # GNU make
+cp ../bar.x bar.y
+% @kbd{rm bar.y}
+% @kbd{pmake}       # BSD make
+cp ../bar.x bar.y
address@hidden example
 
 @end table
 @end table

-- 
Alexandre Duret-Lutz