FYI: users should NOT call AM_AUTOMAKE_VERSION

[Alexandre Duret-Lutz]

Hi Germán,

I stumbled upon your tutorial today:
http://www.ubiobio.cl/~gpoo/documentos/autotools.pdf

(I'm currently writing one too, and also gathering a list of
other tutorials available.)

Unfortunately, there is a terrible recommendation inside:
calling AM_AUTOMAKE_VERSION to require some API version.

This is unfortunate for two reasons:

  1. AM_AUTOMAKE_VERSION is a private undocumented macro.

  2. The aim of AM_AUTOMAKE_VERSION is for the Automake macros
     to tell `automake' which version of Automake they come from.
     I.e. this ensure that `aclocal.m4' has been generated using
     the set of macros that come with the `automake' script.

     In the past people would get many weird behaviors because
     they simply forgot to run `aclocal' before `automake', and were
     using some old Automake macros with a newer `automake'.  Now
     this is diagnosed by mean of AM_AUTOMAKE_VERSION, which is called
     automatically by AM_INIT_AUTOMAKE.

     Calling AM_AUTOMAKE_VERSION by hand with some different number
     will cause unexpected diagnostics to be output (basically Automake
     will think you forgot to run aclocal).
    

There are two documented ways to require a minimum Automake
version: pass it to AM_INIT_AUTOMAKE, as in
  
  AM_INIT_AUTOMAKE([1.9 dist-bzip2])

Or require it locally in some Makefile with AUTOMAKE_OPTIONS:

  AUTOMAKE_OPTIONS = 1.9


Now I can understand that someone finding a macro named
AM_AUTOMAKE_VERSION could conclude that this macro can be used
to specify the version to use, rather than figuring that this is
used by Automake internally to tell itself which version it is!
So I'm installing the following patch on HEAD to help mistaken
people.


2005-01-13  Alexandre Duret-Lutz  <address@hidden>

        * m4/amversion.in (AM_AUTOMAKE_VERSION): Point users to
        AM_INIT_AUTOMAKE if the version passed is incorrect.
        * tests/version8.test: New file.
        * tests/Makefile.am (TESTS): Add version8.test.

Index: m4/amversion.in
===================================================================
RCS file: /cvs/automake/automake/m4/amversion.in,v
retrieving revision 1.7
diff -u -r1.7 amversion.in
--- m4/amversion.in     9 Jan 2005 14:46:21 -0000       1.7
+++ m4/amversion.in     13 Jan 2005 19:57:33 -0000
@@ -10,7 +10,14 @@
 # ----------------------------
 # Automake X.Y traces this macro to ensure aclocal.m4 has been
 # generated from the m4 files accompanying Automake X.Y.
-AC_DEFUN([AM_AUTOMAKE_VERSION], [am__api_version="@APIVERSION@"])
+# (This private macro should not be called outside this file.)
+AC_DEFUN([AM_AUTOMAKE_VERSION],
+[am__api_version='@APIVERSION@'
+dnl Some users find AM_AUTOMAKE_VERSION and mistake it for a way to
+dnl require some minimum version.  Point them to the right macro.
+m4_if([$1], address@hidden@], [],
+      [AC_FATAL([Do not call $0, use AM_INIT_AUTOMAKE([$1]).])])dnl
+])
 
 # AM_SET_CURRENT_AUTOMAKE_VERSION
 # -------------------------------
Index: tests/Makefile.am
===================================================================
RCS file: /cvs/automake/automake/tests/Makefile.am,v
retrieving revision 1.578
diff -u -r1.578 Makefile.am
--- tests/Makefile.am   3 Jan 2005 21:32:19 -0000       1.578
+++ tests/Makefile.am   13 Jan 2005 19:57:33 -0000
@@ -547,6 +547,7 @@
 version4.test \
 version6.test \
 version7.test \
+version8.test \
 vpath.test \
 vtexi.test \
 vtexi2.test \
Index: tests/version8.test
===================================================================
RCS file: tests/version8.test
diff -N tests/version8.test
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ tests/version8.test 13 Jan 2005 19:57:33 -0000
@@ -0,0 +1,28 @@
+#! /bin/sh
+# Copyright (C) 2005  Free Software Foundation, Inc.
+#
+# This file is part of GNU Automake.
+#
+# GNU Automake is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# GNU Automake is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Automake; see the file COPYING.  If not, write to
+# the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+# Calling AM_AUTOMAKE_VERSION by hand is a bug.
+
+. ./defs || exit 1
+
+set -e
+echo 'AM_AUTOMAKE_VERSION([1.9])' >>configure.in
+$ACLOCAL 2>stderr && exit 0
+$FGREP 'AM_INIT_AUTOMAKE([1.9])' stderr
-- 
Alexandre Duret-Lutz