3 @c Copyright 2001, 2003--2020 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 or
7 @c any later version published by the Free Software Foundation; with no
8 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
9 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
14 * Keeping Up-to-date::
15 * Contributing to Gnulib::
16 * Portability guidelines::
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{https://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{https://en.wikipedia.org/wiki/Git_(software)}
72 @url{https://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 @node Keeping Up-to-date
80 @section Keeping Up-to-date
82 The best way to work with Gnulib is to check it out of git.
83 To synchronize, you can use @code{git pull}.
85 Subscribing to the @email{bug-gnulib@@gnu.org} mailing list will help
86 you to plan when to update your local copy of Gnulib (which you use to
87 maintain your software) from git. You can review the archives,
89 @url{https://lists.gnu.org/mailman/listinfo/bug-gnulib}.
91 Sometimes, using an updated version of Gnulib will require you to use
92 newer versions of GNU Automake or Autoconf. You may find it helpful
93 to join the autotools-announce mailing list to be advised of such
96 @node Contributing to Gnulib
97 @section Contributing to Gnulib
99 All software here is copyrighted by the Free Software Foundation---you need
100 to have filled out an assignment form for a project that uses the
101 module for that contribution to be accepted here.
103 If you have a piece of code that you would like to contribute, please
104 email @email{bug-gnulib@@gnu.org}.
106 Generally we are looking for files that fulfill at least one of the
107 following requirements:
111 If your @file{.c} and @file{.h} files define functions that are broken or
112 missing on some other system, we should be able to include it.
115 If your functions remove arbitrary limits from existing
116 functions (either under the same name, or as a slightly different
117 name), we should be able to include it.
120 If your functions define completely new but rarely used functionality,
121 you should probably consider packaging it as a separate library.
125 * Indent with spaces not TABs::
126 * How to add a new module::
129 @node Gnulib licensing
130 @subsection Gnulib licensing
132 Gnulib contains code both under GPL and LGPL@. Because several packages
133 that use Gnulib are GPL, the files state they are licensed under GPL@.
134 However, to support LGPL projects as well, you may use some of the
135 files under LGPL@. The ``License:'' information in the files under
136 modules/ clarifies the real license that applies to the module source.
138 Keep in mind that if you submit patches to files in Gnulib, you should
139 license them under a compatible license, which means that sometimes
140 the contribution will have to be LGPL, if the original file is
141 available under LGPL via a ``License: LGPL'' information in the
142 projects' modules/ file.
144 @node Indent with spaces not TABs
145 @subsection Indent with spaces not TABs
147 We use space-only indentation in nearly all files. This includes all
148 @file{*.h}, @file{*.c}, @file{*.y} files, except for the @code{regex}
149 module. Makefile and ChangeLog files are excluded, since TAB
150 characters are part of their format.
152 In order to tell your editor to produce space-only indentation, you
153 can use these instructions.
157 For Emacs: Add these lines to your Emacs initialization file
158 (@file{$HOME/.emacs} or similar):
161 ;; In Gnulib, indent with spaces everywhere (not TABs).
162 ;; Exceptions: Makefile and ChangeLog modes.
163 (add-hook 'find-file-hook '(lambda ()
164 (if (and buffer-file-name
165 (string-match "/gnulib\\>" (buffer-file-name))
166 (not (string-equal mode-name "Change Log"))
167 (not (string-equal mode-name "Makefile")))
168 (setq indent-tabs-mode nil))))
172 For vi (vim): Add these lines to your @file{$HOME/.vimrc} file:
175 " Don't use tabs for indentation. Spaces are nicer to work with.
179 For Makefile and ChangeLog files, compensate for this by adding this
180 to your @file{$HOME/.vim/after/indent/make.vim} file, and similarly
181 for your @file{$HOME/.vim/after/indent/changelog.vim} file:
184 " Use tabs for indentation, regardless of the global setting.
189 For Eclipse: In the ``Window|Preferences'' dialog (or ``Eclipse|Preferences''
194 Under ``General|Editors|Text Editors'', select the ``Insert spaces for tabs''
198 Under ``C/C++|Code Style'', select a code style profile that has the
199 ``Indentation|Tab policy'' combobox set to ``Spaces only'', such as the
200 ``GNU [built-in]'' policy.
203 If you use the GNU indent program, pass it the option @option{--no-tabs}.
206 @node How to add a new module
207 @subsection How to add a new module
211 Add the header files and source files to @file{lib/}.
214 If the module needs configure-time checks, write an Autoconf
215 macro for it in @file{m4/@var{module}.m4}. See @file{m4/README} for details.
218 Write a module description @file{modules/@var{module}}, based on
219 @file{modules/TEMPLATE}.
222 If the module contributes a section to the end-user documentation,
223 put this documentation in @file{doc/@var{module}.texi} and add it to the ``Files''
224 section of @file{modules/@var{module}}. Most modules don't do this; they have only
225 documentation for the programmer (= Gnulib user). Such documentation
226 usually goes into the @file{lib/} source files. It may also go into @file{doc/};
227 but don't add it to the module description in this case.
230 Add the module to the list in @file{MODULES.html.sh}.
234 You can test that a module builds correctly with:
237 $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
239 $ ./configure && make
247 Check the license and copyright year of headers.
250 Check that the source code follows the GNU coding standards;
251 see @url{https://www.gnu.org/prep/standards}.
254 Add source files to @file{config/srclist*} if they are identical to upstream
255 and should be upgraded in Gnulib whenever the upstream source changes.
258 Include header files in source files to verify the function prototypes.
261 Make sure a replacement function doesn't cause warnings or clashes on
262 systems that have the function.
265 Autoconf functions can use @samp{gl_*} prefix. The @samp{AC_*} prefix is for
266 autoconf internal functions.
269 Build files only if they are needed on a platform. Look at the
270 @code{alloca} and @code{fnmatch} modules for how to achieve this. If
271 for some reason you cannot do this, and you have a @file{.c} file that
272 leads to an empty @file{.o} file on some platforms (through some big
273 @code{#if} around all the code), then ensure that the compilation unit
274 is not empty after preprocessing. One way to do this is to
275 @code{#include <stddef.h>} or @code{<stdio.h>} before the big
279 @node Portability guidelines
280 @section Portability guidelines
282 Gnulib code is intended to be portable to a wide variety of platforms,
283 not just GNU platforms. Gnulib typically attempts to support a
284 platform as long as it is still supported by its provider, even if the
285 platform is not the latest version. @xref{Target Platforms}.
287 Many Gnulib modules exist so that applications need not worry about
288 undesirable variability in implementations. For example, an
289 application that uses the @code{malloc} module need not worry about
290 @code{malloc@ (0)} returning @code{NULL} on some Standard C
291 platforms; and @code{glob} users need not worry about @code{glob}
292 silently omitting symbolic links to nonexistent files on some
293 platforms that do not conform to POSIX.
295 Gnulib code is intended to port without problem to new hosts, e.g.,
296 hosts conforming to recent C and POSIX standards. Hence Gnulib code
297 should avoid using constructs that these newer standards no longer
298 require, without first testing for the presence of these constructs.
299 For example, because C11 made variable length arrays optional, Gnulib
300 code should avoid them unless it first uses the @code{vararrays}
301 module to check whether they are supported.
303 The following subsections discuss some exceptions and caveats to the
304 general Gnulib portability guidelines.
307 * C language versions::
308 * C99 features assumed::
309 * C99 features avoided::
310 * Other portability assumptions::
313 @node C language versions
314 @subsection C language versions
316 Currently Gnulib assumes at least a freestanding C99 compiler,
317 possibly operating with a C library that predates C99; with time this
318 assumption will likely be strengthened to later versions of the C
319 standard. Old platforms currently supported include AIX 6.1, HP-UX
320 11i v1 and Solaris 10, though these platforms are rarely tested.
321 Gnulib itself is so old that it contains many fixes for obsolete
322 platforms, fixes that may be removed in the future.
324 Because of the freestanding C99 assumption, Gnulib code can include
325 @code{<float.h>}, @code{<limits.h>}, @code{<stdarg.h>},
326 @code{<stdbool.h>}, @code{<stddef.h>}, and @code{<stdint.h>}
327 unconditionally. Gnulib code can also assume the existence
328 of @code{<ctype.h>}, @code{<errno.h>}, @code{<fcntl.h>},
329 @code{<locale.h>}, @code{<signal.h>}, @code{<stdio.h>},
330 @code{<stdlib.h>}, @code{<string.h>}, and @code{<time.h>}. Similarly,
331 many modules include @code{<sys/types.h>} even though it's not even in
332 C11; that's OK since @code{<sys/types.h>} has been around nearly
335 Even if the include files exist, they may not conform to the C standard.
336 However, GCC has a @command{fixincludes} script that attempts to fix most
337 C89-conformance problems. Gnulib currently assumes include files
338 largely conform to C89 or better. People still using ancient hosts
339 should use fixincludes or fix their include files manually.
341 Even if the include files conform, the library itself may not.
342 For example, @code{strtod} and @code{mktime} have some bugs on some platforms.
343 You can work around some of these problems by requiring the relevant
344 modules, e.g., the Gnulib @code{mktime} module supplies a working and
345 conforming @code{mktime}.
347 @node C99 features assumed
348 @subsection C99 features assumed by Gnulib
350 Although the C99 standard specifies many features, Gnulib code
351 is conservative about using them, partly because Gnulib predates
352 the widespread adoption of C99, and partly because many C99
353 features are not well-supported in practice. C99 features that
354 are reasonably portable nowadays include:
358 A declarations after a statement, or as the first clause in a
359 @code{for} statement.
362 @code{long long int}.
365 @code{<stdbool.h>}, assuming the @code{stdbool} module is used.
369 @code{<stdint.h>}, assuming the @code{stdint} module is used.
373 Compound literals and designated initializers.
379 @code{static inline} functions.
382 @code{__func__}, assuming the @code{func} module is used. @xref{func}.
385 The @code{restrict} qualifier, assuming
386 @code{AC_REQUIRE([AC_C_RESTRICT])} is used.
389 Flexible array members (however, see the @code{flexmember} module).
392 @node C99 features avoided
393 @subsection C99 features avoided by Gnulib
395 Gnulib avoids some features even though they are standardized by C99,
396 as they have portability problems in practice. Here is a partial list
397 of avoided C99 features. Many other C99 features are portable only if
398 their corresponding modules are used; Gnulib code that uses such a
399 feature should require the corresponding module.
403 Variable length arrays, unless @code{__STDC_NO_VLA__} is defined.
404 See the @code{vararrays} module.
407 @code{extern inline} functions, without checking whether they are
408 supported. @xref{extern inline}.
411 Type-generic math functions.
414 Universal character names in source code.
417 @code{<iso646.h>}, since GNU programs need not worry about deficient
418 source-code encodings.
421 Comments beginning with @samp{//}. This is mostly for style reasons.
424 @node Other portability assumptions
425 @subsection Other portability assumptions made by Gnulib
427 The GNU coding standards allow one departure from strict C: Gnulib
428 code can assume that standard internal types like @code{size_t} are no
429 wider than @code{long}. POSIX requires implementations to support at
430 least one programming environment where this is true, and such
431 environments are recommended for Gnulib-using applications. When it
432 is easy to port to non-POSIX platforms like MinGW where these types
433 are wider than @code{long}, new Gnulib code should do so, e.g., by
434 using @code{ptrdiff_t} instead of @code{long}. However, it is not
435 always that easy, and no effort has been made to check that all Gnulib
436 modules work on MinGW-like environments.
438 Gnulib code makes the following additional assumptions:
442 @code{int} and @code{unsigned int} are at least 32 bits wide. POSIX
443 and the GNU coding standards both require this.
446 Signed integer arithmetic is two's complement.
448 Previously, Gnulib code sometimes assumed that signed integer
449 arithmetic wraps around, but modern compiler optimizations
450 sometimes do not guarantee this, and Gnulib code with this
451 assumption is now considered to be questionable.
452 @xref{Integer Properties}.
454 Although some Gnulib modules contain explicit support for the other signed
455 integer representations allowed by the C standard (ones' complement and signed
456 magnitude), these modules are the exception rather than the rule.
457 All practical Gnulib targets use two's complement.
460 There are no ``holes'' in integer values: all the bits of an integer
461 contribute to its value in the usual way.
464 Addresses and sizes behave as if objects reside in a flat address space.
469 If two nonoverlapping objects have sizes @var{S} and @var{T} represented as
470 @code{size_t} values, then @code{@var{S} + @var{T}} cannot overflow.
473 A pointer @var{P} points within an object @var{O} if and only if
474 @code{(char *) &@var{O} <= (char *) @var{P} && (char *) @var{P} <
475 (char *) (&@var{O} + 1)}.
478 If an existing object has size @var{S}, and if @var{T} is sufficiently
479 small (e.g., 8 KiB), then @code{@var{S} + @var{T}} cannot overflow.
480 Overflow in this case would mean that the rest of your program fits
481 into @var{T} bytes, which can't happen in realistic flat-address-space
485 Objects with all bits zero are treated as 0 or NULL@. For example,
486 @code{memset@ (A, 0, sizeof@ A)} initializes an array @code{A} of
490 Adding zero to a null pointer does not change the pointer.
491 For example, @code{0 + (char *) NULL == (char *) NULL}.
495 The above assumptions are not required by the C or POSIX standards but
496 hold on all practical porting targets that we're familiar with. If
497 you have a porting target where these assumptions are not true, we'd
498 appreciate hearing of any fixes. We need fixes that do not increase
499 runtime overhead on standard hosts and that are relatively easy to
503 @section High Quality
505 We develop and maintain a testsuite for Gnulib. The goal is to have a
506 100% firm interface so that maintainers can feel free to update to the
507 code in git at @emph{any} time and know that their application will not
508 break. This means that before any change can be committed to the
509 repository, a test suite program must be produced that exposes the bug
510 for regression testing. All experimental work should be done on
511 branches to help promote this.