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