README

   1 GNULib
   2 ======
   3
   4 GNULib is inteded to be the canonical source for most of the important
   5 "Portability" files for GNU projects.
   6
   7 While portability is not one of our primary goals, it has helped
   8 introduce many people to the GNU system, and is worthwhile when it can
   9 be acheived at a low cost.  This collection helps lower that cost.
  10
  11 There are three directories that contain all of the files:
  12
  13 gpl/   - Any source files licensed under the GNU General Public License
  14 lgpl/  - Any source files licensed under the GNU Lesser GPL
  15 doc/   - Any documents that may be nice to have in applications.  This
  16 includes such files as 'COPYING, COPYING.LIB, etc.'
  17
  18 Contributing to GNULib
  19 ======================
  20
  21 All software here is Copyright (c) Free Software Foundation - you need
  22 to have filled out an assignment form for a project that uses the
  23 module for that contribution to be accepted here.
  24
  25 If you have a piece of code that you would like to contribute, please
  26 email bug-gnulib@gnu.org.  We will add you to the maintainers list.
  27
  28 Generally we are looking for files that fulfill at least one of the
  29 following requirements:
  30
  31     * If your .c and .h files define functions that are broken or
  32 missing on some other system, we should be able to include it.
  33
  34     * If your functions remove arbitrary limits from existing
  35 functions (either under the same name, or as a slightly different
  36 name), we should be able to include it.
  37
  38 If your functions define completely new but rarely used functionality,
  39 you should probably consider packaging it as a seperate library.
  40
  41 How to add a new module
  42 -----------------------
  43
  44 * Add the header files and source files to lib/.
  45 * If the module needs configure-time checks, write an autoconf
  46   macro for it in m4/<module>.m4. See m4/README for details.
  47 * Write a module description modules/<module>, based on modules/TEMPLATE.
  48 * Add the module to the list in MODULES.html.sh.
  49
  50 You can test that a module builds correctly with:
  51   $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
  52   $ cd /tmp/testdir
  53   $ ./configure && make
  54
  55 Other things:
  56 * Check the license and copyright year of headers.
  57 * Add source files to config/srclist* if they are identical to upstream
  58   and should be upgraded in gnulib whenever the upstream source changes.
  59 * Include header files in source files to verify the function prototypes.
  60 * Make sure a replacement function doesn't cause warnings or clashes on
  61   systems that have the function.
  62 * Autoconf functions can use gl_* prefix. The AC_* prefix is for
  63   autoconf internal functions.
  64 * Try to prevent that the files are built if they aren't needed on a
  65   platform.  Valid excuses to this rule include ELIDE constructs that
  66   lead to an empty .o file (see getopt module).
  67
  68 High Quality
  69 ============
  70
  71 We will be developing a testsuite for these applications.  The goal is
  72 to have a 100% firm interface so that maintainers can feel free to
  73 update to the code in CVS at *any* time and know that their
  74 application will not break.  This means that before any change can be
  75 committed to the repository, a test suite program must be produced
  76 that exposes the bug for regression testing.  All experimental work
  77 should be done on branches to help promote this.
  78
  79 CVS
  80 ===
  81
  82 GNULib is available for anonymous checkout.  In any Bourne-shell the
  83 following should work:
  84
  85 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib login
  86 (Just hit Enter or Return when prompt for a password)
  87 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib
  88