[Automake-ng] [FYI] [ng] docs: we assume GNU make now; update accordingly

[Stefano Lattarini]

* doc/automake.texi: Update and adjust.  Add some FIXME comments for
more delicate passages that should be re-worked and addressed in the
future.
* tests/interp3.test: New test, exposing a known Automake limitation
that is particularly annoying for GNU make users.
* tests/Makefile.am  (XFAIL_TESTS): Add it.
* tests/list-of-tests.mk: Likewise.
---
 doc/automake.texi      |  114 +++++++++++++++++++++---------------------------
 tests/Makefile.am      |    1 +
 tests/interp3.test     |   60 +++++++++++++++++++++++++
 tests/list-of-tests.mk |    1 +
 4 files changed, 112 insertions(+), 64 deletions(-)
 create mode 100755 tests/interp3.test

diff --git a/doc/automake.texi b/doc/automake.texi
index f3a3532..15af185 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -1829,16 +1829,18 @@ distributions from the source control system.
 
 @cindex GNU make extensions
 
-Note that most GNU make extensions are not recognized by Automake.  Using
-such extensions in a @file{Makefile.am} will lead to errors or confusing
-behavior.
+Note that most GNU make extensions are sadly not yet recognized by
+Automake.  Using such extensions in a @file{Makefile.am} will likely
+lead to errors or confusing behavior.  We hope to improve this
+situation over time.
 
 @cindex Append operator
 @cmindex +=
-A special exception is that the GNU make append operator, @samp{+=}, is
-supported.  This operator appends its right hand argument to the variable
-specified on the left.  Automake will translate the operator into
-an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
+For historical reasons, the GNU make append operator @samp{+=} (which
+appends its right hand argument to the variable specified on the left)
+is supported and handled in a special way: Automake will translate the
+operator into an ordinary @samp{=} operator @emph{at Automake (not make)
+runtime}.  This behaviour might change future versions.
 
 Automake tries to keep comments grouped with any adjoining rules or
 variable definitions.
@@ -1880,9 +1882,10 @@ names might change in future releases.
 @cindex Automake, recursive operation
 @cindex Example of recursive operation
 
-When examining a variable definition, Automake will recursively examine
-variables referenced in the definition.  For example, if Automake is
-looking at the content of @code{foo_SOURCES} in this snippet
+When examining the definition of some ``special'' variables, Automake
+might recursively examine variables referenced in the definition in order
+to perform its magic.  For example, if Automake is looking at the content
+of @code{foo_SOURCES} in this snippet
 
 @c Keep in sync with interp.test.
 @example
@@ -1893,6 +1896,19 @@ foo_SOURCES = c.c $(xs)
 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
 contents of @code{foo_SOURCES}.
 
