---

2.5 Modules

Gnulib is divided into modules. Every module implements a single facility. Modules can depend on other modules.

A module consists of a number of files and a module description. The files are copied by gnulib-tool into the package that will use it, usually verbatim, without changes. Source code files (.h, .c files) reside in the lib/ subdirectory. Autoconf macro files reside in the m4/ subdirectory. Build scripts reside in the build-aux/ subdirectory.

The module description contains the list of files; gnulib-tool copies these files. It contains the module’s dependencies; gnulib-tool installs them as well. It also contains the autoconf macro invocation (usually a single line or nothing at all); gnulib-tool ensures this is invoked from the package’s configure.ac file. And also a Makefile.am snippet; gnulib-tool collects these into a Makefile.am for the tailored Gnulib part. The module description and include file specification are for documentation purposes; they are combined into MODULES.html.

The module system serves two purposes:

1. It ensures consistency of the used autoconf macros and Makefile.am rules with the source code. For example, source code which uses the getopt_long function—this is a common way to implement parsing of command line options in a way that complies with the GNU standards—needs the source code (lib/getopt.c and others), the autoconf macro which detects whether the system’s libc already has this function (in m4/getopt.m4), and a few Makefile.am lines that create the substitute getopt.h if not. These three pieces belong together. They cannot be used without each other. The module description and gnulib-tool ensure that they are copied altogether into the destination package.
2. It allows for scalability. It is well-known since the inception of the MODULA-2 language around 1978 that dissection into modules with dependencies allows for building large sets of code in a maintainable way. The maintainability comes from the facts that:
   • Every module has a single purpose; you don’t worry about other parts of the program while creating, reading or modifying the code of a module.
   • The code you have to read in order to understand a module is limited to the source of the module and the .h files of the modules listed as dependencies. It is for this reason also that we recommend to put the comments describing the functions exported by a module into its .h file.

   In other words, the module is the elementary unit of code in Gnulib, comparable to a class in object-oriented languages like Java or C#.

The module system is the basis of gnulib-tool. When gnulib-tool copies a part of Gnulib into a package, it first compiles a module list, starting with the requested modules and adding all the dependencies, and then collects the files, configure.ac snippets and Makefile.am snippets.