3 @c Copyright 2001, 2003-2013 Free Software Foundation, Inc.
5 @c Permission is granted to copy, distribute and/or modify this document
6 @c under the terms of the GNU Free Documentation License, Version 1.3
7 @c or any later version published by the Free Software Foundation;
8 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
9 @c Texts. A copy of the license is included in the ``GNU Free
10 @c Documentation License'' file as part of this distribution.
15 * Keeping Up-to-date::
16 * Contributing to Gnulib::
21 @section Gnulib Basics
23 While portability across operating systems is not one of GNU's primary
24 goals, it has helped introduce many people to the GNU system, and is
25 worthwhile when it can be achieved at a low cost. This collection helps
28 Gnulib is intended to be the canonical source for most of the important
29 ``portability'' and/or common files for GNU projects. These are files
30 intended to be shared at the source level; Gnulib is not a typical
31 library meant to be installed and linked against. Thus, unlike most
32 projects, Gnulib does not normally generate a source tarball
33 distribution; instead, developers grab modules directly from the
36 The easiest, and recommended, way to do this is to use the
37 @command{gnulib-tool} script. Since there is no installation
38 procedure for Gnulib, @command{gnulib-tool} needs to be run directly
39 in the directory that contains the Gnulib source code. You can do
40 this either by specifying the absolute filename of
41 @command{gnulib-tool}, or by using a symbolic link from a place inside
42 your @env{PATH} to the @command{gnulib-tool} file of your preferred
43 Gnulib checkout. For example:
46 $ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool
52 Gnulib is available for anonymous checkout. In any Bourne-shell the
53 following should work:
56 $ git clone git://git.sv.gnu.org/gnulib.git
59 For a read-write checkout you need to have a login on
60 @samp{savannah.gnu.org} and be a member of the Gnulib project at
61 @url{http://savannah.gnu.org/projects/gnulib}. Then, instead of the
62 URL @url{git://git.sv.gnu.org/gnulib}, use the URL
63 @samp{ssh://@var{user}@@git.sv.gnu.org/srv/git/gnulib} where
64 @var{user} is your login name on savannah.gnu.org.
70 @url{http://en.wikipedia.org/wiki/Git_(software)}
72 @url{http://git-scm.com/}
75 When you use @code{git annotate} or @code{git blame} with Gnulib, it's
76 recommended that you use the @option{-w} option, in order to ignore
77 massive whitespace changes that happened in 2009.
79 CVS checkouts are also supported:
82 $ cvs -d :pserver:anonymous@@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
85 @node Keeping Up-to-date
86 @section Keeping Up-to-date
88 The best way to work with Gnulib is to check it out of git.
89 To synchronize, you can use @code{git pull},
90 or @code{cvs update -dP} if you are still using CVS.
92 Subscribing to the @email{bug-gnulib@@gnu.org} mailing list will help
93 you to plan when to update your local copy of Gnulib (which you use to
94 maintain your software) from git. You can review the archives,
96 @url{https://lists.gnu.org/mailman/listinfo/bug-gnulib}.
98 Sometimes, using an updated version of Gnulib will require you to use
99 newer versions of GNU Automake or Autoconf. You may find it helpful
100 to join the autotools-announce mailing list to be advised of such
103 @node Contributing to Gnulib
104 @section Contributing to Gnulib
106 All software here is copyrighted by the Free Software Foundation---you need
107 to have filled out an assignment form for a project that uses the
108 module for that contribution to be accepted here.
110 If you have a piece of code that you would like to contribute, please
111 email @email{bug-gnulib@@gnu.org}.
113 Generally we are looking for files that fulfill at least one of the
114 following requirements:
118 If your @file{.c} and @file{.h} files define functions that are broken or
119 missing on some other system, we should be able to include it.
122 If your functions remove arbitrary limits from existing
123 functions (either under the same name, or as a slightly different
124 name), we should be able to include it.
127 If your functions define completely new but rarely used functionality,
128 you should probably consider packaging it as a separate library.
132 * Indent with spaces not TABs::
133 * How to add a new module::
134 * Portability guidelines::
137 @node Gnulib licensing
138 @subsection Gnulib licensing
140 Gnulib contains code both under GPL and LGPL@. Because several packages
141 that use Gnulib are GPL, the files state they are licensed under GPL@.
142 However, to support LGPL projects as well, you may use some of the
143 files under LGPL@. The ``License:'' information in the files under
144 modules/ clarifies the real license that applies to the module source.
146 Keep in mind that if you submit patches to files in Gnulib, you should
147 license them under a compatible license, which means that sometimes
148 the contribution will have to be LGPL, if the original file is
149 available under LGPL via a ``License: LGPL'' information in the
150 projects' modules/ file.
152 @node Indent with spaces not TABs
153 @subsection Indent with spaces not TABs
155 We use space-only indentation in nearly all files. This includes all
156 @file{*.h}, @file{*.c}, @file{*.y} files, except for the @code{regex}
157 module. Makefile and ChangeLog files are excluded, since TAB
158 characters are part of their format.
160 In order to tell your editor to produce space-only indentation, you
161 can use these instructions.
165 For Emacs: Add these lines to your Emacs initialization file
166 (@file{$HOME/.emacs} or similar):
169 ;; In Gnulib, indent with spaces everywhere (not TABs).
170 ;; Exceptions: Makefile and ChangeLog modes.
171 (add-hook 'find-file-hook '(lambda ()
172 (if (and buffer-file-name
173 (string-match "/gnulib\\>" (buffer-file-name))
174 (not (string-equal mode-name "Change Log"))
175 (not (string-equal mode-name "Makefile")))
176 (setq indent-tabs-mode nil))))
180 For vi (vim): Add these lines to your @file{$HOME/.vimrc} file:
183 " Don't use tabs for indentation. Spaces are nicer to work with.
187 For Makefile and ChangeLog files, compensate for this by adding this
188 to your @file{$HOME/.vim/after/indent/make.vim} file, and similarly
189 for your @file{$HOME/.vim/after/indent/changelog.vim} file:
192 " Use tabs for indentation, regardless of the global setting.
197 For Eclipse: In the ``Window|Preferences'' dialog (or ``Eclipse|Preferences''
202 Under ``General|Editors|Text Editors'', select the ``Insert spaces for tabs''
206 Under ``C/C++|Code Style'', select a code style profile that has the
207 ``Indentation|Tab policy'' combobox set to ``Spaces only'', such as the
208 ``GNU [built-in]'' policy.
211 If you use the GNU indent program, pass it the option @option{--no-tabs}.
214 @node How to add a new module
215 @subsection How to add a new module
219 Add the header files and source files to @file{lib/}.
222 If the module needs configure-time checks, write an Autoconf
223 macro for it in @file{m4/@var{module}.m4}. See @file{m4/README} for details.
226 Write a module description @file{modules/@var{module}}, based on
227 @file{modules/TEMPLATE}.
230 If the module contributes a section to the end-user documentation,
231 put this documentation in @file{doc/@var{module}.texi} and add it to the ``Files''
232 section of @file{modules/@var{module}}. Most modules don't do this; they have only
233 documentation for the programmer (= Gnulib user). Such documentation
234 usually goes into the @file{lib/} source files. It may also go into @file{doc/};
235 but don't add it to the module description in this case.
238 Add the module to the list in @file{MODULES.html.sh}.
242 You can test that a module builds correctly with:
245 $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
247 $ ./configure && make
255 Check the license and copyright year of headers.
258 Check that the source code follows the GNU coding standards;
259 see @url{http://www.gnu.org/prep/standards}.
262 Add source files to @file{config/srclist*} if they are identical to upstream
263 and should be upgraded in Gnulib whenever the upstream source changes.
266 Include header files in source files to verify the function prototypes.
269 Make sure a replacement function doesn't cause warnings or clashes on
270 systems that have the function.
273 Autoconf functions can use @samp{gl_*} prefix. The @samp{AC_*} prefix is for
274 autoconf internal functions.
277 Build files only if they are needed on a platform. Look at the
278 @code{alloca} and @code{fnmatch} modules for how to achieve this. If
279 for some reason you cannot do this, and you have a @file{.c} file that
280 leads to an empty @file{.o} file on some platforms (through some big
281 @code{#if} around all the code), then ensure that the compilation unit
282 is not empty after preprocessing. One way to do this is to
283 @code{#include <stddef.h>} or @code{<stdio.h>} before the big
287 @node Portability guidelines
288 @subsection Portability guidelines
290 Gnulib code is intended to be portable to a wide variety of platforms,
291 not just GNU platforms. See the documentation section ``Target Platforms''
294 Many Gnulib modules exist so that applications need not worry about
295 undesirable variability in implementations. For example, an
296 application that uses the @code{malloc} module need not worry about
297 @code{malloc@ (0)} returning @code{NULL} on some Standard C
298 platforms; and @code{time_r} users need not worry about
299 @code{localtime_r} returning @code{int} (not @code{char@ *}) on some
300 platforms that predate POSIX 1003.1-2001.
302 Currently we assume at least a freestanding C89 compiler, possibly
303 operating with a C library that predates C89. The oldest environments
304 currently ported to are probably HP-UX 10.20 and IRIX 5.3, though we
305 are not testing these platforms very often.
307 Because we assume a freestanding C89 compiler, Gnulib code can include
308 @code{<float.h>}, @code{<limits.h>}, @code{<stdarg.h>}, and
309 @code{<stddef.h>} unconditionally. It can also assume the existence
310 of @code{<ctype.h>}, @code{<errno.h>}, @code{<fcntl.h>},
311 @code{<locale.h>}, @code{<signal.h>}, @code{<stdio.h>},
312 @code{<stdlib.h>}, @code{<string.h>}, and @code{<time.h>}. Similarly,
313 many modules include @code{<sys/types.h>} even though it's not even in
314 C99; that's OK since @code{<sys/types.h>} has been around nearly
317 Even if the include files exist, they may not conform to C89.
318 However, GCC has a @command{fixincludes} script that attempts to fix most
319 C89-conformance problems. So Gnulib currently assumes include files
320 largely conform to C89 or better. People still using ancient hosts
321 should use fixincludes or fix their include files manually.
323 Even if the include files conform to C89, the library itself may not.
324 For example, @code{strtod} and @code{mktime} have some bugs on some platforms.
325 You can work around some of these problems by requiring the relevant
326 modules, e.g., the Gnulib @code{mktime} module supplies a working and
327 conforming @code{mktime}.
329 The GNU coding standards allow one departure from strict C99: Gnulib
330 code can assume that standard internal types like @code{size_t} are no wider
331 than @code{long}. POSIX 1003.1-2001 and the GNU coding standards both
332 require @code{int} to be at least 32 bits wide, so Gnulib code assumes this
333 as well. Gnulib code makes the following additional assumptions:
337 Signed integer arithmetic is two's complement.
339 Previously, Gnulib code sometimes assumed that signed integer
340 arithmetic wraps around, but modern compiler optimizations
341 sometimes do not guarantee this, and Gnulib code with this
342 assumption is now considered to be questionable.
343 @xref{Integer Properties}.
345 Some Gnulib modules contain explicit support for the other signed
346 integer representations allowed by C99 (ones' complement and signed
347 magnitude), but these modules are the exception rather than the rule.
348 All practical Gnulib targets use two's complement.
351 There are no ``holes'' in integer values: all the bits of an integer
352 contribute to its value in the usual way.
355 Addresses and sizes behave as if objects reside in a flat address space.
360 If two nonoverlapping objects have sizes @var{S} and @var{T} represented as
361 @code{size_t} values, then @code{@var{S} + @var{T}} cannot overflow.
364 A pointer @var{P} points within an object @var{O} if and only if
365 @code{(char *) &@var{O} <= (char *) @var{P} && (char *) @var{P} <
366 (char *) (&@var{O} + 1)}.
369 If an existing object has size @var{S}, and if @var{T} is sufficiently
370 small (e.g., 8 KiB), then @code{@var{S} + @var{T}} cannot overflow.
371 Overflow in this case would mean that the rest of your program fits
372 into @var{T} bytes, which can't happen in realistic flat-address-space
376 Objects with all bits zero are treated as 0 or NULL@. For example,
377 @code{memset@ (A, 0, sizeof@ A)} initializes an array @code{A} of
381 Adding zero to a null pointer does not change the pointer.
382 For example, @code{0 + (char *) NULL == (char *) NULL}.
386 The above assumptions are not required by the C or POSIX standards but
387 hold on all practical porting targets that we're familiar with. If
388 you have a porting target where these assumptions are not true, we'd
389 appreciate hearing of any fixes. We need fixes that do not increase
390 runtime overhead on standard hosts and that are relatively easy to
393 With the above caveats, Gnulib code should port without problem to new
394 hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
395 Hence Gnulib code should avoid using constructs (e.g., undeclared
396 functions return @code{int}) that do not conform to C99.
399 @section High Quality
401 We develop and maintain a testsuite for Gnulib. The goal is to have a
402 100% firm interface so that maintainers can feel free to update to the
403 code in git at @emph{any} time and know that their application will not
404 break. This means that before any change can be committed to the
405 repository, a test suite program must be produced that exposes the bug
406 for regression testing. All experimental work should be done on
407 branches to help promote this.