GNULib
======

GNULib is inteded to be the canonical source for most of the important
"Portability" files for GNU projects.

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

There are three directories that contain all of the files:

gpl/   - Any source files licensed under the GNU General Public License
lgpl/  - Any source files licensed under the GNU Lesser GPL
doc/   - Any documents that may be nice to have in applications.  This
includes such files as 'COPYING, COPYING.LIB, etc.'

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.  We will add you to the maintainers list.

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.

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.
* 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.
* Try to prevent that the files are built if they aren't needed on a
  platform.  Valid excuses to this rule include ELIDE constructs that
  lead to an empty .o file (see getopt module).
* If you have a .c file that leads to an empty .o file on some platforms
  (through some big #if around all the code), still make sure that after
  preprocessing the compilation unit is not empty. This is usually fulfilled
  if you #include <stdio.h> or #include <sys/types.h> before the big #if;
  otherwise you need to add a #else branch containing "typedef int dummy;"
  or "extern int dummy;".

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.

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.  However, 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'.

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 CVS 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.

CVS
===

GNULib is available for anonymous checkout.  In any Bourne-shell the
following should work:

$ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib login
(Just hit Enter or Return when prompt for a password)
$ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib