/ [gnulib] / gnulib / README
To checkout: cvs -d:pserver:anonymous@cvs.gnu.org.ua:/cvsmirror/gnulib co gnulib/README

Annotation of /gnulib/README

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.20 - (hide annotations)
Sat Mar 31 12:34:54 2007 UTC (14 years, 9 months ago) by haible
Branch: MAIN
Changes since 1.19: +30 -11 lines
Talk primarily about git, not CVS.

1 karl 1.14 Gnulib
2 jbailey 1.1 ======
4 karl 1.14 Gnulib is intended to be the canonical source for most of the important
5     "portability" and/or common files for GNU projects. These are files
6     intended to be shared at the source level; Gnulib is not a library meant
7 eggert 1.15 to be installed and linked against. Unlike most projects, Gnulib does
8     not normally generate a source tarball distribution; instead, developers
9     should just grab modules directly from the repository.
10 karl 1.14
11     While portability across operating systems is not one of GNU's primary
12     goals, it has helped introduce many people to the GNU system, and is
13     worthwhile when it can be achieved at a low cost. This collection helps
14     lower that cost.
15 jbailey 1.1
17 karl 1.14 Contributing to Gnulib
18 jbailey 1.1 ======================
19     All software here is Copyright (c) Free Software Foundation - you need
20     to have filled out an assignment form for a project that uses the
21     module for that contribution to be accepted here.
23     If you have a piece of code that you would like to contribute, please
24 karl 1.14 email bug-gnulib@gnu.org. You can review the archives, subscribe, etc.,
25     via http://lists.gnu.org/mailman/listinfo/bug-gnulib.
26 jbailey 1.1
27     Generally we are looking for files that fulfill at least one of the
28     following requirements:
30     * If your .c and .h files define functions that are broken or
31     missing on some other system, we should be able to include it.
33     * If your functions remove arbitrary limits from existing
34     functions (either under the same name, or as a slightly different
35     name), we should be able to include it.
37     If your functions define completely new but rarely used functionality,
38 haible 1.4 you should probably consider packaging it as a separate library.
39 haible 1.2
40 karl 1.14
41 haible 1.11 License
42     -------
43 karl 1.14 Gnulib contains code both under GPL and LGPL. Because several packages
44     that use Gnulib are GPL, the files state they are licensed under GPL.
45 haible 1.11 However, to support LGPL projects as well, you may use some of the
46     files under LGPL. The "License:" information in the files under
47 jas 1.13 modules/ clarifies the real license that applies to the module source.
48 haible 1.11
49 karl 1.14 Keep in mind that if you submit patches to files in Gnulib, you should
50 jas 1.13 license them under a compatible license, which means that sometimes
51 haible 1.11 the contribution will have to be LGPL, if the original file is
52     available under LGPL via a "License: LGPL" information in the
53     projects' modules/ file.
55 karl 1.14
56 haible 1.2 How to add a new module
57     -----------------------
58     * Add the header files and source files to lib/.
59     * If the module needs configure-time checks, write an autoconf
60     macro for it in m4/<module>.m4. See m4/README for details.
61     * Write a module description modules/<module>, based on modules/TEMPLATE.
62 haible 1.16 * If the module contributes a section to the end-user documentation,
63     put this documentation in doc/<module>.texi and add it to the "Files"
64     section of modules/<module>. Most modules don't do this; they have only
65     documentation for the programmer (= gnulib user). Such documentation
66     usually goes into the lib/ source files. It may also go into doc/;
67     but don't add it to the module description in this case.
68 haible 1.2 * Add the module to the list in MODULES.html.sh.
70     You can test that a module builds correctly with:
71     $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
72     $ cd /tmp/testdir
73     $ ./configure && make
75     Other things:
76     * Check the license and copyright year of headers.
77 eggert 1.5 * Check that the source code follows the GNU coding standards;
78     see <http://www.gnu.org/prep/standards>.
79 haible 1.2 * Add source files to config/srclist* if they are identical to upstream
80     and should be upgraded in gnulib whenever the upstream source changes.
81     * Include header files in source files to verify the function prototypes.
82     * Make sure a replacement function doesn't cause warnings or clashes on
83     systems that have the function.
84     * Autoconf functions can use gl_* prefix. The AC_* prefix is for
85     autoconf internal functions.
86 eggert 1.7 * Build files only if they are needed on a platform. Look at the
87     alloca and fnmatch modules for how to achieve this. If for some
88     reason you cannot do this, and you have a .c file that leads to an
89     empty .o file on some platforms (through some big #if around all the
90     code), then ensure that the compilation unit is not empty after
91     preprocessing. One way to do this is to #include <stddef.h> or
92     <stdio.h> before the big #if.
93 eggert 1.5
94     Portability guidelines
95     ----------------------
97 karl 1.14 Gnulib code is intended to be portable to a wide variety of platforms,
98 eggert 1.5 not just GNU platforms.
100 karl 1.14 Many Gnulib modules exist so that applications need not worry about
101 eggert 1.5 undesirable variability in implementations. For example, an
102     application that uses the 'malloc' module need not worry about (malloc
103     (0)) returning NULL on some Standard C platforms; and 'time_r' users
104     need not worry about localtime_r returning int (not char *) on some
105     platforms that predate POSIX 1003.1-2001.
107 karl 1.14 Originally much of the Gnulib code was portable to ancient hosts like
108 eggert 1.5 4.2BSD, but it is a maintenance hassle to maintain compatibility with
109     unused hosts, so currently we assume at least a freestanding C89
110     compiler, possibly operating with a C library that predates C89. The
111     oldest environment currently ported to is probably SunOS 4 + GCC 1.x,
112     though we haven't tested this exact combination. SunOS 4 last shipped
113     on 1998-09-30, and Sun dropped support for it on 2003-10-01, so at
114     some point we may start assuming a C89 library as well.
116 karl 1.14 Because we assume a freestanding C89 compiler, Gnulib code can include
117 eggert 1.5 <float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally. It
118     can also include hosted headers like <errno.h> that were present in
119     Unix Version 7 and are thus widely available. Similarly, many modules
120     include <sys/types.h> even though it's not even in C99; that's OK
121     since <sys/types.h> has been around nearly forever. <string.h> and
122     <stdlib.h> were not in Unix Version 7, so they weren't universally
123     available on ancient hosts, but they are both in SunOS 4 (the oldest
124 karl 1.14 platform still in relatively-common use) so Gnulib assumes them now.
125 eggert 1.5
126     Even if the include files exist, they may not conform to C89.
127     However, GCC has a "fixincludes" script that attempts to fix most
128 karl 1.14 C89-conformance problems. So Gnulib currently assumes include files
129 eggert 1.5 largely conform to C89 or better. People still using ancient hosts
130     should use fixincludes or fix their include files manually.
132     Even if the include files conform to C89, the library itself may not.
133 karl 1.14 For example, SunOS 4's (free (NULL)) can dump core, so Gnulib code
134 eggert 1.5 must avoid freeing a null pointer, even though C89 allows it.
135 eggert 1.10 You can work around some of these problems by requiring the relevant
136 karl 1.14 modules, e.g., the Gnulib 'free' module supplies a conforming 'free'.
137 eggert 1.5
138 karl 1.14 The GNU coding standards allow one departure from strict C99: Gnulib
139 eggert 1.6 code can assume that standard internal types like size_t are no wider
140     than 'long'. POSIX 1003.1-2001 and the GNU coding standards both
141 karl 1.14 require 'int' to be at least 32 bits wide, so Gnulib code assumes this
142     as well. Gnulib code makes the following additional assumptions:
143 eggert 1.6
144 eggert 1.19 * With one exception noted below, signed integer arithmetic is two's
145     complement, without runtime overflow checking. This is the
146     traditional behavior, and is supported by C99 implementations that
147     conform to ISO/IEC 10967-1 (LIA-1) and that define signed integer
148     types as being modulo.
150     The exception is signed loop indexes. Here, the behavior is
151     undefined if any signed expression derived from the loop index
152     overflows. For example, the following code contains two such
153     overflows (the "i++" and the "i + 1") and therefore has undefined
154     behavior:
156     int i;
157     for (i = INT_MAX - 10; i <= INT_MAX; i++)
158     if (i + 1 < 0)
159     {
160     report_overflow ();
161     break;
162     }
164     This exception is a concession to modern optimizing compilers,
165     which can turn the above loop into code that executes the loop body
166     11 times, even though wraparound arithmetic would cause the loop to
167     iterate forever.
168 eggert 1.6
169     * There are no "holes" in integer values: all the bits of an integer
170     contribute to its value in the usual way.
172     * If two nonoverlapping objects have sizes S and T represented as
173     size_t values, then S + T cannot overflow. This assumption is true
174     for all practical hosts with flat address spaces, but it is not
175     always true for hosts with segmented address spaces.
177 eggert 1.9 * If an existing object has size S, and if T is sufficiently small
178     (e.g., 8 KiB), then S + T cannot overflow. Overflow in this case
179     would mean that the rest of your program fits into T bytes, which
180     can't happen in realistic flat-address-space hosts.
182 eggert 1.6 * Objects with all bits zero are treated as 0 or NULL. For example,
183     memset (A, 0, sizeof A) initializes an array A of pointers to NULL.
185 eggert 1.8 * Adding zero to a null pointer does not change the pointer.
186     For example, 0 + (char *) NULL == (char *) NULL.
188 eggert 1.6 The above assumptions are not required by the C or POSIX standards but
189     hold on all practical porting targets that we're familiar with. If
190     you have a porting target where these assumptions are not true, we'd
191     appreciate hearing of any fixes. We need fixes that do not increase
192     runtime overhead on standard hosts and that are relatively easy to
193     maintain.
195 karl 1.14 With the above caveats, Gnulib code should port without problem to new
196 eggert 1.6 hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
197 karl 1.14 Hence Gnulib code should avoid using constructs (e.g., undeclared
198 eggert 1.6 functions return 'int') that do not conform to C99.
199 jbailey 1.1
200     High Quality
201     ============
203     We will be developing a testsuite for these applications. The goal is
204     to have a 100% firm interface so that maintainers can feel free to
205 haible 1.20 update to the code in git at *any* time and know that their
206 jbailey 1.1 application will not break. This means that before any change can be
207     committed to the repository, a test suite program must be produced
208     that exposes the bug for regression testing. All experimental work
209     should be done on branches to help promote this.
211 haible 1.20 git and CVS
212     ===========
213 jbailey 1.1
214 karl 1.14 Gnulib is available for anonymous checkout. In any Bourne-shell the
215 jbailey 1.1 following should work:
216 haible 1.20 $ git clone git://git.sv.gnu.org/gnulib
217     Or, if you prefer the CVS-like 'cogito' frontend to plain 'git':
218     $ cg clone git://git.sv.gnu.org/gnulib
220     git resources:
221     Overview: http://en.wikipedia.org/wiki/Git_(software)
222     Homepage: http://git.or.cz/
223     Download: http://www.kernel.org/pub/software/scm/git/
224     Tutorial: http://git.or.cz/course/
225     http://www.kernel.org/pub/software/scm/git/docs/tutorial.html
226     FAQ: http://git.or.cz/gitwiki/GitFaq
228     cogito resources:
229     Overview: http://en.wikipedia.org/wiki/Cogito_(software)
230     Homepage: http://git.or.cz/cogito/
231     Download: http://kernel.org/pub/software/scm/cogito/
232     Tutorial: http://git.or.cz/course/
234     For those among us who have tightly limited disk space and a fast network
235     connection, CVS checkouts are also supported:
236     $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib login
237     (Just hit Enter or Return when prompted for a password)
238     $ cvs -d :pserver:anoncvs@cvs.gnu.org:/cvsroot/gnulib checkout gnulib
239 jbailey 1.1
240 karl 1.14 Gnulib is hosted on savannah.gnu.org. The project page is
241     http://savannah.gnu.org/projects/gnulib.
243 eggert 1.18 Keeping Up-to-date
244     ==================
246 haible 1.20 The best way to work with Gnulib is to check it out of git.
247 eggert 1.18 Subscribing to the bug-gnulib@gnu.org mailing list will help you to
248     plan when to update your local copy of Gnulib (which you use to
249 haible 1.20 maintain your software) from git. To synchronize, you can use "git pull"
250     or "cg update", or "cvs update -dP" if you are still using CVS.
251 eggert 1.18
252     Sometimes, using an updated version of Gnulib will require you to use
253     newer versions of GNU Automake or Autoconf. You may find it helpful
254     to join the autotools-announce mailing list to be advised of such
255     changes.
257 eggert 1.10
258     -----
259 haible 1.20 Copyright (C) 2001, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
260 eggert 1.10
261     This program is free software; you can redistribute it and/or modify
262     it under the terms of the GNU General Public License as published by
263     the Free Software Foundation; either version 2, or (at your option)
264     any later version.
266     This program is distributed in the hope that it will be useful,
267     but WITHOUT ANY WARRANTY; without even the implied warranty of
269     GNU General Public License for more details.
271     You should have received a copy of the GNU General Public License
272     along with this program; if not, write to the Free Software Foundation,
273 eggert 1.12 Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */

Send suggestions and bug reports to Sergey Poznyakoff
ViewVC Help
Powered by ViewVC 1.1.20