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