automake-1.16: Extending aclocal
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’ (⇒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 (⇒
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
(⇒(autoconf)Macro Definitions). The ‘aclocal’ programs also
understands ‘AC_REQUIRE’ (⇒(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’ warns about all underquoted
calls to ‘AC_DEFUN’. We realize this annoys some 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’ (⇒Future of aclocal) will have to temporarily include
all of these third party ‘.m4’ files, maybe several times, even
including files that end up not being needed. Doing so should alleviate
many problems of the current implementation; however, it requires a
stricter style from 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 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; ⇒Local Macros.
Info Catalog
automake-1.16: Macro Search Path
automake-1.16: aclocal Invocation
automake-1.16: Local Macros