dup2: Move AC_LIBOBJ invocation to module description.
[pspp] / README
1 Gnulib
2 ======
3
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
7 lower that cost.
8
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
15 source repository.
16
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
25
26 The home page for Gnulib is http://www.gnu.org/software/gnulib.
27
28
29 git and CVS
30 ===========
31
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
35
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
40 use the URL
41   ssh://<user>@git.sv.gnu.org/srv/git/gnulib
42 where <user> is your login name on savannah.gnu.org.
43
44 git resources:
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
51
52 When you use "git annotate" or "git blame" with gnulib, it's recommended that
53 you use the "-w" option, in order to ignore massive whitespace changes that
54 happened in 2009.
55
56 CVS checkouts are also supported:
57   $ cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
58
59 Gnulib is hosted on savannah.gnu.org.  The project page is
60 http://savannah.gnu.org/projects/gnulib.
61
62
63 Keeping Up-to-date
64 ==================
65
66 The best way to work with Gnulib is to check it out of git.
67 Subscribing to the bug-gnulib@gnu.org mailing list will help you to
68 plan when to update your local copy of Gnulib (which you use to
69 maintain your software) from git.  To synchronize, you can use "git pull",
70 or "cvs update -dP" if you are still using CVS.
71
72 Sometimes, using an updated version of Gnulib will require you to use
73 newer versions of GNU Automake or Autoconf.  You may find it helpful
74 to join the autotools-announce mailing list to be advised of such
75 changes.
76
77
78 Contributing to Gnulib
79 ======================
80
81 All software here is copyrighted by the Free Software Foundation - you need
82 to have filled out an assignment form for a project that uses the
83 module for that contribution to be accepted here.
84
85 If you have a piece of code that you would like to contribute, please
86 email bug-gnulib@gnu.org.  You can review the archives, subscribe, etc.,
87 via http://lists.gnu.org/mailman/listinfo/bug-gnulib.
88
89 Generally we are looking for files that fulfill at least one of the
90 following requirements:
91
92     * If your .c and .h files define functions that are broken or
93 missing on some other system, we should be able to include it.
94
95     * If your functions remove arbitrary limits from existing
96 functions (either under the same name, or as a slightly different
97 name), we should be able to include it.
98
99 If your functions define completely new but rarely used functionality,
100 you should probably consider packaging it as a separate library.
101
102
103 License
104 -------
105 Gnulib contains code both under GPL and LGPL.  Because several packages
106 that use Gnulib are GPL, the files state they are licensed under GPL.
107 However, to support LGPL projects as well, you may use some of the
108 files under LGPL.  The "License:" information in the files under
109 modules/ clarifies the real license that applies to the module source.
110
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 the contribution will have to be LGPL, if the original file is
114 available under LGPL via a "License: LGPL" information in the
115 projects' modules/ file.
116
117
118 Indent with spaces, not TABs
119 ----------------------------
120 We use space-only indentation in nearly all files. This includes all
121 *.h, *.c, *.y files, except for the regex module. Makefile and ChangeLog
122 files are excluded, since TAB characters are part of their format.
123
124 In order to tell your editor to produce space-only indentation, you
125 can use these instructions.
126
127   * For Emacs: Add these lines to your Emacs initialization file
128     ($HOME/.emacs or similar):
129
130       ;; In gnulib, indent with spaces everywhere (not TABs).
131       ;; Exceptions: Makefile and ChangeLog modes.
132       (add-hook 'find-file-hook '(lambda ()
133         (if (and buffer-file-name
134                  (string-match "/gnulib\\>" (buffer-file-name))
135                  (not (string-equal mode-name "Change Log"))
136                  (not (string-equal mode-name "Makefile")))
137             (setq indent-tabs-mode nil))))
138
139   * For vi (vim): Add these lines to your $HOME/.vimrc file:
140
141       " Don't use tabs for indentation. Spaces are nicer to work with.
142       set expandtab
143
144     For Makefile and ChangeLog files, compensate this by adding this to
145     your $HOME/.vim/after/indent/make.vim and
146     $HOME/.vim/after/indent/changelog.vim files:
147
148       " Use tabs for indentation, regardless of the global setting.
149       set noexpandtab
150
151   * For Eclipse: In the "Window|Preferences" dialog (or "Eclipse|Preferences"
152     dialog on MacOS),
153     1. Under "General|Editors|Text Editors", select the "Insert spaces for tabs"
154        checkbox.
155     2. Under "C/C++|Code Style", select a code style profile that has the
156        "Indentation|Tab policy" combobox set to "Spaces only", such as the
157        "GNU [built-in]" policy.
158
159 If you use the GNU indent program, pass it the option '--no-tabs'.
160
161
162 How to add a new module
163 -----------------------
164 * Add the header files and source files to lib/.
165 * If the module needs configure-time checks, write an autoconf
166   macro for it in m4/<module>.m4. See m4/README for details.
167 * Write a module description modules/<module>, based on modules/TEMPLATE.
168 * If the module contributes a section to the end-user documentation,
169   put this documentation in doc/<module>.texi and add it to the "Files"
170   section of modules/<module>.  Most modules don't do this; they have only
171   documentation for the programmer (= gnulib user).  Such documentation
172   usually goes into the lib/ source files.  It may also go into doc/;
173   but don't add it to the module description in this case.
174 * Add the module to the list in MODULES.html.sh.
175
176 You can test that a module builds correctly with:
177   $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
178   $ cd /tmp/testdir
179   $ ./configure && make
180
181 Other things:
182 * Check the license and copyright year of headers.
183 * Check that the source code follows the GNU coding standards;
184   see <http://www.gnu.org/prep/standards>.
185 * Add source files to config/srclist* if they are identical to upstream
186   and should be upgraded in gnulib whenever the upstream source changes.
187 * Include header files in source files to verify the function prototypes.
188 * Make sure a replacement function doesn't cause warnings or clashes on
189   systems that have the function.
190 * Autoconf functions can use gl_* prefix. The AC_* prefix is for
191   autoconf internal functions.
192 * Build files only if they are needed on a platform.  Look at the
193   alloca and fnmatch modules for how to achieve this.  If for some
194   reason you cannot do this, and you have a .c file that leads to an
195   empty .o file on some platforms (through some big #if around all the
196   code), then ensure that the compilation unit is not empty after
197   preprocessing.  One way to do this is to #include <stddef.h> or
198   <stdio.h> before the big #if.
199
200
201 Portability guidelines
202 ----------------------
203
204 Gnulib code is intended to be portable to a wide variety of platforms,
205 not just GNU platforms.  See the documentation section "Target Platforms"
206 for details.
207
208 Many Gnulib modules exist so that applications need not worry about
209 undesirable variability in implementations.  For example, an
210 application that uses the 'malloc' module need not worry about (malloc
211 (0)) returning NULL on some Standard C platforms; and 'time_r' users
212 need not worry about localtime_r returning int (not char *) on some
213 platforms that predate POSIX 1003.1-2001.
214
215 Currently we assume at least a freestanding C89 compiler, possibly
216 operating with a C library that predates C89.  The oldest environments
217 currently ported to are probably HP-UX 10.20 and IRIX 5.3, though we
218 are not testing these platforms very often.
219
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>,
223 <locale.h>, <signal.h>, <stdio.h>, <stdlib.h>, <string.h>, and <time.h>.
224 Similarly, many modules include <sys/types.h> even though it's not even
225 in C99; that's OK since <sys/types.h> has been around nearly forever.
226
227 Even if the include files exist, they may not conform to C89.
228 However, GCC has a "fixincludes" script that attempts to fix most
229 C89-conformance problems.  So Gnulib currently assumes include files
230 largely conform to C89 or better.  People still using ancient hosts
231 should use fixincludes or fix their include files manually.
232
233 Even if the include files conform to C89, the library itself may not.
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
236 modules, e.g., the Gnulib 'mktime' module supplies a working and
237 conforming 'mktime'.
238
239 The GNU coding standards allow one departure from strict C99: Gnulib
240 code can assume that standard internal types like size_t are no wider
241 than 'long'.  POSIX 1003.1-2001 and the GNU coding standards both
242 require 'int' to be at least 32 bits wide, so Gnulib code assumes this
243 as well.  Gnulib code makes the following additional assumptions:
244
245  * Signed integer arithmetic is two's complement.
246
247    Previously, gnulib code sometimes assumed that signed integer
248    arithmetic wraps around, but modern compiler optimizations
249    sometimes do not guarantee this, and gnulib code with this
250    assumption is now considered to be questionable.  For more, please
251    see the file doc/intprops.texi.
252
253    Some gnulib modules contain explicit support for the other signed
254    integer representations allowed by C99 (ones' complement and signed
255    magnitude), but these modules are the exception rather than the rule.
256    All practical gnulib targets use two's complement.
257
258  * There are no "holes" in integer values: all the bits of an integer
259    contribute to its value in the usual way.
260
261  * If two nonoverlapping objects have sizes S and T represented as
262    size_t values, then S + T cannot overflow.  This assumption is true
263    for all practical hosts with flat address spaces, but it is not
264    always true for hosts with segmented address spaces.
265
266  * If an existing object has size S, and if T is sufficiently small
267    (e.g., 8 KiB), then S + T cannot overflow.  Overflow in this case
268    would mean that the rest of your program fits into T bytes, which
269    can't happen in realistic flat-address-space hosts.
270
271  * Objects with all bits zero are treated as 0 or NULL.  For example,
272    memset (A, 0, sizeof A) initializes an array A of pointers to NULL.
273
274  * Adding zero to a null pointer does not change the pointer.
275    For example, 0 + (char *) NULL == (char *) NULL.
276
277 The above assumptions are not required by the C or POSIX standards but
278 hold on all practical porting targets that we're familiar with.  If
279 you have a porting target where these assumptions are not true, we'd
280 appreciate hearing of any fixes.  We need fixes that do not increase
281 runtime overhead on standard hosts and that are relatively easy to
282 maintain.
283
284 With the above caveats, Gnulib code should port without problem to new
285 hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
286 Hence Gnulib code should avoid using constructs (e.g., undeclared
287 functions return 'int') that do not conform to C99.
288
289
290 High Quality
291 ============
292
293 We develop and maintain a testsuite for Gnulib.  The goal is to have a
294 100% firm interface so that maintainers can feel free to update to the
295 code in git at *any* time and know that their application will not
296 break.  This means that before any change can be committed to the
297 repository, a test suite program must be produced that exposes the bug
298 for regression testing.  All experimental work should be done on
299 branches to help promote this.
300
301
302 -----
303 Copyright 2001, 2003-2011 Free Software Foundation, Inc.
304
305 This program is free software: you can redistribute it and/or modify
306 it under the terms of the GNU General Public License as published by
307 the Free Software Foundation; either version 3 of the License, or
308 (at your option) any later version.
309
310 This program is distributed in the hope that it will be useful,
311 but WITHOUT ANY WARRANTY; without even the implied warranty of
312 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
313 GNU General Public License for more details.
314
315 You should have received a copy of the GNU General Public License
316 along with this program.  If not, see <http://www.gnu.org/licenses/>.