(automake-1.16.info)Extending aclocal

---

Next: Local Macros Prev: Macro Search Path Up: aclocal Invocation

---

Enter node , (file) or (file)node

6.3.3 Writing your own aclocal macros
-------------------------------------

The ‘aclocal’ program doesn’t have any built-in knowledge of any macros,
so it is easy to extend it with your own macros.

   This can be used by libraries that want to supply their own Autoconf
macros for use by other programs.  For instance, the ‘gettext’ library
supplies a macro ‘AM_GNU_GETTEXT’ that should be used by any package
using ‘gettext’.  When the library is installed, it installs this macro
so that ‘aclocal’ will find it.

   A macro file’s name should end in ‘.m4’.  Such files should be
installed in ‘$(datadir)/aclocal’.  This is as simple as writing:

     aclocaldir = $(datadir)/aclocal
     aclocal_DATA = mymacro.m4 myothermacro.m4

Please do use ‘$(datadir)/aclocal’, and not something based on the
result of ‘aclocal --print-ac-dir’ (Note: Hard-Coded Install Paths,
for arguments).  It might also be helpful to suggest to the user to add
the ‘$(datadir)/aclocal’ directory to his ‘ACLOCAL_PATH’ variable (Note:
ACLOCAL_PATH) so that ‘aclocal’ will find the ‘.m4’ files installed by
your package automatically.

   A file of macros should be a series of properly quoted ‘AC_DEFUN’’s
(Note: (autoconf)Macro Definitions).  The ‘aclocal’ programs also
understands ‘AC_REQUIRE’ (Note: (autoconf)Prerequisite Macros), 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 ‘AC_PREREQ’
should be done inside the defined macro, not at the beginning of the
file.

   Starting with Automake 1.8, ‘aclocal’ will warn about all underquoted
calls to ‘AC_DEFUN’.  We realize this will annoy a lot of people,
because ‘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 ‘aclocal’ (Note: Future of aclocal) will have to
temporarily include all of these third party ‘.m4’ files, maybe several
times, including even files that are not actually needed.  Doing so
should alleviate many problems 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,

     # bad style
     AC_PREREQ(2.68)
     AC_DEFUN(AX_FOOBAR,
     [AC_REQUIRE([AX_SOMETHING])dnl
     AX_FOO
     AX_BAR
     ])

should be rewritten as

     AC_DEFUN([AX_FOOBAR],
     [AC_PREREQ([2.68])dnl
     AC_REQUIRE([AX_SOMETHING])dnl
     AX_FOO
     AX_BAR
     ])

   Wrapping the ‘AC_PREREQ’ call inside the macro ensures that Autoconf
2.68 will not be required if ‘AX_FOOBAR’ is not actually used.  Most
importantly, quoting the first argument of ‘AC_DEFUN’ allows the macro
to be redefined or included twice (otherwise this first argument would
be expanded during the second definition).  For consistency we like to
quote even arguments such as ‘2.68’ that do not require it.

   If you have been directed here by the ‘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 latest version
of the macro and that the problem hasn’t already been reported before
doing so: people tend to work faster when they aren’t flooded by mails.

   Another situation where ‘aclocal’ is commonly used is to manage
macros that are used locally by the package, Note: Local Macros.