README

   1 Gnulib
   2 ======
   3
   4 Gnulib is intended to be the canonical source for most of the important
   5 "portability" and/or common files for GNU projects.  These are files
   6 intended to be shared at the source level; Gnulib is not a library meant
   7 to be installed and linked against.
   8
   9 While portability across operating systems is not one of GNU's primary
  10 goals, it has helped introduce many people to the GNU system, and is
  11 worthwhile when it can be achieved at a low cost.  This collection helps
  12 lower that cost.
  13
  14
  15 Contributing to Gnulib
  16 ======================
  17 All software here is Copyright (c) Free Software Foundation - you need
  18 to have filled out an assignment form for a project that uses the
  19 module for that contribution to be accepted here.
  20
  21 If you have a piece of code that you would like to contribute, please
  22 email bug-gnulib@gnu.org.  You can review the archives, subscribe, etc.,
  23 via http://lists.gnu.org/mailman/listinfo/bug-gnulib.
  24
  25 Generally we are looking for files that fulfill at least one of the
  26 following requirements:
  27
  28     * If your .c and .h files define functions that are broken or
  29 missing on some other system, we should be able to include it.
  30
  31     * If your functions remove arbitrary limits from existing
  32 functions (either under the same name, or as a slightly different
  33 name), we should be able to include it.
  34
  35 If your functions define completely new but rarely used functionality,
  36 you should probably consider packaging it as a separate library.
  37
  38
  39 License
  40 -------
  41 Gnulib contains code both under GPL and LGPL.  Because several packages
  42 that use Gnulib are GPL, the files state they are licensed under GPL.
  43 However, to support LGPL projects as well, you may use some of the
  44 files under LGPL.  The "License:" information in the files under
  45 modules/ clarifies the real license that applies to the module source.
  46
  47 Keep in mind that if you submit patches to files in Gnulib, you should
  48 license them under a compatible license, which means that sometimes
  49 the contribution will have to be LGPL, if the original file is
  50 available under LGPL via a "License: LGPL" information in the
  51 projects' modules/ file.
  52
  53
  54 How to add a new module
  55 -----------------------
  56 * Add the header files and source files to lib/.
  57 * If the module needs configure-time checks, write an autoconf
  58   macro for it in m4/<module>.m4. See m4/README for details.
  59 * Write a module description modules/<module>, based on modules/TEMPLATE.
  60 * Add the module to the list in MODULES.html.sh.
  61
  62 You can test that a module builds correctly with:
  63   $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
  64   $ cd /tmp/testdir
  65   $ ./configure && make
  66
  67 Other things:
  68 * Check the license and copyright year of headers.
  69 * Check that the source code follows the GNU coding standards;
  70   see <http://www.gnu.org/prep/standards>.
  71 * Add source files to config/srclist* if they are identical to upstream
  72   and should be upgraded in gnulib whenever the upstream source changes.
  73 * Include header files in source files to verify the function prototypes.
  74 * Make sure a replacement function doesn't cause warnings or clashes on
  75   systems that have the function.
  76 * Autoconf functions can use gl_* prefix. The AC_* prefix is for
  77   autoconf internal functions.
  78 * Build files only if they are needed on a platform.  Look at the
  79   alloca and fnmatch modules for how to achieve this.  If for some
  80   reason you cannot do this, and you have a .c file that leads to an
  81   empty .o file on some platforms (through some big #if around all the
  82   code), then ensure that the compilation unit is not empty after
  83   preprocessing.  One way to do this is to #include <stddef.h> or
  84   <stdio.h> before the big #if.
  85
  86 Portability guidelines
  87 ----------------------
  88
  89 Gnulib code is intended to be portable to a wide variety of platforms,
  90 not just GNU platforms.
  91
  92 Many Gnulib modules exist so that applications need not worry about
  93 undesirable variability in implementations.  For example, an
  94 application that uses the 'malloc' module need not worry about (malloc
  95 (0)) returning NULL on some Standard C platforms; and 'time_r' users
  96 need not worry about localtime_r returning int (not char *) on some
  97 platforms that predate POSIX 1003.1-2001.
  98
  99 Originally much of the Gnulib code was portable to ancient hosts like
 100 4.2BSD, but it is a maintenance hassle to maintain compatibility with
 101 unused hosts, so currently we assume at least a freestanding C89
 102 compiler, possibly operating with a C library that predates C89.  The
 103 oldest environment currently ported to is probably SunOS 4 + GCC 1.x,
 104 though we haven't tested this exact combination.  SunOS 4 last shipped
 105 on 1998-09-30, and Sun dropped support for it on 2003-10-01, so at
 106 some point we may start assuming a C89 library as well.
 107
 108 Because we assume a freestanding C89 compiler, Gnulib code can include
 109 <float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally.  It
 110 can also include hosted headers like <errno.h> that were present in
 111 Unix Version 7 and are thus widely available.  Similarly, many modules
 112 include <sys/types.h> even though it's not even in C99; that's OK
 113 since <sys/types.h> has been around nearly forever.  <string.h> and
 114 <stdlib.h> were not in Unix Version 7, so they weren't universally
 115 available on ancient hosts, but they are both in SunOS 4 (the oldest
 116 platform still in relatively-common use) so Gnulib assumes them now.
 117
 118 Even if the include files exist, they may not conform to C89.
 119 However, GCC has a "fixincludes" script that attempts to fix most
 120 C89-conformance problems.  So Gnulib currently assumes include files
 121 largely conform to C89 or better.  People still using ancient hosts
 122 should use fixincludes or fix their include files manually.
 123
 124 Even if the include files conform to C89, the library itself may not.
 125 For example, SunOS 4's (free (NULL)) can dump core, so Gnulib code
 126 must avoid freeing a null pointer, even though C89 allows it.
 127 You can work around some of these problems by requiring the relevant
 128 modules, e.g., the Gnulib 'free' module supplies a conforming 'free'.
 129
 130 The GNU coding standards allow one departure from strict C99: Gnulib
 131 code can assume that standard internal types like size_t are no wider
 132 than 'long'.  POSIX 1003.1-2001 and the GNU coding standards both
 133 require 'int' to be at least 32 bits wide, so Gnulib code assumes this
 134 as well.  Gnulib code makes the following additional assumptions:
 135
 136  * Signed integer arithmetic is two's complement, without runtime
 137    overflow checking.  This is the traditional behavior, and is
 138    supported by C99 implementations that conform to ISO/IEC 10967-1
 139    (LIA-1) and that define signed integer types as being modulo.
 140
 141  * There are no "holes" in integer values: all the bits of an integer
 142    contribute to its value in the usual way.
 143
 144  * If two nonoverlapping objects have sizes S and T represented as
 145    size_t values, then S + T cannot overflow.  This assumption is true
 146    for all practical hosts with flat address spaces, but it is not
 147    always true for hosts with segmented address spaces.
 148
 149  * If an existing object has size S, and if T is sufficiently small
 150    (e.g., 8 KiB), then S + T cannot overflow.  Overflow in this case
 151    would mean that the rest of your program fits into T bytes, which
 152    can't happen in realistic flat-address-space hosts.
 153
 154  * Objects with all bits zero are treated as 0 or NULL.  For example,
 155    memset (A, 0, sizeof A) initializes an array A of pointers to NULL.
 156
 157  * Adding zero to a null pointer does not change the pointer.
 158    For example, 0 + (char *) NULL == (char *) NULL.
 159
 160 The above assumptions are not required by the C or POSIX standards but
 161 hold on all practical porting targets that we're familiar with.  If
 162 you have a porting target where these assumptions are not true, we'd
 163 appreciate hearing of any fixes.  We need fixes that do not increase
 164 runtime overhead on standard hosts and that are relatively easy to
 165 maintain.
 166
 167 With the above caveats, Gnulib code should port without problem to new
 168 hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
 169 Hence Gnulib code should avoid using constructs (e.g., undeclared
 170 functions return 'int') that do not conform to C99.
 171
 172 High Quality
 173 ============
 174
 175 We will be developing a testsuite for these applications.  The goal is
 176 to have a 100% firm interface so that maintainers can feel free to
 177 update to the code in CVS at *any* time and know that their
 178 application will not break.  This means that before any change can be
 179 committed to the repository, a test suite program must be produced
 180 that exposes the bug for regression testing.  All experimental work
 181 should be done on branches to help promote this.
 182
 183 CVS
 184 ===
 185
 186 Gnulib is available for anonymous checkout.  In any Bourne-shell the
 187 following should work:
 188
 189 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib login
 190 (Just hit Enter or Return when prompt for a password)
 191 $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib
 192
 193 Gnulib is hosted on savannah.gnu.org.  The project page is
 194 http://savannah.gnu.org/projects/gnulib.
 195
 196
 197 -----
 198 Copyright (C) 2001, 2003, 2004, 2005 Free Software Foundation, Inc.
 199
 200 This program is free software; you can redistribute it and/or modify
 201 it under the terms of the GNU General Public License as published by
 202 the Free Software Foundation; either version 2, or (at your option)
 203 any later version.
 204
 205 This program is distributed in the hope that it will be useful,
 206 but WITHOUT ANY WARRANTY; without even the implied warranty of
 207 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 208 GNU General Public License for more details.
 209
 210 You should have received a copy of the GNU General Public License
 211 along with this program; if not, write to the Free Software Foundation,
 212 Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */