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