Improve wording related to automake and autotest.

* doc/autoconf.texi (Making testsuite Scripts): Clarify wording in
relation to automake.  Mention dependency on package.m4.
Consolidate examples.  Define AUTOM4TE.
* THANKS: Update.
Reported by William Pursell.

Signed-off-by: Eric Blake <ebb9@byu.net>

diff --git a/ChangeLog b/ChangeLog
index cb4d54a878df361db90884afc0ad30871117995d..5007d8cf1bf23c10dadbc89d65abc82ef08bf56f 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2008-10-21  Eric Blake  <ebb9@byu.net>
+
+       Improve wording related to automake and autotest.
+       * doc/autoconf.texi (Making testsuite Scripts): Clarify wording in
+       relation to automake.  Mention dependency on package.m4.
+       Consolidate examples.  Define AUTOM4TE.
+       * THANKS: Update.
+       Reported by William Pursell.
+
 2008-10-21  Eric Blake  <ebb9@byu.net>
 
        Allow AS_VAR_SET_IF in shell lists.

diff --git a/THANKS b/THANKS
index 366bf62802bac3c716763ae7b9fbf4399e4e4337..977185f633bda6297ed3503cfc410474242289e8 100644 (file)
--- a/THANKS
+++ b/THANKS
@@ -354,6 +354,7 @@ Volker Borchert             bt@teknon.de
 Wayne Chapeskie             waynec@spinnaker.com
 Werner Lemberg              wl@gnu.org
 Wilfredo Sanchez            wsanchez@apple.com
+William Pursell             bill.pursell@gmail.com
 Wolfgang Mueller            Wolfgang.Mueller@cui.unige.ch
 Yury Puhalsky               pooh@cryptopro.ru
 Zack Weinberg               zack@codesourcery.com

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 145302f747ba657fdbd8078b23df03e0965644ab..71f507f1e5e14ddd5e5ccdac8f9d9ed2e67a4907 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -21602,25 +21602,10 @@ full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
 address to which bug reports should be sent.  For sake of completeness,
 we suggest that you also define @code{AT_PACKAGE_NAME},
 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
-@xref{Initializing configure}, for a description of these variables.  We
-suggest the following makefile excerpt:
-
-@smallexample
-# The `:;' works around a Bash 3.2 bug when the output is not writeable.
-$(srcdir)/package.m4: $(top_srcdir)/configure.ac
-        :;@{ \
-          echo '# Signature of the current package.' && \
-          echo 'm4_define([AT_PACKAGE_NAME],      [@@PACKAGE_NAME@@])' && \
-          echo 'm4_define([AT_PACKAGE_TARNAME],   [@@PACKAGE_TARNAME@@])' && \
-          echo 'm4_define([AT_PACKAGE_VERSION],   [@@PACKAGE_VERSION@@])' && \
-          echo 'm4_define([AT_PACKAGE_STRING],    [@@PACKAGE_STRING@@])' && \
-          echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
-        @} >'$(srcdir)/package.m4'
-@end smallexample
-
-@noindent
+@xref{Initializing configure}, for a description of these variables.
 Be sure to distribute @file{package.m4} and to put it into the source
-hierarchy: the test suite ought to be shipped!
+hierarchy: the test suite ought to be shipped!  See below for an example
+@file{Makefile} excerpt.
 
 @item
 Invoke @code{AC_CONFIG_TESTDIR}.
@@ -21639,16 +21624,33 @@ Still within @file{configure.ac}, as appropriate, ensure that some
 @file{tests/atlocal}.
 
 @item
-The @file{tests/Makefile.in} should be modified so the validation in
+The appropriate @file{Makefile} should be modified so the validation in
 your package is triggered by @samp{make check}.  An example is provided
 below.
 @end itemize
 
-With Automake, here is a minimal example about how to link @samp{make
-check} with a validation suite.
+With Automake, here is a minimal example for inclusion in
+@file{tests/Makefile.am}, in order to link @samp{make check} with a
+validation suite.
 
 @example
-EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
+# The `:;' works around a Bash 3.2 bug when the output is not writeable.
+$(srcdir)/package.m4: $(top_srcdir)/configure.ac
+        :;@{ \
+          echo '# Signature of the current package.' && \
+          echo 'm4_define([AT_PACKAGE_NAME],' && \
+          echo '  [@@PACKAGE_NAME@@])' && \
+          echo 'm4_define([AT_PACKAGE_TARNAME],' && \
+          echo '  [@@PACKAGE_TARNAME@@])' && \
+          echo 'm4_define([AT_PACKAGE_VERSION],' && \
+          echo '  [@@PACKAGE_VERSION@@])' && \
+          echo 'm4_define([AT_PACKAGE_STRING],' && \
+          echo '  [@@PACKAGE_STRING@@])' && \
+          echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \
+          echo '  [@@PACKAGE_BUGREPORT@@])'; \
+        @} >'$(srcdir)/package.m4'
+
+EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in
 TESTSUITE = $(srcdir)/testsuite
 
 check-local: atconfig atlocal $(TESTSUITE)
@@ -21662,17 +21664,25 @@ clean-local:
         test ! -f '$(TESTSUITE)' || \
          $(SHELL) '$(TESTSUITE)' --clean
 
+AUTOM4TE = $(SHELL) $(srcdir)/build-aux/missing --run autom4te
 AUTOTEST = $(AUTOM4TE) --language=autotest
 $(TESTSUITE): $(srcdir)/testsuite.at
         $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
         mv $@@.tmp $@@
 @end example
 
+Note that the built testsuite is distributed; this is necessary because
+users might not have Autoconf installed, and thus would not be able to
+rebuild it.  Likewise, the use of @file{missing} provides the user with
+a nicer error message if they modify a source file to the testsuite, and
+accidentally trigger the rebuild rules.
+
 You might want to list explicitly the dependencies, i.e., the list of
 the files @file{testsuite.at} includes.
 
-If you don't use Automake, you might need to add lines inspired from the
-following:
+If you don't use Automake, you should include the above example in
+@file{tests/@/Makefile.in}, along with additional lines inspired from
+the following:
 
 @example
 subdir = tests
@@ -21687,10 +21697,9 @@ atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
 @end example
 
 @noindent
-and manage to have @code{$(EXTRA_DIST)} distributed.
-
-If you use Automake, however, you don't need to add a rule to generate
-@file{atlocal}.
+and manage to have @code{$(EXTRA_DIST)} distributed.  You will also want
+to distribute the file @file{build-aux/@/missing} from the Automake
+project; a copy of this file resides in the Autoconf source.
 
 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
 within your makefile, you can fine-tune test suite execution with this