4.5 Module description

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.

Description

This field should contain a concise description of the module's functionality. One sentence is enough. For example, if it defines a single function ‘frob’, the description can be ‘frob() function: frobnication.’ Gnulib's documentation generator will automatically convert the first part to a hyperlink when it has this form.

Status

This field is either empty/absent, or contains the word ‘obsolete’. In the latter case, gnulib-tool will, unless the option --with-obsolete is 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.’

Notice

This field contains text that gnulib-tool will show to the user when the module is used. This can be a status indicator like ‘This module is obsolete.’ or additional advice. Do not abuse this field.

Applicability

This field is either empty/absent, or contains the word ‘all’. It describes to which Makefile.am the module is applied. By default, a normal module is applied to source_base/Makefile.am (normally lib/Makefile.am), whereas a module ending in -tests is applied to tests_base/Makefile.am (normally 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.

Files

This field contains a newline separated list of the files that are part of the module. gnulib-tool copies 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 file.

Depends-on

This field contains a newline separated list of the modules that are required for the proper working of this module. gnulib-tool includes each required module automatically, unless it is specified with option --avoid or it is marked as obsolete and the option --with-obsolete is not given.

A test modules foo-tests implicitly depends on the corresponding non-test module foo. 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 configure.ac statements. For example:

          strtoull   [test $ac_cv_func_strtoumax = no]

Lines starting with # are recognized as comments and are ignored.

configure.ac-early

This field contains configure.ac stuff (Autoconf macro invocations and shell statements) that are logically placed early in the configure.ac file: right after the AC_PROG_CC invocation. This section is adequate for statements that modify CPPFLAGS, as these can affect the results of other Autoconf macros.

configure.ac

This field contains configure.ac stuff (Autoconf macro invocations and shell statements).

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.am

This field contains Makefile.am statements. Variables like lib_SOURCES are transformed to match the name of the library being built in that directory. For example, lib_SOURCES may become 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.c compiled unconditionally is to write

          lib_SOURCES += foo.c

Include

This field contains the preprocessor statements that users of the module need to add to their source code files. Typically it's a single include statement. A shorthand is allowed: You don't need to write the word “#include”, just the name of the include file in the way it will appear in an include statement. Example:

          "foo.h"

Link

This field contains the set of libraries that are needed when linking libraries or executables that use this module. Often this will be written as a reference to a Makefile variable. Please write them one per line, so that gnulib-tool can remove duplicates when presenting a summary to the user. Example:

          $(POW_LIBM)
          $(LTLIBICONV) when linking with libtool, $(LIBICONV) otherwise

License

This field specifies the license that governs the source code parts of this module. See Copyright for details.

Maintainer

This field specifies the persons who have a definitive say about proposed changes to this module. You don't need to mention email addresses here: they can be inferred from the ChangeLog file.

Please put at least one person here. We don't like unmaintained modules.