FYI: underquoted AC_DEFUN warning

[Alexandre Duret-Lutz]

As discussed in the "aclocal --trace" thread, I'm checking this in
on HEAD.

2003-08-31  Alexandre Duret-Lutz  <address@hidden>

        * aclocal.in (scan_file): Warn about underquoted AC_DEFUN.
        ($underquoted_manual_once): New variable.

Index: aclocal.in
===================================================================
RCS file: /cvs/automake/automake/aclocal.in,v
retrieving revision 1.87
diff -u -r1.87 aclocal.in
--- aclocal.in  28 Aug 2003 22:49:58 -0000      1.87
+++ aclocal.in  31 Aug 2003 21:11:23 -0000
@@ -426,6 +426,9 @@
     }
 }
 
+# Point to the documentation for underquoted AC_DEFUN only once.
+my $underquoted_manual_once = 0;
+
 # Scan a single M4 file.  Return contents.
 sub scan_file ($)
 {
@@ -444,6 +447,15 @@
 
       if (/$ac_defun_rx/)
        {
+         if (! defined $1)
+           {
+             print STDERR "$file:$.: underquoted definition of $2\n";
+             print STDERR "$file:$.: run info '(automake)Extending aclocal'\n"
+               . "or see http://sources.redhat.com/automake/";
+               . "automake.html#Extending%20aclocal\n"
+               unless $underquoted_manual_once;
+             $underquoted_manual_once = 1;
+           }
          if (! defined $map{$1 || $2})
            {
              print STDERR "aclocal: found macro $1 in $file: $.\n"
Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.350
diff -u -r1.350 automake.texi
--- automake.texi       24 Aug 2003 02:00:55 -0000      1.350
+++ automake.texi       31 Aug 2003 21:11:28 -0000
@@ -1778,12 +1778,6 @@
 any package using @command{gettext}.  When the library is installed, it
 installs this macro so that @command{aclocal} will find it.
 
-A file of macros should be a series of @code{AC_DEFUN}'s.  The
address@hidden programs also understands @code{AC_REQUIRE}, so it is
-safe to put each macro in a separate file.  @xref{Prerequisite Macros, ,
-, autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
-autoconf, The Autoconf Manual}.
-
 A macro file's name should end in @file{.m4}.  Such files should be
 installed in @file{$(datadir)/aclocal}.  This is as simple as writing:
 
@@ -1792,6 +1786,64 @@
 aclocal_DATA = mymacro.m4 myothermacro.m4
 @end example
 
+A file of macros should be a series of properly quoted
address@hidden's (@pxref{Macro Definitions, , , autoconf, The
+Autoconf Manual}).  The @command{aclocal} programs also understands
address@hidden (@pxref{Prerequisite Macros, , , autoconf, The
+Autoconf Manual}), so it is safe to put each macro in a separate file.
+Each file should have no side effects but macro definitions.
+Especially, any call to @code{AC_PREREQ} should be done inside the
+defined macro, not at the beginning of the file.
+
address@hidden underquoted AC_DEFUN
address@hidden AC_DEFUN
address@hidden AC_PREREQ
+
+Starting with Automake 1.8, @command{aclocal} will warn about all
+underquoted calls to @code{AC_DEFUN}.  We realize this will annoy a
+lot of people, because @command{aclocal} was not so strict in the past
+and many third party macros are underquoted; and we have to apologize
+for this temporary inconvenience.  The reason we have to be stricter
+is that a future implementation of @command{aclocal} (@pxref{Future of
+aclocal}) will have to temporary include all these third party
address@hidden files, maybe several times, even those which are not
+actually needed.  Doing so should alleviate many problem of the
+current implementation, however it requires a stricter style from the
+macro authors.  Hopefully it is easy to revise the existing macros.
+For instance
address@hidden
+# bad style
+AC_PREREQ(2.57)
+AC_DEFUN(AX_FOOBAR,
+[AC_REQUIRE([AX_SOMETHING])dnl
+AX_FOO
+AX_BAR
+])
address@hidden example
address@hidden
+should be rewritten as
address@hidden
+AC_DEFUN([AX_FOOBAR],
+[AC_PREREQ(2.57)dnl
+AC_REQUIRE([AX_SOMETHING])dnl
+AX_FOO
+AX_BAR
+])
address@hidden example
+
+Wrapping the @code{AC_PREREQ} call inside the macro ensures that
+Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
+used.  Most importantly, quoting the first argument of @code{AC_DEFUN}
+allows the macro to be redefined or included twice (otherwise this
+first argument would be expansed during the second definition).
+
+If you have been directed here by the @command{aclocal} diagnostic but
+are not the maintainer of the implicated macro, you will want to
+contact the maintainer of that macro.  Please make sure you have the
+last version of the macro and that the problem already hasn't been
+reported before doing so: people tend to work faster when they aren't
+flooded by mails.
+
 Another situation where @command{aclocal} is commonly used is to
 manage macros which are used locally by the package, @ref{Local
 Macros}.
@@ -6582,4 +6634,4 @@
 @c  LocalWords:  DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
 @c  LocalWords:  LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
 @c  LocalWords:  WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
address@hidden  LocalWords:  mymodule timestamps timestamp
address@hidden  LocalWords:  mymodule timestamps timestamp underquoted
-- 
Alexandre Duret-Lutz