X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=README;h=921cfe737ef303c3b32e018deff7700fc0951a4c;hb=a6b16b69fe1cad695b270dd5bf3deb2850fc4dd1;hp=413c1533b4de243b0e0d4620631129b5e4b9a1b1;hpb=76a774bce0ece69de840208c0aca98a9fdbc68ff;p=gnulib.git diff --git a/README b/README index 413c1533b..921cfe737 100644 --- a/README +++ b/README @@ -1,29 +1,90 @@ -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. -Contributing to 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 + +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 +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: @@ -38,13 +99,78 @@ 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. + + +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/.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: @@ -54,6 +180,8 @@ 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 . * 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. @@ -61,34 +189,128 @@ Other things: 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 or #include 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 or + before the big #if. + + +Portability guidelines +---------------------- + +Gnulib code is intended to be portable to a wide variety of platforms, +not just GNU platforms. See the documentation section "Target Platforms" +for details. + +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. + +Currently we assume at least a freestanding C89 compiler, possibly +operating with a C library that predates C89. The oldest environments +currently ported to are probably HP-UX 10.20 and IRIX 5.3, though we +are not testing these platforms very often. + +Because we assume a freestanding C89 compiler, Gnulib code can include +, , , and unconditionally. It +can also assume the existence of , , , +, , , , , and . +Similarly, many modules include even though it's not even +in C99; that's OK since has been around nearly forever. + +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, strtod and mktime have some bugs on some platforms. +You can work around some of these problems by requiring the relevant +modules, e.g., the Gnulib 'mktime' module supplies a working and +conforming 'mktime'. + +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. + + Previously, gnulib code sometimes assumed that signed integer + arithmetic wraps around, but modern compiler optimizations + sometimes do not guarantee this, and gnulib code with this + assumption is now considered to be questionable. For more, please + see the file doc/intprops.texi. + + Some gnulib modules contain explicit support for the other signed + integer representations allowed by C99 (ones' complement and signed + magnitude), but these modules are the exception rather than the rule. + All practical gnulib targets use two's complement. + + * 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-2011 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 .