+Unfortunately, for historical reasons, this interpolation processes
+has the effect of currently making it impossible to use more advanced
+GNU make features in the definitions of special variables like
address@hidden; for example, Automake will generate a broken
address@hidden on this input:
+
address@hidden Keep in sync with interp3.test.
address@hidden
+bin_PROGRAMS = foo
+xs = one two
+foo_SOURCES = main.c $(foreach base, $(xs), $(base).c $(base).h)
address@hidden example
+
 @cindex @code{##} (special Automake comment)
 @cindex Special Automake comment
 @cindex Comment, special to Automake
@@ -2688,8 +2704,10 @@ obsolete features or constructions
 @item override
 user redefinitions of Automake rules or variables
 @item portability
-portability issues (e.g., use of @command{make} features that are
-known to be not portable)
+portability issues; e.g., use of file names like @file{aux} that are
+reserved on some systems (like Windows), or use of Automake features
+that require support from the target C compiler, support that is
+known not be present on all the mainstream C compilers.
 @item extra-portability
 extra portability issues related to obscure tools.  One example of such
 a tool is the Microsoft @command{lib} archiver.
@@ -6794,8 +6812,7 @@ the @code{_LDFLAGS} variable for the program.
 
 Automake provides initial support for Vala
 (@uref{http://www.vala-project.org/}).
-This requires valac version 0.7.0 or later, and currently requires
-the user to use GNU @command{make}.
+This requires valac version 0.7.0 or later.
 
 @example
 foo_SOURCES = foo.vala bar.vala zardoc.c
@@ -9181,14 +9198,7 @@ to avoid this limitation.
 
 Please note that it is currently not possible to use @code{$(srcdir)/}
 or @code{$(top_srcdir)/} in the @code{TESTS} variable.  This technical
-limitation is necessary to avoid generating test logs in the source tree
-and has the unfortunate consequence that it is not possible to specify
-distributed tests that are themselves generated by means of explicit
-rules, in a way that is portable to all @command{make} implementations
-(@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
-semantics of FreeBSD and OpenBSD @command{make} conflict with this).
-In case of doubt you may want to require to use GNU @command{make},
-or work around the issue with inference rules to generate the tests.
+limitation is necessary to avoid generating test logs in the source tree.
 
 @node Custom Test Drivers
 @section Custom Test Drivers
@@ -10705,7 +10715,7 @@ debugging and error assessment very difficult.
 
 @item @command{make --no-print-directory}
 
-This is GNU @command{make} specific.  When called with the
+When called with the
 @option{--no-print-directory} option, GNU @command{make} will disable
 printing of the working directory by invoked address@hidden (the
 well-known address@hidden/Leaving directory ...}'' messages).  This helps
@@ -11359,7 +11369,7 @@ keep the third-party sources untouched to ease upgrades 
to new
 versions.
 
 @cindex @file{GNUmakefile} including @file{Makefile}
-Here are two other ideas.  If GNU make is assumed, one possibility is
+Here are two other ideas.  One possibility is
 to add to that subdirectory a @file{GNUmakefile} that defines the
 required targets and includes the third-party @file{Makefile}.  For
 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
@@ -11855,49 +11865,24 @@ even though a file is missing. By listing files, 
@samp{make dist}
 @emph{will} complain.
 
 @item
-Wildcards are not portable to some non-GNU @command{make} implementations,
-e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
-prerequisites of a target.
-
address@hidden
 Finally, it's really hard to @emph{forget} to add a file to
 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
 not compiled or installed, so you can't even test them.
 @end itemize
 
 Still, these are philosophical objections, and as such you may disagree,
-or find enough value in wildcards to dismiss all of them.  Before you
-start writing a patch against Automake to teach it about wildcards,
-let's see the main technical issue: portability.
-
-Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
-not portable to other @command{make} implementations.
-
-The only way Automake could support @command{$(wildcard ...)} is by
-expending @command{$(wildcard ...)} when @command{automake} is run.
-The resulting @file{Makefile.in}s would be portable since they would
-list all files and not use @samp{$(wildcard ...)}.  However that
-means developers would need to remember to run @command{automake} each
-time they add, delete, or rename files.
-
-Compared to editing @file{Makefile.am}, this is a very small gain.  Sure,
-it's easier and faster to type @samp{automake; make} than to type
address@hidden Makefile.am; make}.  But nobody bothered enough to write a
-patch to add support for this syntax.  Some people use scripts to
-generate file lists in @file{Makefile.am} or in separate
address@hidden fragments.
-
-Even if you don't care about portability, and are tempted to use
address@hidden(wildcard ...)} anyway because you target only GNU Make, you
-should know there are many places where Automake needs to know exactly
-which files should be processed.  As Automake doesn't know how to
-expand @samp{$(wildcard ...)}, you cannot use it in these places.
+or find enough value in wildcards to dismiss all of them.  Still, before
+you start ignoring our advice and using @samp{$(wildcard ...)} all over
+the place, you should know there are many places where Automake needs to
+know exactly which files should be processed @footnote{This limitation
+is mostly due to historical reasons; unfortunately, the current
+implementation has been heavily influenced by that assumption, and
+is difficult to change now.  We hope this situation will improve in
+the future (no promises though).}.  As Automake doesn't know how to
+expand @samp{$(wildcard ...)}, you @emph{cannot} use it in these places;
 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
 variables as far Automake is concerned.
 
