2 @section Benefits of using Gnulib
4 Gnulib is useful to enhance various aspects of a package:
8 Portability: With Gnulib, a package maintainer can program against the
9 POSIX and GNU libc APIs and nevertheless expect good portability to
10 platforms that don't implement POSIX.
13 Maintainability: When a package uses modules from Gnulib instead of code
14 written specifically for that package, the maintainer has less code to
18 Security: Gnulib provides functions that are immune against vulnerabilities
19 that plague the uses of the corresponding commonplace functions. For
20 example, @code{asprintf}, @code{canonicalize_file_name} are not affected
21 by buffer sizing problems that affect @code{sprintf}, @code{realpath}.
22 @code{openat} does not have the race conditions that @code{open} has. Etc.
25 Reliability: Gnulib provides functions that combine a call to a system
26 function with a check of the result. Examples are @code{xalloc},
27 @code{xprintf}, @code{xstrtod}, @code{xgetcwd}.
30 Structure: Gnulib offers a way to structure code into modules, typically
31 one include file, one source code file, and one autoconf macro for each
32 functionality. Modularity helps maintainability.
35 @node Library vs Reusable Code
36 @section Library vs. Reusable Code
38 Classical libraries are installed as binary object code. Gnulib is
39 different: It is used as a source code library. Each package that uses
40 Gnulib thus ships with part of the Gnulib source code. The used portion
41 of Gnulib is tailored to the package: A build tool, called
42 @code{gnulib-tool}, is provided that copies a tailored subset of Gnulib
45 @node Portability and Application Code
46 @section Portability and Application Code
48 One of the goals of Gnulib is to make portable programming easy, on
49 the basis of the standards relevant for GNU (and Unix). The objective
50 behind that is to avoid a fragmentation of the user community into
51 disjoint user communities according to the operating system, and
52 instead allow synergies between users on different operating systems.
54 Another goal of Gnulib is to provide application code that can be shared
55 between several applications. Some people wonder: "What? glibc doesn't
56 have a function to copy a file?" Indeed, the scope of a system's libc is
57 to implement the relevant standards (ISO C, POSIX) and to provide
58 access functions to the kernel's system calls, and little more.
60 There is no clear borderline between both areas.
62 For example, Gnulib has a facility for generating the name of backup
63 files. While this task is entirely at the application level---no
64 standard specifies an API for it---the na@"{@dotless{i}}ve code has
65 some portability problems because on some platforms the length of file
66 name components is limited to 30 characters or so. Gnulib handles
69 Similarly, Gnulib has a facility for executing a command in a
70 subprocess. It is at the same time a portability enhancement (it
71 works on GNU, Unix, and Windows, compared to the classical
72 @code{fork}/@code{exec} idiom which is not portable to Windows), as well
73 as an application aid: it takes care of redirecting stdin and/or
74 stdout if desired, and emits an error message if the subprocess
77 @node Target Platforms
78 @section Target Platforms
80 Gnulib supports a number of platforms that we call the ``reasonable
81 portability targets''. This class consists of widespread operating systems,
82 for three years after their last availability, or---for proprietary
83 operating systems---as long as the vendor provides commercial support for
84 it. Already existing Gnulib code for older operating systems is usually
85 left in place for longer than these three years. So it comes that programs
86 that use Gnulib run pretty well also on these older operating systems.
88 Some operating systems are not very widespread, but are Free Software and
89 are actively developed. Such platforms are also supported by Gnulib, if
90 that OS's developers community keeps in touch with the Gnulib developers,
91 by providing bug reports, analyses, or patches. For such platforms, Gnulib
92 supports only the versions of the last year or the last few months,
93 depending on the maturity of said OS project, the number of its users, and
94 how often these users upgrade.
96 Niche operating systems are generally unsupported by Gnulib, unless some
97 of their developers or users contribute support to Gnulib.
99 The degree of support Gnulib guarantees for a platform depends on the
100 amount of testing it gets from volunteers. Platforms on which Gnulib
101 is frequently tested are the best supported. Then come platforms with
102 occasional testing, then platforms which are rarely tested. Usually,
103 we fix bugs when they are reported. Except that some rarely tested
104 platforms are also low priority; bug fixes for these platforms can
107 As of 2018, the list of supported platforms is the following:
111 glibc systems. With glibc 2.19 or newer, they are frequently tested.
112 @c [Not very relevant in the long term.]
113 @c The distributions Ubuntu, Fedora, RHEL, Arch Linux are frequently tested.
114 @c CentOS is occasionally tested.
115 @c Debian, gNewSense, Trisquel, OpenSUSE are rarely tested.
119 glibc on Linux is frequently tested.
121 glibc on kFreeBSD is rarely tested.
124 Mac OS X. In versions 10.13, it's occasionally tested. In version
125 10.5, it's rarely tested.
127 FreeBSD 11.0 or newer is occasionally tested.
129 OpenBSD 6.1 or newer is occasionally tested.
131 NetBSD 7.0 or newer is occasionally tested.
133 AIX 7.1 is occasionally tested.
135 Solaris 10 and 11 are occasionally tested. Solaris 9 and older are rarely
136 tested and low priority.
138 Cygwin 2.9 is occasionally tested. Cygwin 1.7.x is rarely tested.
140 mingw is occasionally tested. But note that some modules are currently
141 unsupported on mingw: @code{mgetgroups}, @code{getugroups}, @code{idcache},
142 @code{userspec}, @code{openpty}, @code{login_tty}, @code{forkpty},
143 @code{pt_chown}, @code{grantpt}, @code{pty}, @code{savewd},
144 @code{mkancesdirs}, @code{mkdir-p}, @code{euidaccess}, @code{faccessat}.
145 The versions of Windows that are supported are Windows XP and newer.
146 Only the latest version of mingw is tested; older versions are not supported.
148 GNU Hurd 0.7 is rarely tested.
150 Native Windows, with MSVC as compiler, is rarely tested and low priority.
151 The versions of MSVC that are supported are MSVC 14 (Visual Studio 2015) or
154 @c There is musl-gcc on Ubuntu, and Alpine Linux 3.3.3.
155 musl libc is rarely tested.
157 Minix 3.3.0 is rarely tested.
159 HP-UX 11.31 is very rarely tested.
161 @c IRIX 6.5 cc has no option for C99 support. You would need to use gcc instead.
162 IRIX 6.5 is very rarely tested.
164 OSF/1 5.1 is no longer tested.
166 Interix 6.1 is no longer tested, and requires the @code{suacomp} library
167 (@url{https://sourceforge.net/projects/suacomp/}) in version 0.6.8 or newer.
169 Haiku and BeOS are no longer tested.
171 uClibc on Linux is no longer tested.
173 QNX is no longer tested.
176 Gnulib supports these operating systems only in an unvirtualized environment.
177 When you run an OS inside a virtual machine, you have to be aware that the
178 virtual machine can bring in bugs of its own. For example, floating-point
179 operations on Solaris can behave slightly differently in QEMU than on real
180 hardware. And Haiku's @command{bash} program misbehaves in VirtualBox 3,
181 whereas it behaves fine in VirtualBox 4.
183 Similarly, running native Windows binaries on GNU/Linux under WINE is
184 rarely tested and low priority: WINE has a set of behaviours and bugs that
185 is slightly different from native Windows.
187 The following platforms are not supported by Gnulib. The cost of
188 supporting them would exceed the benefit because they are rarely used, or
189 poorly documented, or have been supplanted by other platforms, or diverge
190 too much from POSIX, or some combination of these and other factors.
191 Please don't bother sending us patches for them.
197 DJGPP and EMX (the 32-bit operating systems running in DOS).
199 MSDOS (the 16-bit operating system).
201 Windows Mobile, Symbian OS, iOS.
207 Gnulib is divided into modules. Every module implements a single
208 facility. Modules can depend on other modules.
210 A module consists of a number of files and a module description. The
211 files are copied by @code{gnulib-tool} into the package that will use it,
212 usually verbatim, without changes. Source code files (.h, .c files)
213 reside in the @file{lib/} subdirectory. Autoconf macro files reside in
214 the @file{m4/} subdirectory. Build scripts reside in the
215 @file{build-aux/} subdirectory.
217 The module description contains the list of files; @code{gnulib-tool}
218 copies these files. It contains the module's
219 dependencies; @code{gnulib-tool} installs them as well. It also
220 contains the autoconf macro invocation (usually a single line or
221 nothing at all); @code{gnulib-tool} ensures this is invoked from the
222 package's @file{configure.ac} file. And also a @file{Makefile.am}
223 snippet; @code{gnulib-tool} collects these into a @file{Makefile.am}
224 for the tailored Gnulib part. The module description and include file
225 specification are for documentation purposes; they are combined into
228 The module system serves two purposes:
232 It ensures consistency of the used autoconf macros and @file{Makefile.am}
233 rules with the source code. For example, source code which uses the
234 @code{getopt_long} function---this is a common way to implement parsing
235 of command line options in a way that complies with the GNU standards---needs
236 the source code (@file{lib/getopt.c} and others), the autoconf macro
237 which detects whether the system's libc already has this function (in
238 @file{m4/getopt.m4}), and a few @file{Makefile.am} lines that create the
239 substitute @file{getopt.h} if not. These three pieces belong together.
240 They cannot be used without each other. The module description and
241 @code{gnulib-tool} ensure that they are copied altogether into the
245 It allows for scalability. It is well-known since the inception of the
246 MODULA-2 language around 1978 that dissection into modules with
247 dependencies allows for building large sets of code in a maintainable way.
248 The maintainability comes from the facts that:
252 Every module has a single purpose; you don't worry about other parts of
253 the program while creating, reading or modifying the code of a module.
256 The code you have to read in order to understand a module is limited to
257 the source of the module and the .h files of the modules listed as
258 dependencies. It is for this reason also that we recommend to put the
259 comments describing the functions exported by a module into its .h file.
262 In other words, the module is the elementary unit of code in Gnulib,
263 comparable to a class in object-oriented languages like Java or C#.
266 The module system is the basis of @code{gnulib-tool}. When
267 @code{gnulib-tool} copies a part of Gnulib into a package, it first
268 compiles a module list, starting with the requested modules and adding all
269 the dependencies, and then collects the files, @file{configure.ac}
270 snippets and @file{Makefile.am} snippets.
272 @node Various Kinds of Modules
273 @section Various Kinds of Modules
275 There are modules of various kinds in Gnulib. For a complete list of the
276 modules, see in @file{MODULES.html}.
278 @subsection Support for ISO C or POSIX functions.
280 When a function is not implemented by a system, the Gnulib module provides
281 an implementation under the same name. Examples are the @samp{snprintf}
282 and @samp{readlink} modules.
284 Similarly, when a function is not correctly implemented by a system,
285 Gnulib provides a replacement. For functions, we use the pattern
288 #if !HAVE_WORKING_FOO
294 and implement the @code{foo} function under the name @code{rpl_foo}. This
295 renaming is needed to avoid conflicts at compile time (in case the system
296 header files declare @code{foo}) and at link/run time (because the code
297 making use of @code{foo} could end up residing in a shared library, and
298 the executable program using this library could be defining @code{foo}
301 For header files, such as @code{stdbool.h} or @code{stdint.h}, we provide
302 the substitute only if the system doesn't provide a correct one. The
303 template of this replacement is distributed in a slightly different name,
304 with @samp{.in} inserted before the @samp{.h} extension, so that on
305 systems which do provide a correct
306 header file the system's one is used.
308 @subsection Enhancements of ISO C or POSIX functions
310 These are sometimes POSIX functions with GNU extensions also found in
311 glibc---examples: @samp{getopt}, @samp{fnmatch}---and often new
312 APIs---for example, for all functions that allocate memory in one way
313 or the other, we have variants which also include the error checking
314 against the out-of-memory condition.
316 @subsection Portable general use facilities
318 Examples are a module for copying a file---the portability problems
319 relate to the copying of the file's modification time, access rights,
320 and extended attributes---or a module for extracting the tail
321 component of a file name---here the portability to native Windows
322 requires a different API than the classical POSIX @code{basename} function.
324 @subsection Reusable application code
326 Examples are an error reporting function, a module that allows output of
327 numbers with K/M/G suffixes, or cryptographic facilities.
329 @subsection Object oriented classes
331 Examples are data structures like @samp{list}, or abstract output stream
332 classes that work around the fact that an application cannot implement an
333 stdio @code{FILE} with its logic. Here, while staying in C, we use
334 implementation techniques like tables of function pointers, known from the
335 C++ language or from the Linux kernel.
337 @subsection Interfaces to external libraries
339 Examples are the @samp{iconv} module, which interfaces to the
340 @code{iconv} facility, regardless whether it is contained in libc or in
341 an external @code{libiconv}. Or the @samp{readline} module, which
342 interfaces to the GNU readline library.
344 @subsection Build / maintenance infrastructure
346 An example is the @samp{maintainer-makefile} module, which provides extra
347 Makefile tags for maintaining a package.
349 @node Collaborative Development
350 @section Collaborative Development
352 Gnulib is maintained collaboratively. The mailing list is
353 @code{<bug-gnulib at gnu dot org>}. Be warned that some people on the
354 list may be very active at some times and unresponsive at other times.
356 Every module has one or more maintainers. While issues are discussed
357 collaboratively on the list, the maintainer of a module nevertheless has
358 a veto right regarding changes in his module.
360 All patches should be posted the list, regardless whether they are
361 proposed patches or whether they are committed immediately by the
362 maintainer of the particular module. The purpose is not only to inform
363 the other users of the module, but mainly to allow peer review. It is not
364 uncommon that several people contribute comments or spot bugs after a
367 Conversely, if you are using Gnulib, and a patch is posted that affects
368 one of the modules that your package uses, you have an interest in
369 proofreading the patch.
374 Most modules are under the GPL. Some, mostly modules which can
375 reasonably be used in libraries, are under LGPL. The source files
376 always say "GPL", but the real license specification is in the module
377 description file. If the module description file says "GPL", it means
378 "GPLv3+" (GPLv3 or newer, at the licensee's choice); if it says "LGPL",
379 it means "LGPLv3+" (LGPLv3 or newer, at the licensee's choice).
381 More precisely, the license specification in the module description
382 file applies to the files in @file{lib/} and @file{build-aux/}. Different
383 licenses apply to files in special directories:
387 Module description files are under this copyright:
390 Copyright @copyright{} 20XX--20YY Free Software Foundation, Inc.@*
391 Copying and distribution of this file, with or without modification,
392 in any medium, are permitted without royalty provided the copyright
393 notice and this notice are preserved.
397 Autoconf macro files are under this copyright:
400 Copyright @copyright{} 20XX--20YY Free Software Foundation, Inc.@*
401 This file is free software; the Free Software Foundation
402 gives unlimited permission to copy and/or distribute it,
403 with or without modifications, as long as this notice is preserved.
407 If a license statement is not present in a test module, the test files are
408 under GPL. Even if the corresponding source module is under LGPL, this is
409 not a problem, since compiled tests are not installed by ``make install''.
412 Documentation files are under this copyright:
415 Copyright @copyright{} 2004--20YY Free Software Foundation, Inc.@*
416 Permission is granted to copy, distribute and/or modify this document
417 under the terms of the GNU Free Documentation License, Version 1.3 or
418 any later version published by the Free Software Foundation; with no
419 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
420 copy of the license is included in the section entitled ``GNU Free
421 Documentation License''.
425 If you want to use some Gnulib modules under LGPL, you can do so by
426 passing the option @samp{--lgpl} to @code{gnulib-tool}. This will
427 replace the GPL header with an LGPL header while copying the source
428 files to your package. Similarly, if you want some Gnulib modules
429 under LGPLv2+ (Lesser GPL version 2.1 or newer), you can do so by
430 passing the option @samp{--lgpl=2} to @code{gnulib-tool}.
432 Keep in mind that when you submit patches to files in Gnulib, you should
433 license them under a compatible license. This means that sometimes the
434 contribution will have to be LGPL, if the original file is available
435 under LGPL. You can find out about it by looking for a "License: LGPL"
436 information in the corresponding module description.
438 @node Steady Development
439 @section Steady Development
441 Gnulib modules are continually adapted, to match new practices, to be
442 consistent with newly added modules, or simply as a response to build
443 failure reports. Gnulib is available in two qualities:
447 There is the newest version of Gnulib from the Git repository.
450 We also make stable releases every two months, at
451 @url{https://erislabs.net/ianb/projects/gnulib/}.
454 If you are willing to report an occasional regression, we recommend to
455 use the newest version always, except in periods of major changes. Most
456 Gnulib users do this. If you prefer stable releases, please use the
457 newest stable release.
462 Gnulib is open in the sense that we gladly accept contributions if they
463 are generally useful, well engineered, and if the contributors have signed
464 the obligatory papers with the FSF.
466 The module system is open in the sense that a package using Gnulib can
469 locally patch or override files in Gnulib,
471 locally add modules that are treated like Gnulib modules by
475 This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}
476 (@pxref{Extending Gnulib}).