---

4.6 Autoconf macros

For a module foo, an Autoconf macro file m4/foo.m4 is typically created when the Autoconf macro invocations for the module are longer than one or two lines.

The name of the main entry point into this Autoconf macro file is typically gl_FOO. For modules outside Gnulib that are not likely to be moved into Gnulib, please use a prefix specific to your package: gt_ for GNU gettext, cu_ for GNU coreutils, etc.

For modules that define a function foo, the entry point is called gl_FUNC_FOO instead of gl_FOO. For modules that provide a header file with multiple functions, say foo.h, the entry point is called gl_FOO_H or gl_HEADER_FOO_H. This convention is useful because sometimes a header and a function name coincide (for example, fcntl and fcntl.h).

For modules that provide a replacement, it is useful to split the Autoconf macro into two macro definitions: one that detects whether the replacement is needed and requests the replacement by setting a HAVE_FOO variable to 0 or a REPLACE_FOO variable to 1 (this is the entry point, say gl_FUNC_FOO), and one that arranges for the macros needed by the replacement code lib/foo.c (typically called gl_PREREQ_FOO). The reason of this separation is

1. to make it easy to update the Autoconf macros when you have modified the source code file: after changing lib/foo.c, all you have to review is the Depends-on section of the module description and the gl_PREREQ_FOO macro in the Autoconf macro file.
2. The Autoconf macros are often large enough that splitting them eases maintenance.

Autoconf macro files in Gnulib all start with a header consisting of

1. A comment line with the file name. This is useful because in some cases the generated aclocal.m4 file does not contain a reference to the .m4 file but its entire contents. The comment makes it clear which .m4 file is where in the aclocal.m4 file.
2. A comment line with a serial number. This is useful when people use the ‘aclocal --install’ command. aclocal will then refrain from copying a file with a smaller serial number onto a file with a larger serial number. The serial number should be a positive integer on the main branch, or a positive fractional number on a stable branch.
3. The copyright and license header, as usual.