3 @c Copyright 2001, 2003--2021 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 https://git.savannah.gnu.org/git/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{https://git.savannah.gnu.org/git/gnulib.git}, use the URL
63 @samp{ssh://@var{user}@@git.savannah.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.
387 This qualifier is sometimes implemented via a macro, so C++ code that
388 uses Gnulib should avoid using @code{restrict} as an identifier.
391 Flexible array members (however, see the @code{flexmember} module).
394 @node C99 features avoided
395 @subsection C99 features avoided by Gnulib
397 Gnulib avoids some features even though they are standardized by C99,
398 as they have portability problems in practice. Here is a partial list
399 of avoided C99 features. Many other C99 features are portable only if
400 their corresponding modules are used; Gnulib code that uses such a
401 feature should require the corresponding module.
405 Variable length arrays, unless @code{__STDC_NO_VLA__} is defined.
406 See the @code{vararrays} module.
409 @code{extern inline} functions, without checking whether they are
410 supported. @xref{extern inline}.
413 Type-generic math functions.
416 Universal character names in source code.
419 @code{<iso646.h>}, since GNU programs need not worry about deficient
420 source-code encodings.
423 Comments beginning with @samp{//}. This is mostly for style reasons.
426 @node Other portability assumptions
427 @subsection Other portability assumptions made by Gnulib
429 The GNU coding standards allow one departure from strict C: Gnulib
430 code can assume that standard internal types like
431 @code{ptrdiff_t} and @code{size_t} are no
432 wider than @code{long}. POSIX requires implementations to support at
433 least one programming environment where this is true, and such
434 environments are recommended for Gnulib-using applications. When it
435 is easy to port to non-POSIX platforms like MinGW where these types
436 are wider than @code{long}, new Gnulib code should do so, e.g., by
437 using @code{ptrdiff_t} instead of @code{long}. However, it is not
438 always that easy, and no effort has been made to check that all Gnulib
439 modules work on MinGW-like environments.
441 Gnulib code makes the following additional assumptions:
445 @code{int} and @code{unsigned int} are at least 32 bits wide. POSIX
446 and the GNU coding standards both require this.
449 Signed integer arithmetic is two's complement.
451 Previously, Gnulib code sometimes also assumed that signed integer
452 arithmetic wraps around, but modern compiler optimizations
453 sometimes do not guarantee this, and Gnulib code with this
454 assumption is now considered to be questionable.
455 @xref{Integer Properties}.
457 Although some Gnulib modules contain explicit support for the other signed
458 integer representations allowed by the C standard (ones' complement and signed
459 magnitude), these modules are the exception rather than the rule.
460 All practical Gnulib targets use two's complement.
463 There are no ``holes'' in integer values: all the bits of an integer
464 contribute to its value in the usual way.
465 In particular, an unsigned type and its signed counterpart have the
466 same number of bits when you count the latter's sign bit.
469 Objects with all bits zero are treated as 0 or NULL@. For example,
470 @code{memset@ (A, 0, sizeof@ A)} initializes an array @code{A} of
474 The types @code{intptr_t} and @code{uintptr_t} exist, and pointers
475 can be converted to and from these types without loss of information.
478 Addresses and sizes behave as if objects reside in a flat address space.
483 If two nonoverlapping objects have sizes @var{S} and @var{T} represented as
484 @code{ptrdiff_t} or @code{size_t} values, then @code{@var{S} + @var{T}}
488 A pointer @var{P} points within an object @var{O} if and only if
489 @code{(char *) &@var{O} <= (char *) @var{P} && (char *) @var{P} <
490 (char *) (&@var{O} + 1)}.
493 Arithmetic on a valid pointer is equivalent to the same arithmetic on
494 the pointer converted to @code{uintptr_t}, except that offsets are
495 multiplied by the size of the pointed-to objects.
496 For example, if @code{P + I} is a valid expression involving a pointer
497 @var{P} and an integer @var{I}, then @code{(uintptr_t) (P + I) ==
498 (uintptr_t) ((uintptr_t) P + I * sizeof *P)}.
499 Similar arithmetic can be done with @code{intptr_t}, although more
500 care must be taken in case of integer overflow or negative integers.
503 A pointer @code{P} has alignment @code{A} if and only if
504 @code{(uintptr_t) P % A} is zero, and similarly for @code{intptr_t}.
507 If an existing object has size @var{S}, and if @var{T} is sufficiently
508 small (e.g., 8 KiB), then @code{@var{S} + @var{T}} cannot overflow.
509 Overflow in this case would mean that the rest of your program fits
510 into @var{T} bytes, which can't happen in realistic flat-address-space
514 Adding zero to a null pointer does not change the pointer.
515 For example, @code{0 + (char *) NULL == (char *) NULL}.
519 Some system platforms violate these assumptions and are therefore not
520 Gnulib porting targets. @xref{Unsupported Platforms}.
523 @section High Quality
525 We develop and maintain a testsuite for Gnulib. The goal is to have a
526 100% firm interface so that maintainers can feel free to update to the
527 code in git at @emph{any} time and know that their application will not
528 break. This means that before any change can be committed to the
529 repository, a test suite program must be produced that exposes the bug
530 for regression testing. All experimental work should be done on
531 branches to help promote this.
533 When compiling and testing Gnulib and Gnulib-using programs, certain
534 compiler options can help improve reliability. The
535 @code{manywarnings} module enables several forms of static checking in
536 GCC and related compilers (@pxref{manywarnings}). For dynamic checking,
537 you can run @code{configure} with @code{CFLAGS} options appropriate
538 for your compiler. For example:
543 ' -D_FORTIFY_SOURCE=2'\
544 ' -fsanitize=undefined'\
545 ' -fsanitize-undefined-trap-on-error'
553 @code{-D_FORTIFY_SOURCE=2} enables extra security hardening checks in
556 @code{-fsanitize=undefined} enables GCC's undefined behavior sanitizer
559 @code{-fsanitize-undefined-trap-on-error} causes @code{ubsan} to
560 abort the program (through an ``illegal instruction'' signal). This
561 measure stops exploit attempts and also allows you to debug the issue.
564 Without the @code{-fsanitize-undefined-trap-on-error} option,
565 @code{-fsanitize=undefined} causes messages to be printed, and
566 execution continues after an undefined behavior situation.
567 The message printing causes GCC-like compilers to arrange for the
568 program to dynamically link to libraries it might not otherwise need.
569 With GCC, instead of @code{-fsanitize-undefined-trap-on-error} you can
570 use the @code{-static-libubsan} option to arrange for two of the extra
571 libraries (@code{libstdc++} and @code{libubsan}) to be linked
572 statically rather than dynamically, though this typically bloats the
573 executable and the remaining extra libraries are still linked