docs: AM_DISTCHECK_CONFIGURE_FLAGS is for corner cases

* doc/automake.texi (Checking the Distribution): Explain that the
developers should take care of making their code buildable without
requiring any special configure options, so that in general
AM_DISTCHECK_CONFIGURE_FLAGS shouldn't be used.  Give an example
of where its use is legitimate.

diff --git a/ChangeLog b/ChangeLog
index f18647adef5422a73dd4b42e99702d8bd4863ec9..9fabd7d12ca8c13a43e70e1eec42cdffb740243b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2011-06-18  Stefano Lattarini  <stefano.lattarini@gmail.com>
+
+       docs: AM_DISTCHECK_CONFIGURE_FLAGS is for corner cases
+       * doc/automake.texi (Checking the Distribution): Explain that the
+       developers should take care of making their code buildable without
+       requiring any special configure options, so that in general
+       AM_DISTCHECK_CONFIGURE_FLAGS shouldn't be used.  Give an example
+       of where its use is legitimate.
+       Suggestions from Ralf Wildenhues and Eric Blake.
+
 2011-06-13  Stefano Lattarini  <stefano.lattarini@gmail.com>
 
        news: update w.r.t. introduction of AM_DISTCHECK_CONFIGURE_FLAGS

diff --git a/doc/automake.texi b/doc/automake.texi
index b3aecfca0072f932f03760b9cacf7b5e13241457..14c2867401d6e0cdff7e4bbc640779985a39752a 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8426,6 +8426,21 @@ to supply additional flags to @command{configure}, define them in the
 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
 on the command line when invoking @command{make}.
 
+Still, developers are encouraged to strive to make their code buildable
+without requiring any special configure option; thus, in general, you
+shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
+might be few scenarios in which the use of this variable is justified.
+GNU @command{m4} offers an example.  GNU @command{m4} configures by
+default with its experimental and seldom used "changeword" feature
+disabled; so in its case it is useful to have @command{make distcheck}
+run configure with the @option{--with-changeword} option, to ensure that
+the code for changeword support still compiles correctly.
+GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
+variable to stress-test the use of @option{--program-prefix=g}, since at
+one point the @command{m4} build system had a bug where @command{make
+installcheck} was wrongly assuming it could blindly test "@command{m4}",
+rather than the just-installed "@command{gm4}".
+
 @trindex distcheck-hook
 If the @code{distcheck-hook} rule is defined in your top-level
 @file{Makefile.am}, then it will be invoked by @code{distcheck} after