find-maint: Using the GNU Portability Library
6 Using the GNU Portability Library
***********************************
The Gnulib library (<https://www.gnu.org/software/gnulib/>) makes a
variety of systems look more like a GNU/Linux system and also applies a
bunch of automatic bug fixes and workarounds. Some of these also apply
to GNU/Linux systems too. For example, the Gnulib regex implementation
is used when we determine that we are building on a GNU libc system with
a bug in the regex implementation.
6.1 How and Why we Import the Gnulib Code
=========================================
Gnulib does not have a release process which results in a source tarball
you can download. Instead, the code is simply made available by GIT, so
we import gnulib via the submodule feature. The bootstrap script
performs the necessary steps.
Findutils does not use all the Gnulib code. The modules we need are
listed in the file 'bootstrap.conf'.
The upshot of all this is that we can use the findutils git
repository to track which version of Gnulib every findutils release
uses.
A small number of files are installed by automake and will therefore
vary according to which version of automake was used to generate a
release. This includes for example boiler-plate GNU files such as
'ABOUT-NLS', 'INSTALL' and 'COPYING'.
6.2 How We Fix Gnulib Bugs
==========================
Gnulib is used by quite a number of GNU projects, and this means that it
gets plenty of testing. Therefore there are relatively few bugs in the
Gnulib code, but it does happen from time to time.
However, since there is no waiting around for a Gnulib source release
tarball, Gnulib bugs are generally fixed quickly. Here is an outline of
the way we would contribute a fix to Gnulib (assuming you know it is not
already fixed in the current Gnulib git tree):
Check you already completed a copyright assignment for Gnulib
Begin with a vanilla git tree
Download the Findutils source code from git (or use the tree you
have already)
Run the bootstrap script
Run configure
Build findutils
Build findutils and run the test suite, which should pass. In our
example we assume you have just noticed a bug in Gnulib, not that
recent Gnulib changes broke the findutils regression tests.
Write a test case
If in fact Gnulib did break the findutils regression tests, you can
probably skip this step, since you already have a test case
demonstrating the problem. Otherwise, write a findutils test case
for the bug and/or a Gnulib test case.
Fix the Gnulib bug
Make sure your editor follows symbolic links so that your changes
to 'gnulib/...' actually affect the files in the git working
directory you checked out earlier. Observe that your test now
passes.
Prepare a Gnulib patch
In the gnulib subdirectory, use 'git format-patch' to prepare the
patch. Follow the normal usage for checkin comments (take a look
at the output of 'git log'). Check that the patch conforms with
the GNU coding standards, and email it to the Gnulib mailing list.
Wait for the patch to be applied
Once your bug fix has been applied, you can update your gnulib
directory from git, and then check in the change to the submodule
as normal (you can check 'git help submodule' for details).
There is an alternative to the method above; it is possible to store
local diffs to be patched into gnulib beneath the 'gnulib-local'.
Normally however, there is no need for this, since gnulib updates are
very prompt.
6.3 How to update Gnulib to latest
==================================
With a non-dirty working tree, the command 'make
update-gnulib-to-latest' (or the shorter alias 'make gnulib-sync'
allows, well, to update the gnulib submodule. In detail, that is:
1. Fetching the latest upstream gnulib reference.
2. Copying the files which should stay in sync like 'bootstrap' from
gnulib into the findutils working tree.
3. And finally showing the 'git status' for the gnulib submodule and
the above copied files.
After that, the maintainer compares if all is correct, if the
findutils build and run correct, and finally commits with the new gnulib
version, e.g. via 'git gui'.
The 'gnulib-sync' target can be run any time - after a 'configure'
run -, and only rejects to run if the working tree is dirty.
Info Catalog
find-maint: Tools
find-maint: Top
find-maint: Documentation