FYI: Upgrading (Was: Re: Odd warning)

[Alexandre Duret-Lutz]

>>> "adl" == Alexandre Duret-Lutz <address@hidden> writes:

 adl> How about adding the appended section to the manual?

I'm checking it in (HEAD and branch-1-8).

2004-01-20  Alexandre Duret-Lutz  <address@hidden>

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

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.18.2.3
diff -u -r1.18.2.3 automake.texi
--- doc/automake.texi   7 Jan 2004 19:31:29 -0000       1.18.2.3
+++ doc/automake.texi   20 Jan 2004 21:47:13 -0000
@@ -108,6 +108,7 @@
 * 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 @@
 @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}:
@@ -6458,6 +6459,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.
+
address@hidden Upgrading
address@hidden Upgrading a Package to a Newer Automake Version
+
+Automake maintains three kind of files in a package.
+
address@hidden
address@hidden @file{aclocal.m4}
address@hidden @file{Makefile.in}s
address@hidden auxiliary tools like @file{install-sh} or @file{py-compile}
address@hidden itemize
+
address@hidden is generated by @command{aclocal} and contains some
+Automake-supplied M4 macros.  Auxiliary tools are installed by
address@hidden --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
+
address@hidden
+aclocal # with any option needed (such a -I m4)
+autoconf
+automake --add-missing --force-missing
address@hidden example
+
address@hidden
+or more conveniently:
+
address@hidden
+autoreconf -vfi
address@hidden 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
address@hidden
+
+Presently @command{automake} is able to diagnose situations where
address@hidden has been generated with another version of
address@hidden  However it never checks whether auxiliary scripts
+are up-to-date.  In other words, @command{automake} will tell you when
address@hidden 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
Index: doc/stamp-vti
===================================================================
RCS file: /cvs/automake/automake/doc/stamp-vti,v
retrieving revision 1.24.2.12
diff -u -r1.24.2.12 stamp-vti
--- doc/stamp-vti       12 Jan 2004 23:36:53 -0000      1.24.2.12
+++ doc/stamp-vti       20 Jan 2004 21:47:13 -0000
@@ -1,4 +1,4 @@
address@hidden UPDATED 7 January 2004
address@hidden UPDATED 20 January 2004
 @set UPDATED-MONTH January 2004
 @set EDITION 1.8.2a
 @set VERSION 1.8.2a
Index: doc/version.texi
===================================================================
RCS file: /cvs/automake/automake/doc/version.texi,v
retrieving revision 1.24.2.12
diff -u -r1.24.2.12 version.texi
--- doc/version.texi    12 Jan 2004 23:36:53 -0000      1.24.2.12
+++ doc/version.texi    20 Jan 2004 21:47:13 -0000
@@ -1,4 +1,4 @@
address@hidden UPDATED 7 January 2004
address@hidden UPDATED 20 January 2004
 @set UPDATED-MONTH January 2004
 @set EDITION 1.8.2a
 @set VERSION 1.8.2a
-- 
Alexandre Duret-Lutz