X-Git-Url: http://erislabs.net/gitweb/?p=gnulib.git;a=blobdiff_plain;f=README;h=0191f7a93eeef53463aca05e92476cc53dc8bf1f;hp=4b699a7a230d2f718361de34efc89001b7510576;hb=54c3ba61dfdf260865f2a6529ab414e24da17cf5;hpb=10cecf2f783bf0504f05947787495a0d2a75db04 diff --git a/README b/README index 4b699a7a2..0191f7a93 100644 --- a/README +++ b/README @@ -1,286 +1 @@ -Gnulib -====== - -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. - -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. - -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 - -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://@git.sv.gnu.org/srv/git/gnulib -where 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 - -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 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. 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/.m4. See m4/README for details. -* Write a module description modules/, based on modules/TEMPLATE. -* If the module contributes a section to the end-user documentation, - put this documentation in doc/.texi and add it to the "Files" - section of modules/. 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 . -* 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 or - 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 -, , , and unconditionally. It -can also include hosted headers like that were present in -Unix Version 7 and are thus widely available. Similarly, many modules -include even though it's not even in C99; that's OK -since has been around nearly forever. and - 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 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. - - ------ -Copyright 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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. - -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 . +Please see doc/gnulib-readme.texi for basic information about Gnulib.