gnulib/README

Gnulib
======

Gnulib is intended to be the canonical source for most of the important
"portability" and/or common files for GNU projects.  These are files
intended to be shared at the source level; Gnulib is not a library meant
to be installed and linked against.  Unlike most projects, Gnulib does
not normally generate a source tarball distribution; instead, developers
should just grab modules directly from the repository.

While portability across operating systems is not one of GNU's primary
goals, it has helped introduce many people to the GNU system, and is
worthwhile when it can be achieved at a low cost.  This collection helps
lower that cost.


Contributing to Gnulib
======================
All software here is Copyright (c) Free Software Foundation - you need
to have filled out an assignment form for a project that uses the
module for that contribution to be accepted here.

If you have a piece of code that you would like to contribute, please
email bug-gnulib@gnu.org.  You can review the archives, subscribe, etc.,
via http://lists.gnu.org/mailman/listinfo/bug-gnulib.

Generally we are looking for files that fulfill at least one of the
following requirements:

    * If your .c and .h files define functions that are broken or
missing on some other system, we should be able to include it.

    * If your functions remove arbitrary limits from existing
functions (either under the same name, or as a slightly different
name), we should be able to include it.

If your functions define completely new but rarely used functionality,
you should probably consider packaging it as a separate library.


License
-------
Gnulib contains code both under GPL and LGPL.  Because several packages
that use Gnulib are GPL, the files state they are licensed under GPL.
However, to support LGPL projects as well, you may use some of the
files under LGPL.  The "License:" information in the files under
modules/ clarifies the real license that applies to the module source.

Keep in mind that if you submit patches to files in Gnulib, you should
license them under a compatible license, which means that sometimes
the contribution will have to be LGPL, if the original file is
available under LGPL via a "License: LGPL" information in the
projects' modules/ file.


How to add a new module
-----------------------
* Add the header files and source files to lib/.
* If the module needs configure-time checks, write an autoconf
  macro for it in m4/<module>.m4. See m4/README for details.
* Write a module description modules/<module>, based on modules/TEMPLATE.
* If the module contributes a section to the end-user documentation,
  put this documentation in doc/<module>.texi and add it to the "Files"
  section of modules/<module>.  Most modules don't do this; they have only
  documentation for the programmer (= gnulib user).  Such documentation
  usually goes into the lib/ source files.  It may also go into doc/;
  but don't add it to the module description in this case.
* Add the module to the list in MODULES.html.sh.

You can test that a module builds correctly with:
  $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
  $ cd /tmp/testdir
  $ ./configure && make

Other things:
* Check the license and copyright year of headers.
* Check that the source code follows the GNU coding standards;
  see <http://www.gnu.org/prep/standards>.
* Add source files to config/srclist* if they are identical to upstream
  and should be upgraded in gnulib whenever the upstream source changes.
* Include header files in source files to verify the function prototypes.
* Make sure a replacement function doesn't cause warnings or clashes on
  systems that have the function.
* Autoconf functions can use gl_* prefix. The AC_* prefix is for
  autoconf internal functions.
* Build files only if they are needed on a platform.  Look at the
  alloca and fnmatch modules for how to achieve this.  If for some
  reason you cannot do this, and you have a .c file that leads to an
  empty .o file on some platforms (through some big #if around all the
  code), then ensure that the compilation unit is not empty after
  preprocessing.  One way to do this is to #include <stddef.h> or
  <stdio.h> before the big #if.

Portability guidelines
----------------------

Gnulib code is intended to be portable to a wide variety of platforms,
not just GNU platforms.

Many Gnulib modules exist so that applications need not worry about
undesirable variability in implementations.  For example, an
application that uses the 'malloc' module need not worry about (malloc
(0)) returning NULL on some Standard C platforms; and 'time_r' users
need not worry about localtime_r returning int (not char *) on some
platforms that predate POSIX 1003.1-2001.

Originally much of the Gnulib code was portable to ancient hosts like
4.2BSD, but it is a maintenance hassle to maintain compatibility with
unused hosts, so currently we assume at least a freestanding C89
compiler, possibly operating with a C library that predates C89.  The
oldest environment currently ported to is probably SunOS 4 + GCC 1.x,
though we haven't tested this exact combination.  SunOS 4 last shipped
on 1998-09-30, and Sun dropped support for it on 2003-10-01, so at
some point we may start assuming a C89 library as well.

Because we assume a freestanding C89 compiler, Gnulib code can include
<float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally.  It
can also include hosted headers like <errno.h> that were present in
Unix Version 7 and are thus widely available.  Similarly, many modules
include <sys/types.h> even though it's not even in C99; that's OK
since <sys/types.h> has been around nearly forever.  <string.h> and
<stdlib.h> were not in Unix Version 7, so they weren't universally
available on ancient hosts, but they are both in SunOS 4 (the oldest
platform still in relatively-common use) so Gnulib assumes them now.

