GNULib
======
-GNULib is inteded to be the canonical source for most of the important
+GNULib is intended 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.
+be achieved at a low cost. This collection helps lower that cost.
There are three directories that contain all of the files:
If your functions define completely new but rarely used functionality,
you should probably consider packaging it as a separate library.
+License
+-------
+
+GNULib contain 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/ clarify the real license that apply to 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
-----------------------
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;".
+* 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
----------------------
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.
+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
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'.
+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
============
(Just hit Enter or Return when prompt for a password)
$ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib
+
+-----
+
+Copyright (C) 2001, 2003, 2004 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
projects / gnulib.git / blobdiff