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.
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.
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.’
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.
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.
This field should contain ‘no’ if the module cannot be used in a
test directory created with gnulib-tool --create-testdir.
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.
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.
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.
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.
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
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"
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
When this field is omitted, it defaults to the union of the Link
field of the dependencies.
This field specifies the license that governs the source code parts of this module. See Copyright for details. Be sure to place, in every source code file, a copyright notice and the appropriate license notice, taken from the etc/license-notices/ directory.
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.