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 * 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 The GNU coding standards allow one departure from strict C99: GNULib
 119 code can assume that standard internal types like size_t are no wider
 120 than 'long'.  POSIX 1003.1-2001 and the GNU coding standards both
 121 require 'int' to be at least 32 bits wide, so GNULib code assumes this
 122 as well.  GNULib code makes the following additional assumptions:
 123
 124  * Signed integer arithmetic is two's complement, without runtime
 125    overflow checking.
 126
 127  * There are no "holes" in integer values: all the bits of an integer
 128    contribute to its value in the usual way.
 129
 130  * If two nonoverlapping objects have sizes S and T represented as
 131    size_t values, then S + T cannot overflow.  This assumption is true
 132    for all practical hosts with flat address spaces, but it is not
 133    always true for hosts with segmented address spaces.
 134
 135  * Objects with all bits zero are treated as 0 or NULL.  For example,
 136    memset (A, 0, sizeof A) initializes an array A of pointers to NULL.
 137
 138 The above assumptions are not required by the C or POSIX standards but
 139 hold on all practical porting targets that we're familiar with.  If
 140 you have a porting target where these assumptions are not true, we'd
 141 appreciate hearing of any fixes.  We need fixes that do not increase
 142 runtime overhead on standard hosts and that are relatively easy to
 143 maintain.
 144
 145 With the above caveats, GNULib code should port without problem to new
 146 hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
 147 Hence GNULib code should avoid using constructs (e.g., undeclared
 148 functions return 'int') that do not conform to C99.
 149
 150 High Quality
 151 ============
 152
 153 We will be developing a testsuite for these applications.  The goal is
 154 to have a 100% firm interface so that maintainers can feel free to
 155 update to the code in CVS at *any* time and know that their
 156 application will not break.  This means that before any change can be
 157 committed to the repository, a test suite program must be produced
 158 that exposes the bug for regression testing.  All experimental work
 159 should be done on branches to help promote this.
 160
 161 CVS
 162 ===
 163
 164 GNULib is available for anonymous checkout.  In any Bourne-shell the
 165 following should work:
 166
 167 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib login
 168 (Just hit Enter or Return when prompt for a password)
 169 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib
 170