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 separate 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 * Check that the source code follows the GNU coding standards;
  58   see <http://www.gnu.org/prep/standards>.
  59 * Add source files to config/srclist* if they are identical to upstream
  60   and should be upgraded in gnulib whenever the upstream source changes.
  61 * Include header files in source files to verify the function prototypes.
  62 * Make sure a replacement function doesn't cause warnings or clashes on
  63   systems that have the function.
  64 * Autoconf functions can use gl_* prefix. The AC_* prefix is for
  65   autoconf internal functions.
  66 * Try to prevent that the files are built if they aren't needed on a
  67   platform.  Valid excuses to this rule include ELIDE constructs that
  68   lead to an empty .o file (see getopt module).
  69 * If you have a .c file that leads to an empty .o file on some platforms
  70   (through some big #if around all the code), still make sure that after
  71   preprocessing the compilation unit is not empty. This is usually fulfilled
  72   if you #include <stdio.h> or #include <sys/types.h> before the big #if;
  73   otherwise you need to add a #else branch containing "typedef int dummy;"
  74   or "extern int dummy;".
  75
  76 Portability guidelines
  77 ----------------------
  78
  79 GNULib code is intended to be portable to a wide variety of platforms,
  80 not just GNU platforms.
  81
  82 Many GNULib modules exist so that applications need not worry about
  83 undesirable variability in implementations.  For example, an
  84 application that uses the 'malloc' module need not worry about (malloc
  85 (0)) returning NULL on some Standard C platforms; and 'time_r' users
  86 need not worry about localtime_r returning int (not char *) on some
  87 platforms that predate POSIX 1003.1-2001.
  88
  89 Originally much of the GNULib code was portable to ancient hosts like
  90 4.2BSD, but it is a maintenance hassle to maintain compatibility with
  91 unused hosts, so currently we assume at least a freestanding C89
  92 compiler, possibly operating with a C library that predates C89.  The
  93 oldest environment currently ported to is probably SunOS 4 + GCC 1.x,
  94 though we haven't tested this exact combination.  SunOS 4 last shipped
  95 on 1998-09-30, and Sun dropped support for it on 2003-10-01, so at
  96 some point we may start assuming a C89 library as well.
  97
  98 Because we assume a freestanding C89 compiler, GNULib code can include
  99 <float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally.  It
 100 can also include hosted headers like <errno.h> that were present in
 101 Unix Version 7 and are thus widely available.  Similarly, many modules
 102 include <sys/types.h> even though it's not even in C99; that's OK
 103 since <sys/types.h> has been around nearly forever.  <string.h> and
 104 <stdlib.h> were not in Unix Version 7, so they weren't universally
 105 available on ancient hosts, but they are both in SunOS 4 (the oldest
 106 platform still in relatively-common use) so GNUlib assumes them now.
 107
 108 Even if the include files exist, they may not conform to C89.
 109 However, GCC has a "fixincludes" script that attempts to fix most
 110 C89-conformance problems.  So GNULib currently assumes include files
 111 largely conform to C89 or better.  People still using ancient hosts
 112 should use fixincludes or fix their include files manually.
 113
 114 Even if the include files conform to C89, the library itself may not.
 115 For example, SunOS 4's (free (NULL)) can dump core, so GNULib code
 116 must avoid freeing a null pointer, even though C89 allows it.
 117
 118 GNULib code should port without problem to new hosts, e.g., hosts
 119 conforming to C99 or to recent POSIX standards.  Hence GNUlib code
 120 should avoid using constructs (e.g., undeclared functions return
 121 'int') that do not conform to C99.  However, the GNU coding standards
 122 allow one departure from strict C99: GNUlib code can assume that
 123 standard internal types like size_t are no wider than 'long'.
 124
 125 High Quality
 126 ============
 127
 128 We will be developing a testsuite for these applications.  The goal is
 129 to have a 100% firm interface so that maintainers can feel free to
 130 update to the code in CVS at *any* time and know that their
 131 application will not break.  This means that before any change can be
 132 committed to the repository, a test suite program must be produced
 133 that exposes the bug for regression testing.  All experimental work
 134 should be done on branches to help promote this.
 135
 136 CVS
 137 ===
 138
 139 GNULib is available for anonymous checkout.  In any Bourne-shell the
 140 following should work:
 141
 142 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib login
 143 (Just hit Enter or Return when prompt for a password)
 144 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib
 145