---

5 Extending Gnulib

Gnulib modules are intended to be suitable for widespread use. Most problems with Gnulib can and should be fixed in a generic way, so that all of Gnulib’s users can benefit from the change. But occasionally a problem arises that is difficult or undesirable to fix generically, or a project that uses Gnulib may need to work around an issue before the Gnulib maintainers commit a final fix. Maintainers may also want to add their own pools of modules to projects as Gnulib “staging areas.”

The obvious way to make local changes to Gnulib modules is to use gnulib-tool to check out pristine modules, then to modify the results in-place. This works well enough for short-lived experiments. It is harder to keep modified versions of Gnulib modules for a long time, even though Git (or another distributed version control systems) can help out a lot with this during the development process.

Git, however, doesn’t address the distribution issue. When a package “foobar” needs a modified version of, say, stdint.in.h, it either has to put a comment into foobar/autogen.sh saying “Attention! This doesn’t work with a pristine Gnulib, you need this and that patch after checking out Gnulib,” or it has to use the ‘--avoid=stdint’ option and provide the modified stdint module in a different directory.

The --local-dir option to gnulib-tool solves this problem. It allows the package to override or augment Gnulib. This means:

• You can store files that are to override Gnulib files or modules.
• You can store context diffs to be applied to Gnulib files.
• You can add modules of your own, that are not (yet) in Gnulib.
• You can also add unstructured amounts of code to the library, by grouping the non-Gnulib files of the library in a single kitchen-sink “module.” (This kind of kitchen-sink module is not needed when you use the gnulib-tool option --makefile-name.)

In a release tarball, you can distribute the contents of this --local-dir directory that will be combinable with newer versions of Gnulib, barring incompatible changes to Gnulib.

If the --local-dir=directory option is specified, then gnulib-tool looks in directory whenever it reads a file from the Gnulib directory. Suppose gnulib-tool is looking for file. Then:

• If directory/file exists, then gnulib-tool uses it instead of the file included in Gnulib.
• Otherwise, if directory/file.diff exists, then gnulib-tool uses the file from Gnulib after applying the diff using the patch program.
• Otherwise, gnulib-tool uses the file included in Gnulib.

You can specify the --local-dir multiple times. In this case, the first specified directory has the highest precedence. That is, a file found in one directory will shadow any file and file.diff in the later directories and in the Gnulib directory. And a file file.diff found in one directory will be applied on top of the combination of file and file.diff files found in the later directories and in the Gnulib directory.

Please make wise use of this option. It also allows you to easily hold back modifications you make to Gnulib macros in cases it may be better to share them.