-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:
-
- * 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.
-
- * 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 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
-
-Gnulib is hosted on savannah.gnu.org. The project page is
-http://savannah.gnu.org/projects/gnulib.
-
-
------
-Copyright (C) 2001, 2003, 2004, 2005, 2006 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. */
+Please see doc/gnulib-readme.texi for basic information about Gnulib.
projects / gnulib.git / blobdiff