[PATCH] docs: more details about make VPATH rewriting woes

[Stefano Lattarini]

* doc/autoconf.texi (Automatic Rule Rewriting): Solaris make
VPATH rewriting might apply also to shell variables, functions
and keywords (and automake has already tripped on this once);
document this, with an example.  Since we are at it, do some
minor reformatting of existing text.
---
 ChangeLog         |    9 +++++++++
 doc/autoconf.texi |   37 +++++++++++++++++++++++++++++--------
 2 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 6e36455..9a03f19 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2011-09-13  Stefano Lattarini  <address@hidden>
+
+       docs: more details about make VPATH rewriting woes
+       * doc/autoconf.texi (Automatic Rule Rewriting): Solaris make
+       VPATH rewriting might apply also to shell variables, functions
+       and keywords (and automake has already tripped on this once);
+       document this, with an example.  Since we are at it, do some
+       minor reformatting of existing text.
+
 2011-08-16  Stefano Lattarini  <address@hidden>
 
        docs: other issues with parallel BSD make
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 3377afe..bd37e5c 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -20255,14 +20255,35 @@ However, this rule leads to real problems in 
practice.  For example, if
 the source directory contains an ordinary file named @file{test} that is
 used in a dependency, Solaris @command{make} rewrites commands like
 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
address@hidden, which is typically undesirable.  To avoid this problem,
-portable makefiles should never mention a source file whose name is that
-of a shell keyword like @file{until} or a shell command like
address@hidden or @command{gcc} or @command{test}.
-
-Because of these problems GNU @command{make} and many other
address@hidden implementations do not rewrite commands, so portable
-makefiles should
address@hidden, which is typically undesirable.  The same might happen also
+to shell functions, variables and keywords.
+
address@hidden
+$ @kbd{mkdir build}
+$ @kbd{cd build}
+$ @kbd{cat > Makefile <<'END'}
+VPATH = ..
+all: arg func for echo
+        func () @{ for arg in "$$@@"; do echo $$arg; done; @}; \
+        func "hello world"
+END
+$ @kbd{touch ../arg ../func ../for ../echo}
+$ @kbd{make}
+../func () @{ ../for ../arg in "$@@"; do ../echo $arg; done; @}; \
+../func "hello world"
+sh: syntax error at line 1: `do' unexpected
+*** Error code 2
address@hidden example
+
address@hidden
+To avoid this problem, portable makefiles should never mention a source
+file or dependency whose name is that of a shell keyword like @file{for}
+or @file{until}, a shell command like @command{cat} or @command{gcc} or
address@hidden, or a shell function or variable used in the corresponding
address@hidden recipe.
+
+Because of these problems GNU @command{make} and many other @command{make}
+implementations do not rewrite commands, so portable makefiles should
 search @code{VPATH} manually.  It is tempting to write this:
 
 @smallexample
-- 
1.7.2.3