For the module description, you can start from an existing module's description, or from a blank one: module/TEMPLATE for a normal module, or module/TEMPLATE-TESTS for a unit test module. Some more fields are possible but rarely used. Use module/TEMPLATE-EXTENDED if you want to use one of them.
Module descriptions have the following fields. Absent fields are equivalent to fields with empty contents.
--with-obsoleteis given, omit it when it used as a dependency. It is good practice to also notify the user about an obsolete module. This is done by putting into the ‘Notice’ section (see below) text like ‘This module is obsolete.’
Makefile.amthe module is applied. By default, a normal module is applied to source_base
lib/Makefile.am), whereas a module ending in
-testsis applied to tests_base
tests/Makefile.am). If this field is ‘all’, it is applied to both
Makefile.ams. This is useful for modules which provide Makefile.am macros rather than compiled source code.
gnulib-toolcopies these files into the package that uses the module.
This list is typically ordered by importance: First comes the header file, then the implementation files, then other files.
It is possible to have the same file mentioned in multiple modules. That is,
if the maintainers of that module agree on the purpose and future of said
gnulib-toolincludes each required module automatically, unless it is specified with option
--avoidor it is marked as obsolete and the option
--with-obsoleteis not given.
A test modules
foo-tests implicity depends on the corresponding non-test
foo implicitly depends on
foo-tests if the
latter exists and if the option
--with-tests has been given.
Tests modules can depend on non-tests modules. Non-tests modules should not depend on tests modules. (Recall that tests modules are built in a separate directory.)
Each listed required module may be declared a conditional dependency. This
is indicated by placing the condition for the dependency on the same line,
enclosed in brackets, after the name of the required module. The condition
is a shell expression that is run after the module's
statements. For example:
strtoull [test $ac_cv_func_strtoumax = no]
Lines starting with
# are recognized as comments and are ignored.
AC_PROG_CCinvocation. This section is adequate for statements that modify
CPPFLAGS, as these can affect the results of other Autoconf macros.
It is forbidden to add items to the
CPPFLAGS variable here, other than
temporarily, as these could affect the results of other Autoconf macros.
We avoid adding items to the
LIBS variable, other than temporarily.
Instead, the module can export an Autoconf-substituted variable that contains
link options. The user of the module can then decide to which executables
to apply which link options. Recall that a package can build executables of
different kinds and purposes; having all executables link against all
libraries is inappropriate.
If the statements in this section grow larger than a couple of lines, we
recommend moving them to a
.m4 file of their own.
Makefile.amstatements. Variables like
lib_SOURCESare transformed to match the name of the library being built in that directory. For example,
libgnu_a_SOURCES(for a plain library) or
libgnu_la_SOURCES(for a libtool library). Therefore, the normal way of having an implementation file
lib/foo.ccompiled unconditionally is to write
lib_SOURCES += foo.c
$(POW_LIBM) $(LTLIBICONV) when linking with libtool, $(LIBICONV) otherwise
Please put at least one person here. We don't like unmaintained modules.