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