-You can get warnings about @samp{$(wildcard ...}) constructs using the
address@hidden flag.
-
 @node Limitations on File Names
 @section Limitations on File Names
 @cindex file names, limitations on
@@ -12596,8 +12581,7 @@ to the timestamp ordering of @file{data.h}, 
@file{data.w},
 @file{data.x}, and @file{data.c}.  Another one is a race condition
 if a parallel @command{make} attempts to run multiple instances of the
 recover block at once.  Finally, the recursive rule breaks @samp{make -n}
-when run with GNU @command{make} (as well as some other @command{make}
-implementations), as it may remove @file{data.h} even when it should not
+as it may remove @file{data.h} even when it should not
 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
 The GNU Make Manual}).
 
@@ -12774,6 +12758,8 @@ $(ELCFILES): elc-stamp
         fi
 @end example
 
address@hidden Automake-NG does assume GNU make, so we might want to
+re-work this section to take advantage of pattern rules support.}
 For completeness it should be noted that GNU @command{make} is able to
 express rules with multiple output files using pattern rules
 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
@@ -12933,10 +12919,10 @@ If less verbose output has been enabled in the 
package with the
 @code{make V=1} to see the commands being executed.
 @item
 @code{make -n} can help show what would be done without actually doing
-it.  Note however, that this will @emph{still execute} commands prefixed
-with @samp{+}, and, when using GNU @command{make}, commands that contain
-the strings @samp{$(MAKE)} or @address@hidden@}} (@pxref{Instead of
-Execution,,, make, The GNU Make Manual}).
+it.  Note however, that this will @emph{still execute} recipes prefixed
+with @samp{+} and recipes that contain the strings @samp{$(MAKE)} or
address@hidden@address@hidden (@pxref{Instead of Execution,,, make, The GNU Make
+Manual}).
 Typically, this is helpful to show what recursive rules would do, but it
 means that, in your own rules, you should not mix such recursion with
 actions that change any address@hidden's @samp{dist} and
diff --git a/tests/Makefile.am b/tests/Makefile.am
index dc16ad5..9381f26 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -38,6 +38,7 @@ XFAIL_TESTS = \
 all.test \
 cond17.test \
 gcj6.test \
+interp3.test \
 override-conditional-2.test \
 java-nobase.test \
 objext-pr10128.test \
diff --git a/tests/interp3.test b/tests/interp3.test
new file mode 100755
index 0000000..ba74339
--- /dev/null
+++ b/tests/interp3.test
@@ -0,0 +1,60 @@
+#! /bin/sh
+# Copyright (C) 2012 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Variable interpolation should work even when GNU make functions are
+# involved.  This is unfortunately not the case currently, due to
+# historical and hard-to-lift limitations (this is also documented in
+# the manual, using an example that is a stripped-down version of this
+# test case).
+
+required=cc
+. ./defs || Exit 1
+
+cat >> configure.in << 'END'
+AC_PROG_CC
+AC_OUTPUT
+END
+
+cat > Makefile.am << 'END'
+bin_PROGRAMS = foo
+xs = one two
+foo_SOURCES = main.c $(foreach base, $(xs), $(base).c $(base).h)
+END
+
+$ACLOCAL
+$AUTOMAKE
+$AUTOCONF
+
+./configure
+
+echo 'int one (void) { return 1; }' > one.c
+echo 'extern int one (void);' > one.h
+echo 'int two (void) { return 2; }' > two.c
+echo 'extern int two (void);' > two.h
+
+cat > main.c <<'END'
+#include "one.h"
+#include "two.h"
+int maint (void)
+{
+  return one () + two ();
+}
+END
+
+$MAKE
+$MAKE distcheck
+
+:
diff --git a/tests/list-of-tests.mk b/tests/list-of-tests.mk
index 8f66c26..ea04a10 100644
--- a/tests/list-of-tests.mk
+++ b/tests/list-of-tests.mk
@@ -491,6 +491,7 @@ instmany-python.test \
 install-info-dir.test \
 interp.test \
 interp2.test \
+interp3.test \
 java.test \
 java2.test \
 java3.test \
-- 
1.7.7.3