README 13.6 KB
Newer Older
Karl Berry's avatar
Karl Berry committed
1
Gnulib
2
3
======

Karl Berry's avatar
Karl Berry committed
4
5
6
7
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.
8

9
10
11
12
13
14
15
16
17
18
19
20
21
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
22
place inside your PATH to the gnulib-tool file of your preferred
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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

52
53
54
55
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.

Jim Meyering's avatar
Jim Meyering committed
56
CVS checkouts are also supported:
57
58
59
60
61
62
63
64
65
66
67
68
  $ 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
Jim Meyering's avatar
Jim Meyering committed
69
70
maintain your software) from git.  To synchronize, you can use "git pull",
or "cvs update -dP" if you are still using CVS.
71
72
73
74
75
76

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.

77

Karl Berry's avatar
Karl Berry committed
78
Contributing to Gnulib
79
======================
Bruno Haible's avatar
Bruno Haible committed
80

81
All software here is copyrighted by the Free Software Foundation - you need
82
83
84
85
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
Karl Berry's avatar
Karl Berry committed
86
87
email bug-gnulib@gnu.org.  You can review the archives, subscribe, etc.,
via http://lists.gnu.org/mailman/listinfo/bug-gnulib.
88
89
90
91
92
93
94
95
96
97
98
99

Generally we are looking for files that fulfill at least one of the
following requirements:

    * If your .c and .h files define functions that are broken or
missing on some other system, we should be able to include it.

    * If your functions remove arbitrary limits from existing
functions (either under the same name, or as a slightly different
name), we should be able to include it.

If your functions define completely new but rarely used functionality,
Bruno Haible's avatar
Bruno Haible committed
100
you should probably consider packaging it as a separate library.
101

Karl Berry's avatar
Karl Berry committed
102

103
104
License
-------
Karl Berry's avatar
Karl Berry committed
105
106
Gnulib contains code both under GPL and LGPL.  Because several packages
that use Gnulib are GPL, the files state they are licensed under GPL.
107
108
However, to support LGPL projects as well, you may use some of the
files under LGPL.  The "License:" information in the files under
109
modules/ clarifies the real license that applies to the module source.
110

Karl Berry's avatar
Karl Berry committed
111
Keep in mind that if you submit patches to files in Gnulib, you should
112
license them under a compatible license, which means that sometimes
113
114
115
116
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.

Karl Berry's avatar
Karl Berry committed
117

118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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"
152
    dialog on Mac OS),
153
154
155
156
157
158
159
160
161
    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'.


162
163
164
165
166
167
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.
168
169
170
171
172
173
* 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.
174
175
176
177
178
179
180
181
182
* Add the module to the list in MODULES.html.sh.

You can test that a module builds correctly with:
  $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
  $ cd /tmp/testdir
  $ ./configure && make

Other things:
* Check the license and copyright year of headers.
183
184
* Check that the source code follows the GNU coding standards;
  see <http://www.gnu.org/prep/standards>.
185
186
187
188
189
190
191
* 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.
* Make sure a replacement function doesn't cause warnings or clashes on
  systems that have the function.
* Autoconf functions can use gl_* prefix. The AC_* prefix is for
  autoconf internal functions.
192
193
194
195
196
197
198
* 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 <stddef.h> or
  <stdio.h> before the big #if.
199

200

201
202
203
Portability guidelines
----------------------

Karl Berry's avatar
Karl Berry committed
204
Gnulib code is intended to be portable to a wide variety of platforms,
Bruno Haible's avatar
Bruno Haible committed
205
206
not just GNU platforms.  See the documentation section "Target Platforms"
for details.
207

Karl Berry's avatar
Karl Berry committed
208
Many Gnulib modules exist so that applications need not worry about
209
210
211
212
213
214
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.

Bruno Haible's avatar
Bruno Haible committed
215
Currently we assume at least a freestanding C89 compiler, possibly
Paul Eggert's avatar
Paul Eggert committed
216
operating with a C library that predates C89.  The oldest environments
Bruno Haible's avatar
Bruno Haible committed
217
currently ported to are probably HP-UX 10.20 and IRIX 5.3, though we
Paul Eggert's avatar
Paul Eggert committed
218
are not testing these platforms very often.
219

Karl Berry's avatar
Karl Berry committed
220
Because we assume a freestanding C89 compiler, Gnulib code can include
221
<float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally.  It
222
can also assume the existence of <ctime.h>, <errno.h>, <fcntl.h>,
Bruno Haible's avatar
Bruno Haible committed
223
224
225
<locale.h>, <signal.h>, <stdio.h>, <stdlib.h>, <string.h>, and <time.h>.
Similarly, many modules include <sys/types.h> even though it's not even
in C99; that's OK since <sys/types.h> has been around nearly forever.
226
227
228

Even if the include files exist, they may not conform to C89.
However, GCC has a "fixincludes" script that attempts to fix most
Karl Berry's avatar
Karl Berry committed
229
C89-conformance problems.  So Gnulib currently assumes include files
230
231
232
233
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.
Bruno Haible's avatar
Bruno Haible committed
234
For example, strtod and mktime have some bugs on some platforms.
235
You can work around some of these problems by requiring the relevant
Bruno Haible's avatar
Bruno Haible committed
236
237
modules, e.g., the Gnulib 'mktime' module supplies a working and
conforming 'mktime'.
238

Karl Berry's avatar
Karl Berry committed
239
The GNU coding standards allow one departure from strict C99: Gnulib
240
241
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
Karl Berry's avatar
Karl Berry committed
242
243
require 'int' to be at least 32 bits wide, so Gnulib code assumes this
as well.  Gnulib code makes the following additional assumptions:
244

245
246
247
248
249
250
251
252
253
254
255
256
 * 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.
257
258
259
260

 * There are no "holes" in integer values: all the bits of an integer
   contribute to its value in the usual way.

261
262
263
264
265
266
267
268
269
270
271
272
273
 * Addresses and sizes behave as if objects reside in a flat address space.
   In particular:

   - If two nonoverlapping objects have sizes S and T represented as
     size_t values, then S + T cannot overflow.

   - A pointer P points within an object O if and only if
     (char *) &O <= (char *) P && (char *) P < (char *) (&O + 1).

   - 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.
274

275
276
277
 * 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.

Paul Eggert's avatar
Paul Eggert committed
278
279
280
 * Adding zero to a null pointer does not change the pointer.
   For example, 0 + (char *) NULL == (char *) NULL.

281
282
283
284
285
286
287
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.

Karl Berry's avatar
Karl Berry committed
288
With the above caveats, Gnulib code should port without problem to new
289
hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
Karl Berry's avatar
Karl Berry committed
290
Hence Gnulib code should avoid using constructs (e.g., undeclared
291
functions return 'int') that do not conform to C99.
292

293

294
295
296
High Quality
============

297
298
299
300
301
302
303
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.
304

305

Karl Berry's avatar
Karl Berry committed
306
-----
307
Copyright 2001, 2003-2012 Free Software Foundation, Inc.
308

309
This program is free software: you can redistribute it and/or modify
310
it under the terms of the GNU General Public License as published by
311
312
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
313
314
315
316
317
318
319

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
320
along with this program.  If not, see <http://www.gnu.org/licenses/>.