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
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
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
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
is looking for file. Then:
gnulib-tooluses it instead of the file included in Gnulib.
gnulib-tooluses the file from Gnulib after applying the diff using the
gnulib-tooluses 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.