* doc/automake.texi (Upgrading): New node.

diff --git a/ChangeLog b/ChangeLog
index 2e9e1a2a69c5ea79998148513a7f0e618c6baf33..0403552717853bc3df1e37a594b0b7c8f3db87ec 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2004-01-20  Alexandre Duret-Lutz  <adl@gnu.org>
+
+       * doc/automake.texi (Upgrading): New node.
+
 2004-01-20  Gary V. Vaughan  <gary@gnu.org>
 
        * automake.in (scan_autoconf_traces): AC_LIBTOOL_TAGS can be

diff --git a/doc/automake.texi b/doc/automake.texi
index ae15b13db019f50802b1ab2d9e3569288a71b778..ae2ae5589380891955a3b6b649a8e87919bcc157 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -108,6 +108,7 @@ published by the Free Software Foundation raise funds for
 * Extending::                   Extending Automake
 * Distributing::                Distributing the Makefile.in
 * API versioning::              About compatibility between Automake versions
+* Upgrading::                   Upgrading to a Newer Automake Version
 * FAQ::                         Frequently Asked Questions
 * Copying This Manual::         How to make copies of this manual
 * Indices::                     Indices of variables, macros, and concepts
@@ -6415,13 +6416,13 @@ means you can install several versions of Automake in the same
 @samp{$PATH}.  Furthermore, @file{Makefile}'s generated by Automake 1.6
 will use @samp{automake-1.6} explicitly in their rebuild rules.
 
-Note that @samp{1.6} in @samp{automake-1.6} is Automake's API version,
+The number @samp{1.6} in @samp{automake-1.6} is Automake's API version,
 not Automake's version.  If a bug fix release is made, for instance
 Automake 1.6.1, the API version will remain 1.6.  This means that a
 package which work with Automake 1.6 should also work with 1.6.1; after
 all, this is what people expect from bug fix releases.
 
-Note that if your package relies on a feature or a bug fix introduced in
+If your package relies on a feature or a bug fix introduced in
 a release, you can pass this version as an option to Automake to ensure
 older releases will not be used.  For instance, use this in your
 @file{configure.ac}:
@@ -6459,6 +6460,62 @@ If it turns out you need to use such a undocumented feature, contact
 @email{automake@@gnu.org} and try to get it documented and exercised by
 the test-suite.
 
+@node Upgrading
+@chapter Upgrading a Package to a Newer Automake Version
+
+Automake maintains three kind of files in a package.
+
+@itemize
+@item @file{aclocal.m4}
+@item @file{Makefile.in}s
+@item auxiliary tools like @file{install-sh} or @file{py-compile}
+@end itemize
+
+@file{aclocal.m4} is generated by @command{aclocal} and contains some
+Automake-supplied M4 macros.  Auxiliary tools are installed by
+@samp{automake --add-missing} when needed.  @file{Makefile.in}s are
+built from @file{Makefile.am} by @command{automake}, and rely on the
+definitions of the M4 macros put in @file{aclocal.m4} as well as the
+behavior of the auxiliary tools installed.
+
+Because all these files are closely related, it is important to
+regenerate all of them when upgrading to a newer Automake release.
+The usual way to do that is
+
+@example
+aclocal # with any option needed (such a -I m4)
+autoconf
+automake --add-missing --force-missing
+@end example
+
+@noindent
+or more conveniently:
+
+@example
+autoreconf -vfi
+@end example
+
+The use of @code{--force-missing} ensures that auxiliary tools will be
+overridden by new versions (@pxref{Invoking Automake}).
+
+It is important to regenerate all these files each time Automake is
+upgraded, even between bug fixes releases.  For instance it is not
+unusual for a bug fix to involve changes to both the rules generated
+in @file{Makefile.in} and the supporting M4 macros copied to
+@file{aclocal.m4}.
+
+Presently @command{automake} is able to diagnose situations where
+@file{aclocal.m4} has been generated with another version of
+@command{aclocal}.  However it never checks whether auxiliary scripts
+are up-to-date.  In other words, @command{automake} will tell you when
+@command{aclocal} needs to be rerun, but it will never diagnose a
+missing @code{--force-missing}.
+
+Before upgrading to a new major release, it is a good idea to read the
+file @file{NEWS}.  This file lists all changes between releases: new
+features, obsolete constructs, known incompatibilities, and
+workarounds.
+
 @node FAQ
 @chapter Frequently Asked Questions about Automake
 

diff --git a/doc/stamp-vti b/doc/stamp-vti
index 436217c02361bb510afcba6ff6c6aa848c341251..0c96585378fb53a20bd227accebbe7d1711eb493 100644 (file)
--- a/doc/stamp-vti
+++ b/doc/stamp-vti
@@ -1,4 +1,4 @@
-@set UPDATED 7 January 2004
+@set UPDATED 20 January 2004
 @set UPDATED-MONTH January 2004
 @set EDITION 1.8a
 @set VERSION 1.8a

diff --git a/doc/version.texi b/doc/version.texi
index 436217c02361bb510afcba6ff6c6aa848c341251..0c96585378fb53a20bd227accebbe7d1711eb493 100644 (file)
--- a/doc/version.texi
+++ b/doc/version.texi
@@ -1,4 +1,4 @@
-@set UPDATED 7 January 2004
+@set UPDATED 20 January 2004
 @set UPDATED-MONTH January 2004
 @set EDITION 1.8a
 @set VERSION 1.8a