diff options
| -rw-r--r-- | NEWS | 10 | ||||
| -rw-r--r-- | THANKS | 1 | ||||
| -rw-r--r-- | doc/automake.texi | 56 |
3 files changed, 52 insertions, 15 deletions
@@ -60,6 +60,16 @@ New in 1.13.2: category. You are advised to simply use the '.texi' extension instead. +* Documentation fixes: + + - The long-deprecated but still supported two-arguments invocation form + of AM_INIT_AUTOMAKE is documented once again. This seems the sanest + thing to do, given that support for such an usage might need to remain + in place for a unspecified amount of time in order to cater for people + who want to define the version number for their package dynamically at + configure runtime (unfortunately, Autoconf does not yet support this + scenario, so we cannot delegate the work to it). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ New in 1.13.1: @@ -91,6 +91,7 @@ Dennis Schridde devurandom@gmx.net Derek R. Price derek.price@openavenue.com Diab Jerius djerius@cfa.harvard.edu Didier Cassirame faded@free.fr +Diego Elio Pettenò flameeyes@flameeyes.eu Dieter Baron dillo@stieltjes.smc.univie.ac.at Dieter Jurzitza DJurzitza@harmanbecker.com Дилян Палаузов dilyan.palauzov@aegee.org diff --git a/doc/automake.texi b/doc/automake.texi index b4dad5c08..64bde411b 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -3896,19 +3896,25 @@ Automake ships with several Autoconf macros that you can use from your Runs many macros required for proper operation of the generated Makefiles. @vindex AUTOMAKE_OPTIONS -@code{AM_INIT_AUTOMAKE} is called with a single argument: a space-separated -list of Automake options that should be applied to every @file{Makefile.am} -in the tree. The effect is as if each option were listed in -@code{AUTOMAKE_OPTIONS} (@pxref{Options}). - -@c FIXME: Remove this "modernization advice" in Automake 1.14 (and adjust -@c FIXME: the error message in m4/init.m4:AM_INIT_AUTOMAKE accordingly). +Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a +space-separated list of Automake options that should be applied to +every @file{Makefile.am} in the tree. The effect is as if +each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}). @acindex AC_INIT -This macro could once (before Automake 1.13) also be called in the -@emph{now obsolete and completely unsupported} form +This macro can also be called in another, @emph{deprecated} form: @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form, -there were two required arguments: the package and the version number. +there are two required arguments: the package and the version number. +This usage is mostly obsolete because the @var{package} and @var{version} +can be obtained from Autoconf's @code{AC_INIT} macro. However, +differently from what happens for @code{AC_INIT} invocations, this +@code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions +in the @code{PACKAGE} and @code{VERSION} arguments, and this can be +still be useful in some selected situations. Our hope is that future +Autoconf versions will improve their support for package versions +defined dynamically at configure runtime; when (and if) this happens, +support for the two-args @code{AM_INIT_AUTOMAKE} invocation will likely +be removed from Automake. @anchor{Modernize AM_INIT_AUTOMAKE invocation} If your @file{configure.ac} has: @@ -3919,8 +3925,7 @@ AM_INIT_AUTOMAKE([mumble], [1.5]) @end example @noindent -you must modernize it as follows in order to make it work with Automake -1.13 or later: +you should modernize it as follows: @example AC_INIT([mumble], [1.5]) @@ -9924,8 +9929,27 @@ be read as a side effect of running @command{configure}, like @file{version.sh} in the example above. Speaking of @file{version.sh} scripts, we recommend against them -today. We recommend that @file{version.sh} be replaced by an M4 file -that is included by @file{configure.ac}: +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 +@command{automake} cannot track dependencies (listing @file{version.sh} +in @command{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]) @@ -9939,7 +9963,9 @@ Here @file{version.m4} could contain something like @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this second form is that @command{automake} will take care of the dependencies when defining the rebuild rule, and will also distribute -the file automatically. +the file automatically. An inconvenience is that @command{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 |