FYI: document CONFIGURE_DEPENDENCIES and CONFIG_STATUS_DEPENDENCIES

[Alexandre Duret-Lutz]

I'm installing this.

2003-12-04  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (Rebuilding): Document CONFIGURE_DEPENDENCIES
        and CONFIG_STATUS_DEPENDENCIES.  Move this sections later
        in the manual since it's pretty advanced material.

Index: NEWS
===================================================================
RCS file: /cvs/automake/automake/NEWS,v
retrieving revision 1.254
diff -u -r1.254 NEWS
--- NEWS        2 Dec 2003 20:55:18 -0000       1.254
+++ NEWS        4 Dec 2003 20:48:28 -0000
@@ -66,10 +66,10 @@
   - For similar reasons, the rules to rebuild configure,
     config.status, and aclocal.m4 are now defined in all directories.
     Note that if you were using the CONFIG_STATUS_DEPENDENCIES and
-    CONFIGURE_DEPENDENCIES (undocumented) variables, you should better
-    define them in all directories.  This is easily done using an
-    AC_SUBST (make sure you prefix these dependencies with
-    $(abs_top_srcdir) since this variable will appear at different
+    CONFIGURE_DEPENDENCIES (formerly undocumented) variables, you
+    should better define them in all directories.  This is easily done
+    using an AC_SUBST (make sure you prefix these dependencies with
+    $(top_srcdir) since this variable will appear at different
     levels of the build tree).
 
   - aclocal will now use `m4_include' instead of copying local m4
@@ -277,6 +277,10 @@
     on the command line.  The old behavior, where these variables were
     defined empty in each Makefile, can be obtained by AC_SUBSTing or
     AC_ARG_VARing each variable from configure.ac.
+
+  - CONFIGURE_DEPENDENCIES and CONFIG_STATUS_DEPENDENCIES are now
+    documented.  (The is not a new feature, these variables have
+    been there since at least Automake 1.4.)
 
 Bugs fixed in 1.7.9:
 * Fix install-strip to work with nobase_ binaries.
Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.16
diff -u -r1.16 automake.texi
--- doc/automake.texi   2 Dec 2003 20:00:02 -0000       1.16
+++ doc/automake.texi   4 Dec 2003 20:48:34 -0000
@@ -93,7 +93,6 @@
 * configure::                   Scanning configure.ac or configure.in
 * Top level::                   The top-level Makefile.am
 * Alternative::                 An alternative approach to subdirectories
-* Rebuilding::                  Automatic rebuilding of Makefile
 * Programs::                    Building programs and libraries
 * Other objects::               Other derived objects
 * Other GNU Tools::             Other GNU Tools
@@ -102,6 +101,7 @@
 * Clean::                       What gets cleaned
 * Dist::                        What goes in a distribution
 * Tests::                       Support for test suites
+* Rebuilding::                  Automatic rebuilding of Makefile
 * Options::                     Changing Automake's behavior
 * Miscellaneous::               Miscellaneous rules
 * Include::                     Including extra files in an Automake template.
@@ -1879,6 +1879,7 @@
 numerous macros, it will rapidly become difficult to maintain, and it
 will be almost impossible to share macros between package.
 
address@hidden ACLOCAL_AMFLAGS
 The second possibility, which we do recommend, is to write each macro
 in its own file and gather all these files in a directory.  This
 directory is usually called @file{m4/}.  To build @file{aclocal.m4},
@@ -2201,24 +2202,6 @@
 nobase_dist_pkgdata_DATA = images/vortex.pgm
 @end example
 
address@hidden Rebuilding
address@hidden Rebuilding Makefiles
-
-Automake generates rules to automatically rebuild @file{Makefile}s,
address@hidden, and other derived files like @file{Makefile.in}.
-
-If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
-these automatic rebuilding rules are only enabled in maintainer mode.
-
-Sometimes you need to run @code{aclocal} with an argument like @code{-I}
-to tell it where to find @file{.m4} files.  Since sometimes @code{make}
-will automatically run @code{aclocal}, you need a way to specify these
-arguments.  You can do this by defining @code{ACLOCAL_AMFLAGS}; this
-holds arguments which are passed verbatim to @code{aclocal}.  This variable
-is only useful in the top-level @file{Makefile.am}.
address@hidden ACLOCAL_AMFLAGS
-
-
 @node Programs
 @chapter Building Programs and Libraries
 
@@ -5459,6 +5442,100 @@
 The @code{installcheck} target is available to the user as a way to
 run any tests after the package has been installed.  You can add tests
 to this by writing an @code{installcheck-local} rule.
+
+
address@hidden Rebuilding
address@hidden Rebuilding Makefiles
address@hidden rebuild rules
+
+Automake generates rules to automatically rebuild @file{Makefile}s,
address@hidden, and other derived files like @file{Makefile.in}.
+
address@hidden AM_MAINTAINER_MODE
+If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
+these automatic rebuilding rules are only enabled in maintainer mode.
+
address@hidden ACLOCAL_AMFLAGS
+Sometimes you need to run @code{aclocal} with an argument like @code{-I}
+to tell it where to find @file{.m4} files.  Since sometimes @code{make}
+will automatically run @code{aclocal}, you need a way to specify these
+arguments.  You can do this by defining @code{ACLOCAL_AMFLAGS}; this
+holds arguments which are passed verbatim to @code{aclocal}.  This variable
+is only useful in the top-level @file{Makefile.am}.
+
address@hidden CONFIG_STATUS_DEPENDENCIES
address@hidden CONFIGURE_DEPENDENCIES
address@hidden @file{version.sh}, example
address@hidden @file{version.m4}, example
+
+Sometimes it is convenient to supplement the rebuild rules for
address@hidden or @file{config.status} with additional dependencies.
+The variables @code{CONFIGURE_DEPENDENCIES} and
address@hidden can be used to list these extra
+dependencies.  These variable should be defined in all
address@hidden of the tree (because these two rebuild rules are
+output in all them), so it is safer and easier to @code{AC_SUBST} them
+from @file{configure.ac}.  For instance the following statement will
+cause @file{configure} to be rerun each time @file{version.sh} is
+changed.
address@hidden
+AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
address@hidden example
address@hidden
+Note the @code{$(top_srcdir)/} in the filename.  Since this variable
+is to be used in all @file{Makefile}s, its value must be sensible at
+any level in the build hierarchy.
+
+Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
address@hidden
+
address@hidden adds dependencies to the
address@hidden rule, whose effect is to run @code{autoconf}.  This
+variable should be seldom used, because @code{automake} already tracks
address@hidden files.  However it can be useful when playing
+tricky games with @code{m4_esyscmd} or similar non-recommendable
+macros with side effects.
+
address@hidden adds dependencies to the
address@hidden rule, whose effect is to run @file{configure}.
+This variable should therefore carry any non-standard source that may
+be read as a side effect of running configure, like @file{version.sh}
+in the example above.
+
+Speaking of @file{version.sh} scripts, we recommend against them
+today.  They are mainly used when the version of a package is updated
+automatically by a script (e.g., in daily builds).  Here is what some
+old-style @file{configure.ac}s may look like:
address@hidden
+AC_INIT
+. $srcdir/version.sh
+AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
address@hidden
address@hidden example
address@hidden
+Here, @file{version.sh} is a shell fragment that sets
address@hidden  The problem with this example is that
address@hidden cannot track dependencies (listing @file{version.sh}
+in @code{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
+to the user), and that it uses the obsolete form of @code{AC_INIT} and
address@hidden  Upgrading to the new syntax is not
+straightforward, because shell variables are not allowed in
address@hidden's arguments.  We recommend that @file{version.sh} be
+replaced by an M4 file that is included by @file{configure.ac}:
address@hidden
+m4_include([version.m4])
+AC_INIT([name], VERSION_NUMBER)
+AM_INIT_AUTOMAKE
address@hidden
address@hidden example
address@hidden
+Here @file{version.m4} could contain something like
address@hidden([VERSION_NUMBER], [1.2])}.  The advantage of this
+second form is that @code{automake} will take care of the dependencies
+when defining the rebuild rule, and will also distribute the file
+automatically.  An inconvenient is that @code{autoconf} will now be
+rerun each time the version number is bumped, when only
address@hidden had to be rerun in the previous setup.
 
 
 @node Options
-- 
Alexandre Duret-Lutz