From f1ecbe81da0d33a4c7b3316b38044acbc0c2ced8 Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Thu, 4 Dec 2003 20:49:41 +0000 Subject: [PATCH] * doc/automake.texi (Rebuilding): Document CONFIGURE_DEPENDENCIES and CONFIG_STATUS_DEPENDENCIES. Move this sections later in the manual since it's pretty advanced material. --- ChangeLog | 4 ++ NEWS | 12 +++-- doc/automake.texi | 115 ++++++++++++++++++++++++++++++++++++++-------- doc/stamp-vti | 2 +- doc/version.texi | 2 +- 5 files changed, 110 insertions(+), 25 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4ddac4ab0..0774b1203 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2003-12-04 Alexandre Duret-Lutz + * doc/automake.texi (Rebuilding): Document CONFIGURE_DEPENDENCIES + and CONFIG_STATUS_DEPENDENCIES. Move this sections later + in the manual since it's pretty advanced material. + * automake.in ($config_header_location): Remove. Use %ac_config_files_location instead. (rewrite_inputs_into_dependencies): Do not prepend $(top_builddir)/ diff --git a/NEWS b/NEWS index dbf2523d5..905b6d427 100644 --- a/NEWS +++ b/NEWS @@ -66,10 +66,10 @@ New in 1.7i: - 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 @@ New in 1.7i: 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. diff --git a/doc/automake.texi b/doc/automake.texi index 1cd86c4ed..009caa61b 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -93,7 +93,6 @@ This edition documents version @value{VERSION}. * 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 @@ This edition documents version @value{VERSION}. * 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 @@ henceforth be visible to @command{autoconf}. However if it contains numerous macros, it will rapidly become difficult to maintain, and it will be almost impossible to share macros between package. +@vindex 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 @@ either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance: nobase_dist_pkgdata_DATA = images/vortex.pgm @end example -@node Rebuilding -@chapter Rebuilding Makefiles - -Automake generates rules to automatically rebuild @file{Makefile}s, -@file{configure}, 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}. -@vindex ACLOCAL_AMFLAGS - - @node Programs @chapter Building Programs and Libraries @@ -5461,6 +5444,100 @@ run any tests after the package has been installed. You can add tests to this by writing an @code{installcheck-local} rule. +@node Rebuilding +@chapter Rebuilding Makefiles +@cindex rebuild rules + +Automake generates rules to automatically rebuild @file{Makefile}s, +@file{configure}, and other derived files like @file{Makefile.in}. + +@cvindex 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. + +@vindex 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}. + +@vindex CONFIG_STATUS_DEPENDENCIES +@vindex CONFIGURE_DEPENDENCIES +@cindex @file{version.sh}, example +@cindex @file{version.m4}, example + +Sometimes it is convenient to supplement the rebuild rules for +@file{configure} or @file{config.status} with additional dependencies. +The variables @code{CONFIGURE_DEPENDENCIES} and +@code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra +dependencies. These variable should be defined in all +@file{Makefile}s 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. +@example +AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh']) +@end example +@noindent +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 +@code{CONFIG_STATUS_DEPENDENCIES}. + +@code{CONFIGURE_DEPENDENCIES} adds dependencies to the +@file{configure} rule, whose effect is to run @code{autoconf}. This +variable should be seldom used, because @code{automake} already tracks +@code{m4_include}d files. However it can be useful when playing +tricky games with @code{m4_esyscmd} or similar non-recommendable +macros with side effects. + +@code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the +@file{config.status} 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: +@example +AC_INIT +. $srcdir/version.sh +AM_INIT_AUTOMAKE([name], $VERSION_NUMBER) +@dots{} +@end example +@noindent +Here, @file{version.sh} is a shell fragment that sets +@code{VERSION_NUMBER}. The problem with this example is that +@code{automake} 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 +@code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not +straightforward, because shell variables are not allowed in +@code{AC_INIT}'s arguments. We recommend that @file{version.sh} be +replaced by an M4 file that is included by @file{configure.ac}: +@example +m4_include([version.m4]) +AC_INIT([name], VERSION_NUMBER) +AM_INIT_AUTOMAKE +@dots{} +@end example +@noindent +Here @file{version.m4} could contain something like +@code{m4_define([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 +@file{configure} had to be rerun in the previous setup. + + @node Options @chapter Changing Automake's Behavior diff --git a/doc/stamp-vti b/doc/stamp-vti index baf7e253f..face1ea31 100644 --- a/doc/stamp-vti +++ b/doc/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 2 December 2003 +@set UPDATED 4 December 2003 @set UPDATED-MONTH December 2003 @set EDITION 1.7i @set VERSION 1.7i diff --git a/doc/version.texi b/doc/version.texi index baf7e253f..face1ea31 100644 --- a/doc/version.texi +++ b/doc/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 2 December 2003 +@set UPDATED 4 December 2003 @set UPDATED-MONTH December 2003 @set EDITION 1.7i @set VERSION 1.7i -- 2.47.2