-GNULib
+Gnulib
======
-GNULib is inteded to be the canonical source for most of the important
-"Portability" files for GNU projects.
+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.
-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.
+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 typical
+library meant to be installed and linked against. Thus, unlike most
+projects, Gnulib does not normally generate a source tarball
+distribution; instead, developers grab modules directly from the
+source repository.
-There are three directories that contain all of the files:
+The easiest, and recommended, way to do this is to use the gnulib-tool
+script. Since there is no installation procedure for Gnulib,
+gnulib-tool needs to be run directly in the directory that contains the
+Gnulib source code. You can do this either by specifying the absolute
+filename of gnulib-tool, or by using a symbolic link from a
+place inside your PATH to the gnulib-tool file of your preferred
+Gnulib checkout. For example:
+ $ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool
-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.'
+The home page for Gnulib is http://www.gnu.org/software/gnulib.
+
+
+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.git
+
+For a read-write checkout you need to have a login on savannah.gnu.org and be
+a member of the gnulib project at http://savannah.gnu.org/projects/gnulib .
+Then, instead of the URL
+ git://git.sv.gnu.org/gnulib
+use the URL
+ ssh://<user>@git.sv.gnu.org/srv/git/gnulib
+where <user> is your login name on savannah.gnu.org.
+
+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
+
+When you use "git annotate" or "git blame" with gnulib, it's recommended that
+you use the "-w" option, in order to ignore massive whitespace changes that
+happened in 2009.
+
+CVS checkouts are also supported:
+ $ cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
+
+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 "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.
-Contributing to GNULib
-======================
-All software here is Copyright (c) Free Software Foundation - you need
+Contributing to Gnulib
+======================
+All software here is copyrighted by the 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.
+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:
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 seperate library.
+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.
+
+
+Indent with spaces, not TABs
+----------------------------
+We use space-only indentation in nearly all files. This includes all
+*.h, *.c, *.y files, except for the regex module. Makefile and ChangeLog
+files are excluded, since TAB characters are part of their format.
+
+In order to tell your editor to produce space-only indentation, you
+can use these instructions.
+
+ * For Emacs: Add these lines to your Emacs initialization file
+ ($HOME/.emacs or similar):
+
+ ;; In gnulib, indent with spaces everywhere (not TABs).
+ ;; Exceptions: Makefile and ChangeLog modes.
+ (add-hook 'find-file-hook '(lambda ()
+ (if (and buffer-file-name
+ (string-match "/gnulib\\>" (buffer-file-name))
+ (not (string-equal mode-name "Change Log"))
+ (not (string-equal mode-name "Makefile")))
+ (setq indent-tabs-mode nil))))
+
+ * For vi (vim): Add these lines to your $HOME/.vimrc file:
+
+ " Don't use tabs for indentation. Spaces are nicer to work with.
+ set expandtab
+
+ For Makefile and ChangeLog files, compensate this by adding this to
+ your $HOME/.vim/after/indent/make.vim and
+ $HOME/.vim/after/indent/changelog.vim files:
+
+ " Use tabs for indentation, regardless of the global setting.
+ set noexpandtab
+
+ * For Eclipse: In the "Window|Preferences" dialog (or "Eclipse|Preferences"
+ dialog on MacOS),
+ 1. Under "General|Editors|Text Editors", select the "Insert spaces for tabs"
+ checkbox.
+ 2. Under "C/C++|Code Style", select a code style profile that has the
+ "Indentation|Tab policy" combobox set to "Spaces only", such as the
+ "GNU [built-in]" policy.
+
+If you use the GNU indent program, pass it the option '--no-tabs'.
+
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:
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.
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).
+* 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 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.
+We develop and maintain a testsuite for Gnulib. 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.
-CVS
-===
-GNULib is available for anonymous checkout. In any Bourne-shell the
-following should work:
+-----
+Copyright 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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 3 of the License, or
+(at your option) any later version.
-$ 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
+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, see <http://www.gnu.org/licenses/>.
projects / gnulib.git / blobdiff