automake: Extending aclocal

1 
1 6.3.3 Writing your own aclocal macros
1 -------------------------------------
1 
1 The ‘aclocal’ program doesn’t have any built-in knowledge of any macros,
1 so it is easy to extend it with your own macros.
1 
1    This can be used by libraries that want to supply their own Autoconf
1 macros for use by other programs.  For instance, the ‘gettext’ library
1 supplies a macro ‘AM_GNU_GETTEXT’ that should be used by any package
1 using ‘gettext’.  When the library is installed, it installs this macro
1 so that ‘aclocal’ will find it.
1 
1    A macro file’s name should end in ‘.m4’.  Such files should be
1 installed in ‘$(datadir)/aclocal’.  This is as simple as writing:
1 
1      aclocaldir = $(datadir)/aclocal
1      aclocal_DATA = mymacro.m4 myothermacro.m4
1 
1 Please do use ‘$(datadir)/aclocal’, and not something based on the
1 result of ‘aclocal --print-ac-dir’ (⇒Hard-Coded Install Paths,
1 for arguments).  It might also be helpful to suggest to the user to add
11 the ‘$(datadir)/aclocal’ directory to his ‘ACLOCAL_PATH’ variable (⇒
 ACLOCAL_PATH) so that ‘aclocal’ will find the ‘.m4’ files installed by
1 your package automatically.
1 
1    A file of macros should be a series of properly quoted ‘AC_DEFUN’’s
1 (⇒(autoconf)Macro Definitions).  The ‘aclocal’ programs also
1 understands ‘AC_REQUIRE’ (⇒(autoconf)Prerequisite Macros), so it
1 is safe to put each macro in a separate file.  Each file should have no
1 side effects but macro definitions.  Especially, any call to ‘AC_PREREQ’
1 should be done inside the defined macro, not at the beginning of the
1 file.
1 
1    Starting with Automake 1.8, ‘aclocal’ will warn about all underquoted
1 calls to ‘AC_DEFUN’.  We realize this will annoy a lot of people,
1 because ‘aclocal’ was not so strict in the past and many third party
1 macros are underquoted; and we have to apologize for this temporary
1 inconvenience.  The reason we have to be stricter is that a future
1 implementation of ‘aclocal’ (⇒Future of aclocal) will have to
1 temporarily include all of these third party ‘.m4’ files, maybe several
1 times, including even files that are not actually needed.  Doing so
1 should alleviate many problems of the current implementation, however it
1 requires a stricter style from the macro authors.  Hopefully it is easy
1 to revise the existing macros.  For instance,
1 
1      # bad style
1      AC_PREREQ(2.68)
1      AC_DEFUN(AX_FOOBAR,
1      [AC_REQUIRE([AX_SOMETHING])dnl
1      AX_FOO
1      AX_BAR
1      ])
1 
1 should be rewritten as
1 
1      AC_DEFUN([AX_FOOBAR],
1      [AC_PREREQ([2.68])dnl
1      AC_REQUIRE([AX_SOMETHING])dnl
1      AX_FOO
1      AX_BAR
1      ])
1 
1    Wrapping the ‘AC_PREREQ’ call inside the macro ensures that Autoconf
1 2.68 will not be required if ‘AX_FOOBAR’ is not actually used.  Most
1 importantly, quoting the first argument of ‘AC_DEFUN’ allows the macro
1 to be redefined or included twice (otherwise this first argument would
1 be expanded during the second definition).  For consistency we like to
1 quote even arguments such as ‘2.68’ that do not require it.
1 
1    If you have been directed here by the ‘aclocal’ diagnostic but are
1 not the maintainer of the implicated macro, you will want to contact the
1 maintainer of that macro.  Please make sure you have the latest version
1 of the macro and that the problem hasn’t already been reported before
1 doing so: people tend to work faster when they aren’t flooded by mails.
1 
1    Another situation where ‘aclocal’ is commonly used is to manage
1 macros that are used locally by the package, ⇒Local Macros.
1