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.
+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://<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
+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.
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:
preprocessing. One way to do this is to #include <stddef.h> or
<stdio.h> before the big #if.
+
Portability guidelines
----------------------
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.
+ * 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.
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.
+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 (C) 2001, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+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
+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.
+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
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. */
+along with this program. If not, see <http://www.gnu.org/licenses/>.
projects / gnulib.git / blobdiff