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 C99, POSIX:2001) 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
80 Gnulib is divided into modules. Every module implements a single
81 facility. Modules can depend on other modules.
83 A module consists of a number of files and a module description. The
84 files are copied by @code{gnulib-tool} into the package that will use it,
85 usually verbatim, without changes. Source code files (.h, .c files)
86 reside in the @file{lib/} subdirectory. Autoconf macro files reside in
87 the @file{m4/} subdirectory. Build scripts reside in the
88 @file{build-aux/} subdirectory.
90 The module description contains the list of files --- @code{gnulib-tool}
91 copies these files. It contains the module's
92 dependencies --- @code{gnulib-tool} installs them as well. It also
93 contains the autoconf macro invocation (usually a single line or
94 nothing at all) --- @code{gnulib-tool} ensures this is invoked from the
95 package's @file{configure.ac} file. And also a @file{Makefile.am}
96 snippet --- @code{gnulib-tool} collects these into a @file{Makefile.am}
97 for the tailored Gnulib part. The module description and include file
98 specification are for documentation purposes; they are combined into
101 The module system serves two purposes:
105 It ensures consistency of the used autoconf macros and @file{Makefile.am}
106 rules with the source code. For example, source code which uses the
107 @code{getopt_long} function --- this is a common way to implement parsing
108 of command line options in a way that complies with the GNU standards ---
109 needs the source code (@file{lib/getopt.c} and others), the autoconf macro
110 which detects whether the system's libc already has this function (in
111 @file{m4/getopt.m4}), and a few @file{Makefile.am} lines that create the
112 substitute @file{getopt.h} if not. These three pieces belong together.
113 They cannot be used without each other. The module description and
114 @code{gnulib-tool} ensure that they are copied altogether into the
118 It allows for scalability. It is well-known since the inception of the
119 MODULA-2 language around 1978 that dissection into modules with
120 dependencies allows for building large sets of code in a maintainable way.
121 The maintainability comes from the facts that:
125 Every module has a single purpose; you don't worry about other parts of
126 the program while creating, reading or modifying the code of a module.
129 The code you have to read in order to understand a module is limited to
130 the source of the module and the .h files of the modules listed as
131 dependencies. It is for this reason also that we recommend to put the
132 comments describing the functions exported by a module into its .h file.
135 In other words, the module is the elementary unit of code in Gnulib,
136 comparable to a class in object-oriented languages like Java or C#.
139 The module system is the basis of @code{gnulib-tool}. When
140 @code{gnulib-tool} copies a part of Gnulib into a package, it first
141 compiles a module list, starting with the requested modules and adding all
142 the dependencies, and then collects the files, @file{configure.ac}
143 snippets and @file{Makefile.am} snippets.
145 @node Various Kinds of Modules
146 @section Various Kinds of Modules
148 There are modules of various kinds in Gnulib. For a complete list of the
149 modules, see in @file{MODULES.html}.
151 @subsection Support for ISO C or POSIX functions.
153 When a function is not implemented by a system, the Gnulib module provides
154 an implementation under the same name. Examples are the @samp{snprintf}
155 and @samp{readlink} modules.
157 Similarly, when a function is not correctly implemented by a system,
158 Gnulib provides a replacement. For functions, we use the pattern
161 #if !HAVE_WORKING_FOO
167 and implement the @code{foo} function under the name @code{rpl_foo}. This
168 renaming is needed to avoid conflicts at compile time (in case the system
169 header files declare @code{foo}) and at link/run time (because the code
170 making use of @code{foo} could end up residing in a shared library, and
171 the executable program using this library could be defining @code{foo}
174 For header files, such as @code{stdbool.h} or @code{stdint.h}, we provide
175 the substitute only if the system doesn't provide a correct one. The
176 template of this replacement is distributed in a slightly different name,
177 with @samp{.in} inserted before the @samp{.h} extension, so that on
178 systems which do provide a correct
179 header file the system's one is used.
181 @subsection Enhancements of ISO C or POSIX functions
183 These are sometimes POSIX functions with GNU extensions also found in
184 glibc --- examples: @samp{getopt}, @samp{fnmatch} --- and often new
185 APIs --- for example, for all functions that allocate memory in one way
186 or the other, we have variants which also include the error checking
187 against the out-of-memory condition.
189 @subsection Portable general use facilities
191 Examples are a module for copying a file --- the portability problems
192 relate to the copying of the file's modification time, access rights,
193 and extended attributes --- or a module for extracting the tail
194 component of a file name --- here the portability to Woe32 requires a
195 different API than the classical POSIX @code{basename} function.
197 @subsection Reusable application code
199 Examples are an error reporting function, a module that allows output of
200 numbers with K/M/G suffixes, or cryptographic facilities.
202 @subsection Object oriented classes
204 Examples are data structures like @samp{list}, or abstract output stream
205 classes that work around the fact that an application cannot implement an
206 stdio @code{FILE} with its logic. Here, while staying in C, we use
207 implementation techniques like tables of function pointers, known from the
208 C++ language or from the Linux kernel.
210 @subsection Interfaces to external libraries
212 Examples are the @samp{iconv} module, which interfaces to the
213 @code{iconv} facility, regardless whether it is contained in libc or in
214 an external @code{libiconv}. Or the @samp{readline} module, which
215 interfaces to the GNU readline library.
217 @subsection Build / maintenance infrastructure
219 An example is the @samp{maintainer-makefile} module, which provides extra
220 Makefile tags for maintaining a package.
222 @node Collaborative Development
223 @section Collaborative Development
225 Gnulib is maintained collaboratively. The mailing list is
226 @code{<bug-gnulib at gnu dot org>}. Be warned that some people on the
227 list may be very active at some times and unresponsive at other times.
229 Every module has one or more maintainers. While issues are discussed
230 collaboratively on the list, the maintainer of a module nevertheless has
231 a veto right regarding changes in his module.
233 All patches should be posted the list, regardless whether they are
234 proposed patches or whether they are committed immediately by the
235 maintainer of the particular module. The purpose is not only to inform
236 the other users of the module, but mainly to allow peer review. It is not
237 uncommon that several people contribute comments or spot bugs after a
240 Conversely, if you are using Gnulib, and a patch is posted that affects
241 one of the modules that your package uses, you have an interest in
242 proofreading the patch.
247 Most modules are under the GPL. Some, mostly modules which can
248 reasonably be used in libraries, are under LGPL. The source files
249 always say "GPL", but the real license specification is in the module
250 description file. If the module description file says "GPL", it means
251 "GPLv3+" (GPLv3 or newer, at the licensee's choice); if it says "LGPL",
252 it means "LGPLv3+" (LGPLv3 or newer, at the licensee's choice).
254 More precisely, the license specification in the module description
255 file applies to the files in @file{lib/} and @file{build-aux/}. Different
256 licenses apply to files in special directories:
260 Module description files are under this copyright:
263 Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@*
264 Copying and distribution of this file, with or without modification,
265 in any medium, are permitted without royalty provided the copyright
266 notice and this notice are preserved.
270 Autoconf macro files are under this copyright:
273 Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@*
274 This file is free software; the Free Software Foundation
275 gives unlimited permission to copy and/or distribute it,
276 with or without modifications, as long as this notice is preserved.
280 If a license statement is not present in a test module, the test files are
281 under GPL. Even if the corresponding source module is under LGPL, this is
282 not a problem, since compiled tests are not installed by ``make install''.
285 Documentation files are under this copyright:
288 Copyright @copyright{} 2004-200Y Free Software Foundation, Inc.@*
289 Permission is granted to copy, distribute and/or modify this document
290 under the terms of the GNU Free Documentation License, Version 1.3 or
291 any later version published by the Free Software Foundation; with no
292 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
293 copy of the license is included in the section entitled ``GNU Free
294 Documentation License''.
298 If you want to use some Gnulib modules under LGPL, you can do so by
299 passing the option @samp{--lgpl} to @code{gnulib-tool}. This will
300 replace the GPL header with an LGPL header while copying the source
301 files to your package. Similarly, if you want some Gnulib modules
302 under LGPLv2+ (Lesser GPL version 2.1 or newer), you can do so by
303 passing the option @samp{--lgpl=2} to @code{gnulib-tool}.
305 Keep in mind that when you submit patches to files in Gnulib, you should
306 license them under a compatible license. This means that sometimes the
307 contribution will have to be LGPL, if the original file is available
308 under LGPL. You can find out about it by looking for a "License: LGPL"
309 information in the corresponding module description.
311 @node Steady Development
312 @section Steady Development
314 Gnulib modules are continually adapted, to match new practices, to be
315 consistent with newly added modules, or simply as a response to build
316 failure reports. Gnulib is available in two qualities:
320 There is the newest version of Gnulib from the Git repository. The
321 source tree can also be fetched from a read-only CVS that mirrors the Git
325 We also make stable releases every two months, at
326 @url{http://erislabs.net/ianb/projects/gnulib/}.
329 If you are willing to report an occasional regression, we recommend to
330 use the newest version always, except in periods of major changes. Most
331 Gnulib users do this. If you prefer stable releases, please use the
332 newest stable release.
337 Gnulib is open in the sense that we gladly accept contributions if they
338 are generally useful, well engineered, and if the contributors have signed
339 the obligatory papers with the FSF.
341 The module system is open in the sense that a package using Gnulib can
344 locally patch or override files in Gnulib,
346 locally add modules that are treated like Gnulib modules by
350 This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}
351 (@pxref{Extending Gnulib}).