README

   1 GNULib
   2 ======
   3
   4 GNULib is intended 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 achieved 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 * Build files only if they are needed on a platform.  Look at the
  67   alloca and fnmatch modules for how to achieve this.  If for some
  68   reason you cannot do this, and you have a .c file that leads to an
  69   empty .o file on some platforms (through some big #if around all the
  70   code), then ensure that the compilation unit is not empty after
  71   preprocessing.  One way to do this is to #include <stddef.h> or
  72   <stdio.h> before the big #if.
  73
  74 Portability guidelines
  75 ----------------------
  76
  77 GNULib code is intended to be portable to a wide variety of platforms,
  78 not just GNU platforms.
  79
  80 Many GNULib modules exist so that applications need not worry about
  81 undesirable variability in implementations.  For example, an
  82 application that uses the 'malloc' module need not worry about (malloc
  83 (0)) returning NULL on some Standard C platforms; and 'time_r' users
  84 need not worry about localtime_r returning int (not char *) on some
  85 platforms that predate POSIX 1003.1-2001.
  86
  87 Originally much of the GNULib code was portable to ancient hosts like
  88 4.2BSD, but it is a maintenance hassle to maintain compatibility with
  89 unused hosts, so currently we assume at least a freestanding C89
  90 compiler, possibly operating with a C library that predates C89.  The
  91 oldest environment currently ported to is probably SunOS 4 + GCC 1.x,
  92 though we haven't tested this exact combination.  SunOS 4 last shipped
  93 on 1998-09-30, and Sun dropped support for it on 2003-10-01, so at
  94 some point we may start assuming a C89 library as well.
  95
  96 Because we assume a freestanding C89 compiler, GNULib code can include
  97 <float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally.  It
  98 can also include hosted headers like <errno.h> that were present in
  99 Unix Version 7 and are thus widely available.  Similarly, many modules
 100 include <sys/types.h> even though it's not even in C99; that's OK
 101 since <sys/types.h> has been around nearly forever.  <string.h> and
 102 <stdlib.h> were not in Unix Version 7, so they weren't universally
 103 available on ancient hosts, but they are both in SunOS 4 (the oldest
 104 platform still in relatively-common use) so GNULib assumes them now.
 105
 106 Even if the include files exist, they may not conform to C89.
 107 However, GCC has a "fixincludes" script that attempts to fix most
 108 C89-conformance problems.  So GNULib currently assumes include files
 109 largely conform to C89 or better.  People still using ancient hosts
 110 should use fixincludes or fix their include files manually.
 111
 112 Even if the include files conform to C89, the library itself may not.
 113 For example, SunOS 4's (free (NULL)) can dump core, so GNULib code
 114 must avoid freeing a null pointer, even though C89 allows it.
 115
 116 The GNU coding standards allow one departure from strict C99: GNULib
 117 code can assume that standard internal types like size_t are no wider
 118 than 'long'.  POSIX 1003.1-2001 and the GNU coding standards both
 119 require 'int' to be at least 32 bits wide, so GNULib code assumes this
 120 as well.  GNULib code makes the following additional assumptions:
 121
 122  * Signed integer arithmetic is two's complement, without runtime
 123    overflow checking.
 124
 125  * There are no "holes" in integer values: all the bits of an integer
 126    contribute to its value in the usual way.
 127
 128  * If two nonoverlapping objects have sizes S and T represented as
 129    size_t values, then S + T cannot overflow.  This assumption is true
 130    for all practical hosts with flat address spaces, but it is not
 131    always true for hosts with segmented address spaces.
 132
 133  * Objects with all bits zero are treated as 0 or NULL.  For example,
 134    memset (A, 0, sizeof A) initializes an array A of pointers to NULL.
 135
 136 The above assumptions are not required by the C or POSIX standards but
 137 hold on all practical porting targets that we're familiar with.  If
 138 you have a porting target where these assumptions are not true, we'd
 139 appreciate hearing of any fixes.  We need fixes that do not increase
 140 runtime overhead on standard hosts and that are relatively easy to
 141 maintain.
 142
 143 With the above caveats, GNULib code should port without problem to new
 144 hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
 145 Hence GNULib code should avoid using constructs (e.g., undeclared
 146 functions return 'int') that do not conform to C99.
 147
 148 High Quality
 149 ============
 150
 151 We will be developing a testsuite for these applications.  The goal is
 152 to have a 100% firm interface so that maintainers can feel free to
 153 update to the code in CVS at *any* time and know that their
 154 application will not break.  This means that before any change can be
 155 committed to the repository, a test suite program must be produced
 156 that exposes the bug for regression testing.  All experimental work
 157 should be done on branches to help promote this.
 158
 159 CVS
 160 ===
 161
 162 GNULib is available for anonymous checkout.  In any Bourne-shell the
 163 following should work:
 164
 165 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib login
 166 (Just hit Enter or Return when prompt for a password)
 167 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib
 168