[bug#68674] recommending autoreconf -f when version mismatch

[Karl Berry]

The patch below changes the wording of the "version mismatch" errors to
recommend running autoreconf -f. If anyone sees any problems with the
idea, or the wording, let me know.

I discovered this when trying out the last automake pretest. After
configuring with the new automake, I then went back to the released
automake version, provoking the error:

  configure.ac:26: error: version mismatch.  This is Automake 1.16.5,
  configure.ac:26: but the definition used by this AM_INIT_AUTOMAKE
  configure.ac:26: comes from Automake 1.16j.  You should recreate
  configure.ac:26: aclocal.m4 with aclocal and run automake again.

However, running aclocal && automake did not change anything. The 
problem was not (just) aclocal.m4, but the autom4te.cache/ files, which
aclocal and automake do not touch.

The new message is:

  configure.ac:6: error: version mismatch.  This is Automake 1.16.90,
  configure.ac:6: but the definition used by this AM_INIT_AUTOMAKE
  configure.ac:6: comes from Automake 1.16.5.  You should run
  configure.ac:6: autoreconf -f (or otherwise erase all old files, run
  configure.ac:6: aclocal to recreate aclocal.m4, and rerun automake).

I also tweaked the manual to suggest autoreconf in another place.

Comments/corrections/criticisms/whatever welcome ... --thanks, karl.

-----------------------------------------------------------------------------
automake: recommend autoreconf -f with version mismatches.

* bin/automake.in (scan_autoconf_traces): change error
to suggest running autoreconf -f. The version mismatch is
most likely to happen due to the cache files, which
aclocal && automake (the previous recommendation) does not delete.
(scan_autoconf_files): likewise.
* doc/automake.texi (Auto-generating aclocal.m4): mention autoreconf.
Other minor wording changes.
diff --git a/bin/automake.in b/bin/automake.in
index f568773eb..0499d81eb 100644
--- a/bin/automake.in
+++ b/bin/automake.in
@@ -5442,8 +5442,9 @@ sub scan_autoconf_traces
          error ($where,
                 "version mismatch.  This is Automake $VERSION,\n" .
                 "but the definition used by this AM_INIT_AUTOMAKE\n" .
-                "comes from Automake $args[1].  You should recreate\n" .
-                "aclocal.m4 with aclocal and run automake again.\n",
+                "comes from Automake $args[1].  You should run\n" .
+                "autoreconf -f (or otherwise erase all old files,\n" .
+                "recreate aclocal.m4 with aclocal, and rerun automake).",
                 # $? = 63 is used to indicate version mismatch to missing.
                 exit_code => 63)
            if $VERSION ne $args[1];
@@ -5621,9 +5622,10 @@ sub scan_autoconf_files ()
          if (-f 'aclocal.m4')
            {
              error ($seen_init_automake,
-                    "your implementation of AM_INIT_AUTOMAKE comes from " .
-                    "an\nold Automake version.  You should recreate " .
-                    "aclocal.m4\nwith aclocal and run automake again",
+                     "your implementation of AM_INIT_AUTOMAKE comes from\n" .
+                     "an old Automake version.  You should run\n" .
+                     "autoreconf -f (or otherwise erase all old files, run\n" .
+                     "aclocal to remake aclocal.m4, and rerun automake).",
                     # $? = 63 is used to indicate version mismatch to missing.
                     exit_code => 63);
            }
@@ -5632,8 +5634,8 @@ sub scan_autoconf_files ()
              error ($seen_init_automake,
                     "no proper implementation of AM_INIT_AUTOMAKE was " .
                     "found,\nprobably because aclocal.m4 is missing.\n" .
-                    "You should run aclocal to create this file, then\n" .
-                    "run automake again");
+                    "You should run autoreconf -f (or aclocal to create\n" .
+                    "this file, then rerun automake).");
            }
        }
     }
diff --git a/doc/automake.texi b/doc/automake.texi
index ecefe2dc6..d30905e0f 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3276,7 +3276,7 @@ macros installed in a system-wide directory; 
@pxref{aclocal Invocation}).

 @node aclocal Invocation
 @section Auto-generating aclocal.m4
-@c This node used to be named "Invoking automake".  This @anchor
+@c This node used to be named "Invoking aclocal".  This @anchor
 @c allows old links to still work.
 @anchor{Invoking aclocal}

@@ -3335,9 +3335,15 @@ autoconf, The Autoconf Manual}) in order to trace the 
macros that are
 used, and omit from @file{aclocal.m4} all macros that are mentioned
 but otherwise unexpanded (this can happen when a macro is called
 conditionally).  @command{autom4te} is expected to be in the
-@env{PATH}, just as @command{autoconf}.  Its location can be
+@env{PATH}, just like @command{autoconf}.  Its location can be
 overridden using the @env{AUTOM4TE} environment variable.

+Although this section explains the details of @command{aclocal}, in
+practice it is usually simpler to run @command{autoreconf}, instead of
+worrying about the required order of the various tools
+(@pxref{autoreconf Invocation, , Using @command{autoreconf},
+autoconf, The Autoconf Manual}).
+
 @menu
 * aclocal Options::             Options supported by aclocal
 * Macro Search Path::           How aclocal finds .m4 files
@@ -5686,13 +5692,13 @@ this issue because older Automake versions used to call
 @command{libtoolize}.

 Since Automake 1.6, it has been decided that running
-@command{libtoolize} was none of Automake's business.  Instead, that
+@command{libtoolize} was not Automake's business.  Instead, that
 functionality has been moved into the @command{autoreconf} command
 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
 The Autoconf Manual}).  If you do not want to remember what to run and
-when, just learn the @command{autoreconf} command.  Hopefully,
-replacing existing @file{bootstrap} or @file{autogen.sh} scripts by
-a call to @command{autoreconf} should also free you from any similar
+when, just remember the @command{autoreconf} command.  Hopefully,
+replacing existing @file{bootstrap} or @file{autogen.sh} scripts by a
+call to @command{autoreconf} should also free you from any similar
 incompatible change in the future.

 @node Objects created both with libtool and without
@@ -8092,8 +8098,8 @@ Here are the current support plans.
 Currently Automake provides support for Texinfo and man pages.

 @menu
-* Texinfo::                     Texinfo
-* Man Pages::                   Man pages
+* Texinfo::
+* Man Pages::
 @end menu


@@ -8214,7 +8220,7 @@ included when @command{automake} is invoked with the
 If you have multiple Texinfo files, and you want to use the
 @file{version.texi} feature, then you have to have a separate version
 file for each Texinfo file.  Automake will treat any include in a
-Texinfo file that matches @file{vers*.texi} just as an automatically
+Texinfo file that matches @file{vers*.texi} just like an automatically
 generated version file.

 Often an Info file depends on more than one @file{.texi} file.  For

compile finished at Mon Jan 22 18:13:52 2024