README

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