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.  Unlike most projects, Gnulib does
   8 not normally generate a source tarball distribution; instead, developers
   9 should just grab modules directly from the repository.
  10
  11 While portability across operating systems is not one of GNU's primary
  12 goals, it has helped introduce many people to the GNU system, and is
  13 worthwhile when it can be achieved at a low cost.  This collection helps
  14 lower that cost.
  15
  16
  17 Contributing to Gnulib
  18 ======================
  19 All software here is Copyright (c) Free Software Foundation - you need
  20 to have filled out an assignment form for a project that uses the
  21 module for that contribution to be accepted here.
  22
  23 If you have a piece of code that you would like to contribute, please
  24 email bug-gnulib@gnu.org.  You can review the archives, subscribe, etc.,
  25 via http://lists.gnu.org/mailman/listinfo/bug-gnulib.
  26
  27 Generally we are looking for files that fulfill at least one of the
  28 following requirements:
  29
  30     * If your .c and .h files define functions that are broken or
  31 missing on some other system, we should be able to include it.
  32
  33     * If your functions remove arbitrary limits from existing
  34 functions (either under the same name, or as a slightly different
  35 name), we should be able to include it.
  36
  37 If your functions define completely new but rarely used functionality,
  38 you should probably consider packaging it as a separate library.
  39
  40
  41 License
  42 -------
  43 Gnulib contains code both under GPL and LGPL.  Because several packages
  44 that use Gnulib are GPL, the files state they are licensed under GPL.
  45 However, to support LGPL projects as well, you may use some of the
  46 files under LGPL.  The "License:" information in the files under
  47 modules/ clarifies the real license that applies to the module source.
  48
  49 Keep in mind that if you submit patches to files in Gnulib, you should
  50 license them under a compatible license, which means that sometimes
  51 the contribution will have to be LGPL, if the original file is
  52 available under LGPL via a "License: LGPL" information in the
  53 projects' modules/ file.
  54
  55
  56 How to add a new module
  57 -----------------------
  58 * Add the header files and source files to lib/.
  59 * If the module needs configure-time checks, write an autoconf
  60   macro for it in m4/<module>.m4. See m4/README for details.
  61 * Write a module description modules/<module>, based on modules/TEMPLATE.
  62 * If the module contributes a section to the end-user documentation,
  63   put this documentation in doc/<module>.texi and add it to the "Files"
  64   section of modules/<module>.  Most modules don't do this; they have only
  65   documentation for the programmer (= gnulib user).  Such documentation
  66   usually goes into the lib/ source files.  It may also go into doc/;
  67   but don't add it to the module description in this case.
  68 * Add the module to the list in MODULES.html.sh.
  69
  70 You can test that a module builds correctly with:
  71   $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
  72   $ cd /tmp/testdir
  73   $ ./configure && make
  74
  75 Other things:
  76 * Check the license and copyright year of headers.
  77 * Check that the source code follows the GNU coding standards;
  78   see <http://www.gnu.org/prep/standards>.
  79 * Add source files to config/srclist* if they are identical to upstream
  80   and should be upgraded in gnulib whenever the upstream source changes.
  81 * Include header files in source files to verify the function prototypes.
  82 * Make sure a replacement function doesn't cause warnings or clashes on
  83   systems that have the function.
  84 * Autoconf functions can use gl_* prefix. The AC_* prefix is for
  85   autoconf internal functions.
  86 * Build files only if they are needed on a platform.  Look at the
  87   alloca and fnmatch modules for how to achieve this.  If for some
  88   reason you cannot do this, and you have a .c file that leads to an
  89   empty .o file on some platforms (through some big #if around all the
  90   code), then ensure that the compilation unit is not empty after
  91   preprocessing.  One way to do this is to #include <stddef.h> or
  92   <stdio.h> before the big #if.
  93
  94 Portability guidelines
  95 ----------------------
  96
  97 Gnulib code is intended to be portable to a wide variety of platforms,
  98 not just GNU platforms.
  99
 100 Many Gnulib modules exist so that applications need not worry about
 101 undesirable variability in implementations.  For example, an
 102 application that uses the 'malloc' module need not worry about (malloc
 103 (0)) returning NULL on some Standard C platforms; and 'time_r' users
 104 need not worry about localtime_r returning int (not char *) on some
 105 platforms that predate POSIX 1003.1-2001.
 106
 107 Originally much of the Gnulib code was portable to ancient hosts like
 108 4.2BSD, but it is a maintenance hassle to maintain compatibility with
 109 unused hosts, so currently we assume at least a freestanding C89
 110 compiler, possibly operating with a C library that predates C89.  The
 111 oldest environment currently ported to is probably SunOS 4 + GCC 1.x,
 112 though we haven't tested this exact combination.  SunOS 4 last shipped
 113 on 1998-09-30, and Sun dropped support for it on 2003-10-01, so at
 114 some point we may start assuming a C89 library as well.
 115
 116 Because we assume a freestanding C89 compiler, Gnulib code can include
 117 <float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally.  It
 118 can also include hosted headers like <errno.h> that were present in
 119 Unix Version 7 and are thus widely available.  Similarly, many modules
 120 include <sys/types.h> even though it's not even in C99; that's OK
 121 since <sys/types.h> has been around nearly forever.  <string.h> and
 122 <stdlib.h> were not in Unix Version 7, so they weren't universally
 123 available on ancient hosts, but they are both in SunOS 4 (the oldest
 124 platform still in relatively-common use) so Gnulib assumes them now.
 125
 126 Even if the include files exist, they may not conform to C89.
 127 However, GCC has a "fixincludes" script that attempts to fix most
 128 C89-conformance problems.  So Gnulib currently assumes include files
 129 largely conform to C89 or better.  People still using ancient hosts
 130 should use fixincludes or fix their include files manually.
 131
 132 Even if the include files conform to C89, the library itself may not.
 133 For example, SunOS 4's (free (NULL)) can dump core, so Gnulib code
 134 must avoid freeing a null pointer, even though C89 allows it.
 135 You can work around some of these problems by requiring the relevant
 136 modules, e.g., the Gnulib 'free' module supplies a conforming 'free'.
 137
 138 The GNU coding standards allow one departure from strict C99: Gnulib
 139 code can assume that standard internal types like size_t are no wider
 140 than 'long'.  POSIX 1003.1-2001 and the GNU coding standards both
 141 require 'int' to be at least 32 bits wide, so Gnulib code assumes this
 142 as well.  Gnulib code makes the following additional assumptions:
 143
 144  * With one exception noted below, signed integer arithmetic is two's
 145    complement, without runtime overflow checking.  This is the
 146    traditional behavior, and is supported by C99 implementations that
 147    conform to ISO/IEC 10967-1 (LIA-1) and that define signed integer
 148    types as being modulo.
 149
 150    The exception is signed loop indexes.  Here, the behavior is
 151    undefined if any signed expression derived from the loop index
 152    overflows.  For example, the following code contains two such
 153    overflows (the "i++" and the "i + 1") and therefore has undefined
 154    behavior:
 155
 156      int i;
 157      for (i = INT_MAX - 10; i <= INT_MAX; i++)
 158        if (i + 1 < 0)
 159          {
 160            report_overflow ();
 161            break;
 162          }
 163
 164    This exception is a concession to modern optimizing compilers,
 165    which can turn the above loop into code that executes the loop body
 166    11 times, even though wraparound arithmetic would cause the loop to
 167    iterate forever.
 168
 169  * There are no "holes" in integer values: all the bits of an integer
 170    contribute to its value in the usual way.
 171
 172  * If two nonoverlapping objects have sizes S and T represented as
 173    size_t values, then S + T cannot overflow.  This assumption is true
 174    for all practical hosts with flat address spaces, but it is not
 175    always true for hosts with segmented address spaces.
 176
 177  * If an existing object has size S, and if T is sufficiently small
 178    (e.g., 8 KiB), then S + T cannot overflow.  Overflow in this case
 179    would mean that the rest of your program fits into T bytes, which
 180    can't happen in realistic flat-address-space hosts.
 181
 182  * Objects with all bits zero are treated as 0 or NULL.  For example,
 183    memset (A, 0, sizeof A) initializes an array A of pointers to NULL.
 184
 185  * Adding zero to a null pointer does not change the pointer.
 186    For example, 0 + (char *) NULL == (char *) NULL.
 187
 188 The above assumptions are not required by the C or POSIX standards but
 189 hold on all practical porting targets that we're familiar with.  If
 190 you have a porting target where these assumptions are not true, we'd
 191 appreciate hearing of any fixes.  We need fixes that do not increase
 192 runtime overhead on standard hosts and that are relatively easy to
 193 maintain.
 194
 195 With the above caveats, Gnulib code should port without problem to new
 196 hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
 197 Hence Gnulib code should avoid using constructs (e.g., undeclared
 198 functions return 'int') that do not conform to C99.
 199
 200 High Quality
 201 ============
 202
 203 We will be developing a testsuite for these applications.  The goal is
 204 to have a 100% firm interface so that maintainers can feel free to
 205 update to the code in git at *any* time and know that their
 206 application will not break.  This means that before any change can be
 207 committed to the repository, a test suite program must be produced
 208 that exposes the bug for regression testing.  All experimental work
 209 should be done on branches to help promote this.
 210
 211 git and CVS
 212 ===========
 213
 214 Gnulib is available for anonymous checkout.  In any Bourne-shell the
 215 following should work:
 216   $ git clone git://git.sv.gnu.org/gnulib.git
 217 Or, if you prefer the CVS-like 'cogito' frontend to plain 'git':
 218   $ cg clone git://git.sv.gnu.org/gnulib.git
 219
 220 For a read-write checkout you need to have a login on savannah.gnu.org and be
 221 a member of the gnulib project at http://savannah.gnu.org/projects/gnulib .
 222 Then, instead of the URL
 223   git://git.sv.gnu.org/gnulib
 224 use the URL
 225   ssh://<user>@git.sv.gnu.org/srv/git/gnulib
 226 where <user> is your login name on savannah.gnu.org.
 227
 228 git resources:
 229   Overview: http://en.wikipedia.org/wiki/Git_(software)
 230   Homepage: http://git.or.cz/
 231   Download: http://www.kernel.org/pub/software/scm/git/
 232   Tutorial: http://git.or.cz/course/
 233             http://www.kernel.org/pub/software/scm/git/docs/tutorial.html
 234   FAQ:      http://git.or.cz/gitwiki/GitFaq
 235
 236 cogito resources:
 237   Overview: http://en.wikipedia.org/wiki/Cogito_(software)
 238   Homepage: http://git.or.cz/cogito/
 239   Download: http://kernel.org/pub/software/scm/cogito/
 240   Tutorial: http://git.or.cz/course/
 241
 242 For those among us who have tightly limited disk space and a fast network
 243 connection, CVS checkouts are also supported:
 244   $ cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
 245
 246 CVS checkouts from before 2007-09-19 can be converted to the new read-only CVS
 247 location through commands like these:
 248   $ find . -name Root       -exec sed --in-place 's|.*|:pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git|' {} ';'
 249   $ find . -name Repository -exec sed --in-place 's|^gnulib|/srv/git/gnulib.git/HEAD|' {} ';'
 250
 251 Gnulib is hosted on savannah.gnu.org.  The project page is
 252 http://savannah.gnu.org/projects/gnulib.
 253
 254 Keeping Up-to-date
 255 ==================
 256
 257 The best way to work with Gnulib is to check it out of git.
 258 Subscribing to the bug-gnulib@gnu.org mailing list will help you to
 259 plan when to update your local copy of Gnulib (which you use to
 260 maintain your software) from git.  To synchronize, you can use "git pull"
 261 or "cg update", or "cvs update -dP" if you are still using CVS.
 262
 263 Sometimes, using an updated version of Gnulib will require you to use
 264 newer versions of GNU Automake or Autoconf.  You may find it helpful
 265 to join the autotools-announce mailing list to be advised of such
 266 changes.
 267
 268
 269 -----
 270 Copyright (C) 2001, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
 271
 272 This program is free software: you can redistribute it and/or modify
 273 it under the terms of the GNU General Public License as published by
 274 the Free Software Foundation; either version 3 of the License, or
 275 (at your option) any later version.
 276
 277 This program is distributed in the hope that it will be useful,
 278 but WITHOUT ANY WARRANTY; without even the implied warranty of
 279 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 280 GNU General Public License for more details.
 281
 282 You should have received a copy of the GNU General Public License
 283 along with this program.  If not, see <http://www.gnu.org/licenses/>.  */