Even if the include files exist, they may not conform to C89.
However, GCC has a "fixincludes" script that attempts to fix most
C89-conformance problems.  So Gnulib currently assumes include files
largely conform to C89 or better.  People still using ancient hosts
should use fixincludes or fix their include files manually.

Even if the include files conform to C89, the library itself may not.
For example, SunOS 4's (free (NULL)) can dump core, so Gnulib code
must avoid freeing a null pointer, even though C89 allows it.
You can work around some of these problems by requiring the relevant
modules, e.g., the Gnulib 'free' module supplies a conforming 'free'.

The GNU coding standards allow one departure from strict C99: Gnulib
code can assume that standard internal types like size_t are no wider
than 'long'.  POSIX 1003.1-2001 and the GNU coding standards both
require 'int' to be at least 32 bits wide, so Gnulib code assumes this
as well.  Gnulib code makes the following additional assumptions:

 * With one exception noted below, signed integer arithmetic is two's
   complement, without runtime overflow checking.  This is the
   traditional behavior, and is supported by C99 implementations that
   conform to ISO/IEC 10967-1 (LIA-1) and that define signed integer
   types as being modulo.

   The exception is signed loop indexes.  Here, the behavior is
   undefined if any signed expression derived from the loop index
   overflows.  For example, the following code contains two such
   overflows (the "i++" and the "i + 1") and therefore has undefined
   behavior:

     int i;
     for (i = INT_MAX - 10; i <= INT_MAX; i++)
       if (i + 1 < 0)
	 {
	   report_overflow ();
	   break;
	 }

   This exception is a concession to modern optimizing compilers,
   which can turn the above loop into code that executes the loop body
   11 times, even though wraparound arithmetic would cause the loop to
   iterate forever.

 * There are no "holes" in integer values: all the bits of an integer
   contribute to its value in the usual way.

 * If two nonoverlapping objects have sizes S and T represented as
   size_t values, then S + T cannot overflow.  This assumption is true
   for all practical hosts with flat address spaces, but it is not
   always true for hosts with segmented address spaces.

 * If an existing object has size S, and if T is sufficiently small
   (e.g., 8 KiB), then S + T cannot overflow.  Overflow in this case
   would mean that the rest of your program fits into T bytes, which
   can't happen in realistic flat-address-space hosts.

 * Objects with all bits zero are treated as 0 or NULL.  For example,
   memset (A, 0, sizeof A) initializes an array A of pointers to NULL.

 * Adding zero to a null pointer does not change the pointer.
   For example, 0 + (char *) NULL == (char *) NULL.

The above assumptions are not required by the C or POSIX standards but
hold on all practical porting targets that we're familiar with.  If
you have a porting target where these assumptions are not true, we'd
appreciate hearing of any fixes.  We need fixes that do not increase
runtime overhead on standard hosts and that are relatively easy to
maintain.

With the above caveats, Gnulib code should port without problem to new
hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
Hence Gnulib code should avoid using constructs (e.g., undeclared
functions return 'int') that do not conform to C99.

High Quality
============

We will be developing a testsuite for these applications.  The goal is
to have a 100% firm interface so that maintainers can feel free to
update to the code in git at *any* time and know that their
application will not break.  This means that before any change can be
committed to the repository, a test suite program must be produced
that exposes the bug for regression testing.  All experimental work
should be done on branches to help promote this.

git and CVS
===========

Gnulib is available for anonymous checkout.  In any Bourne-shell the
following should work:
  $ git clone git://git.sv.gnu.org/gnulib
Or, if you prefer the CVS-like 'cogito' frontend to plain 'git':
  $ cg clone git://git.sv.gnu.org/gnulib

git resources:
  Overview: http://en.wikipedia.org/wiki/Git_(software)
  Homepage: http://git.or.cz/
  Download: http://www.kernel.org/pub/software/scm/git/
  Tutorial: http://git.or.cz/course/
            http://www.kernel.org/pub/software/scm/git/docs/tutorial.html
  FAQ:      http://git.or.cz/gitwiki/GitFaq

cogito resources:
  Overview: http://en.wikipedia.org/wiki/Cogito_(software)
  Homepage: http://git.or.cz/cogito/
  Download: http://kernel.org/pub/software/scm/cogito/
  Tutorial: http://git.or.cz/course/

For those among us who have tightly limited disk space and a fast network
connection, CVS checkouts are also supported:
  $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib login
  (Just hit Enter or Return when prompted for a password)
  $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib

Gnulib is hosted on savannah.gnu.org.  The project page is
http://savannah.gnu.org/projects/gnulib.

Keeping Up-to-date
==================

The best way to work with Gnulib is to check it out of git.
Subscribing to the bug-gnulib@gnu.org mailing list will help you to
plan when to update your local copy of Gnulib (which you use to
maintain your software) from git.  To synchronize, you can use "git pull"
or "cg update", or "cvs update -dP" if you are still using CVS.

Sometimes, using an updated version of Gnulib will require you to use
newer versions of GNU Automake or Autoconf.  You may find it helpful
to join the autotools-announce mailing list to be advised of such
changes.


-----
Copyright (C) 2001, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */