automake: Local Macros

1 
1 6.3.4 Handling Local Macros
1 ---------------------------
1 
1 Feature tests offered by Autoconf do not cover all needs.  People often
1 have to supplement existing tests with their own macros, or with
1 third-party macros.
1 
1    There are two ways to organize custom macros in a package.
1 
1    The first possibility (the historical practice) is to list all your
1 macros in ‘acinclude.m4’.  This file will be included in ‘aclocal.m4’
1 when you run ‘aclocal’, and its macro(s) will henceforth be visible to
1 ‘autoconf’.  However if it contains numerous macros, it will rapidly
1 become difficult to maintain, and it will be almost impossible to share
1 macros between packages.
1 
1    The second possibility, which we do recommend, is to write each macro
1 in its own file and gather all these files in a directory.  This
1 directory is usually called ‘m4/’.  Then it’s enough to update
1 ‘configure.ac’ by adding a proper call to ‘AC_CONFIG_MACRO_DIRS’:
1 
1      AC_CONFIG_MACRO_DIRS([m4])
1 
1    ‘aclocal’ will then take care of automatically adding ‘m4/’ to its
1 search path for m4 files.
1 
1    When ‘aclocal’ is run, it will build an ‘aclocal.m4’ that
1 ‘m4_include’s any file from ‘m4/’ that defines a required macro.  Macros
1 not found locally will still be searched in system-wide directories, as
1 explained in ⇒Macro Search Path.
1 
1    Custom macros should be distributed for the same reason that
1 ‘configure.ac’ is: so that other people have all the sources of your
1 package if they want to work on it.  Actually, this distribution happens
1 automatically because all ‘m4_include’d files are distributed.
1 
1    However there is no consensus on the distribution of third-party
1 macros that your package may use.  Many libraries install their own
11 macro in the system-wide ‘aclocal’ directory (⇒Extending
 aclocal).  For instance, Guile ships with a file called ‘guile.m4’
1 that contains the macro ‘GUILE_FLAGS’ that can be used to define setup
1 compiler and linker flags appropriate for using Guile.  Using
1 ‘GUILE_FLAGS’ in ‘configure.ac’ will cause ‘aclocal’ to copy ‘guile.m4’
1 into ‘aclocal.m4’, but as ‘guile.m4’ is not part of the project, it will
1 not be distributed.  Technically, that means a user who needs to rebuild
1 ‘aclocal.m4’ will have to install Guile first.  This is probably OK, if
1 Guile already is a requirement to build the package.  However, if Guile
1 is only an optional feature, or if your package might run on
1 architectures where Guile cannot be installed, this requirement will
1 hinder development.  An easy solution is to copy such third-party macros
1 in your local ‘m4/’ directory so they get distributed.
1 
1    Since Automake 1.10, ‘aclocal’ offers the option ‘--install’ to copy
1 these system-wide third-party macros in your local macro directory,
1 helping to solve the above problem.
1 
1    With this setup, system-wide macros will be copied to ‘m4/’ the first
1 time you run ‘aclocal’.  Then the locally installed macros will have
1 precedence over the system-wide installed macros each time ‘aclocal’ is
1 run again.
1 
1    One reason why you should keep ‘--install’ in the flags even after
1 the first run is that when you later edit ‘configure.ac’ and depend on a
1 new macro, this macro will be installed in your ‘m4/’ automatically.
1 Another one is that serial numbers (⇒Serials) can be used to
1 update the macros in your source tree automatically when new system-wide
1 versions are installed.  A serial number should be a single line of the
1 form
1 
1      #serial NNN
1 
1 where NNN contains only digits and dots.  It should appear in the M4
1 file before any macro definition.  It is a good practice to maintain a
1 serial number for each macro you distribute, even if you do not use the
1 ‘--install’ option of ‘aclocal’: this allows other people to use it.
1