1 @node Library vs. Reusable Code
2 @section Library vs. Reusable Code
4 Classical libraries are installed as binary object code. Gnulib is
5 different: It is used as a source code library. Each package that uses
6 Gnulib thus ships with part of the Gnulib source code. The used portion
7 of Gnulib is tailored to the package: A build tool, called
8 @code{gnulib-tool}, is provided that copies a tailored subset of Gnulib
11 @node Portability and Application Code
12 @section Portability and Application Code
14 One of the goals of Gnulib is to make portable programming easy, on
15 the basis of the standards relevant for GNU (and Unix). The objective
16 behind that is to avoid a fragmentation of the user community into
17 disjoint user communities according to the operating system, and
18 instead allow synergies between users on different operating systems.
20 Another goal of Gnulib is to provide application code that can be shared
21 between several applications. Some people wonder: "What? glibc doesn't
22 have a function to copy a file?" Indeed, the scope of a system's libc is
23 to implement the relevant standards (ISO C99, POSIX:2001) and to provide
24 access functions to the kernel's system calls, and little more.
26 There is no clear borderline between both areas.
28 For example, Gnulib has a facility for generating the name of backup
29 files. While this task is entirely at the application level --- no
30 standard specifies an API for it --- the na@"{@dotless{i}}ve code has
31 some portability problems because on some platforms the length of file
32 name components is limited to 30 characters or so. Gnulib handles
35 Similarly, Gnulib has a facility for executing a command in a
36 subprocess. It is at the same time a portability enhancement (it
37 works on GNU, Unix, and Windows, compared to the classical
38 @code{fork()}/@code{exec()} which is not portable to Windows), as well
39 as an application aid: it takes care of redirecting stdin and/or
40 stdout if desired, and emits an error message if the subprocess
46 Gnulib is divided into modules. Every module implements a single
47 facility. Modules can depend on other modules.
49 A module consists of a number of files and a module description. The
50 files are copied by @code{gnulib-tool} into the package that will use it,
51 usually verbatim, without changes. Source code files (.h, .c files)
52 reside in the @file{lib/} subdirectory. Autoconf macro files reside in
53 the @file{m4/} subdirectory. Build scripts reside in the
54 @file{build-aux/} subdirectory.
56 The module description contains the list of files --- @code{gnulib-tool}
57 copies these files. It contains the module's
58 dependencies --- @code{gnulib-tool} installs them as well. It also
59 contains the autoconf macro invocation (usually a single line or
60 nothing at all) --- @code{gnulib-tool} ensures this is invoked from the
61 package's @file{configure.ac} file. And also a @file{Makefile.am}
62 snippet --- @code{gnulib-tool} collects these into a @file{Makefile.am}
63 for the tailored Gnulib part. The module description and include file
64 specification are for documentation purposes; they are combined into
67 The module system serves two purposes:
71 It ensures consistency of the used autoconf macros and @file{Makefile.am}
72 rules with the source code. For example, source code which uses the
73 @code{getopt_long} function --- this is a common way to implement parsing
74 of command line options in a way that complies with the GNU standards ---
75 needs the source code (@file{lib/getopt.c} and others), the autoconf macro
76 which detects whether the system's libc already has this function (in
77 @file{m4/getopt.m4}), and a few @file{Makefile.am} lines that create the
78 substitute @file{getopt.h} if not. These three pieces belong together.
79 They cannot be used without each other. The module description and
80 @code{gnulib-tool} ensure that they are copied altogether into the
84 It allows for scalability. It is well-known since the inception of the
85 MODULA-2 language around 1978 that dissection into modules with
86 dependencies allows for building large sets of code in a maintainable way.
87 The maintainability comes from the facts that:
91 Every module has a single purpose; you don't worry about other parts of
92 the program while creating, reading or modifying the code of a module.
95 The code you have to read in order to understand a module is limited to
96 the source of the module and the .h files of the modules listed as
97 dependencies. It is for this reason also that we recommend to put the
98 comments describing the functions exported by a module into its .h file.
101 In other words, the module is the elementary unit of code in Gnulib,
102 comparable to a class in object-oriented languages like Java or C#.
105 The module system is the basis of @code{gnulib-tool}. When
106 @code{gnulib-tool} copies a part of Gnulib into a package, it first
107 compiles a module list, starting with the requested modules and adding all
108 the dependencies, and then collects the files, @file{configure.ac}
109 snippets and @file{Makefile.am} snippets.
111 @node Various Kinds of Modules
112 @section Various Kinds of Modules
114 There are modules of various kinds in Gnulib. For a complete list of the
115 modules, see in @file{MODULES.html}.
117 @subsection Support for ISO C or POSIX functions.
119 When a function is not implemented by a system, the Gnulib module provides
120 an implementation under the same name. Examples are the @samp{snprintf}
121 and @samp{readlink} modules.
123 Similarly, when a function is not correctly implemented by a system,
124 Gnulib provides a replacement. For functions, we use the pattern
127 #if !HAVE_WORKING_FOO
133 and implement the @code{foo} function under the name @code{rpl_foo}. This
134 renaming is needed to avoid conflicts at compile time (in case the system
135 header files declare @code{foo}) and at link/run time (because the code
136 making use of @code{foo} could end up residing in a shared library, and
137 the executable program using this library could be defining @code{foo}
140 For header files, such as @code{stdbool.h} or @code{stdint.h}, we provide
141 the substitute only if the system doesn't provide a correct one. The
142 template of this replacement is distributed in a slightly different name,
143 with an added underscore, so that on systems which do provide a correct
144 header file the system's one is used.
146 @subsection Enhancements of ISO C or POSIX functions
148 These are sometimes POSIX functions with GNU extensions also found in
149 glibc --- examples: @samp{getopt}, @samp{fnmatch} --- and often new
150 APIs --- for example, for all functions that allocate memory in one way
151 or the other, we have variants which also include the error checking
152 against the out-of-memory condition.
154 @subsection Portable general use facilities
156 Examples are a module for copying a file --- the portability problems
157 relate to the copying of the file's modification time, access rights,
158 and extended attributes --- or a module for extracting the tail
159 component of a file name --- here the portability to Woe32 requires a
160 different API than the classical POSIX @code{basename} function.
162 @subsection Reusable application code
164 Examples are an error reporting function, a module that allows output of
165 numbers with K/M/G suffixes, or cryptographic facilities.
167 @subsection Object oriented classes
169 Examples are data structures like @samp{list}, or abstract output stream
170 classes that work around the fact that an application cannot implement an
171 stdio @code{FILE} with its logic. Here, while staying in C, we use
172 implementation techniques like tables of function pointers, known from the
173 C++ language or from the Linux kernel.
175 @subsection Interfaces to external libraries
177 Examples are the @samp{iconv} module, which interfaces to the
178 @code{iconv()} facility, regardless whether it is contained in libc or in
179 an external @code{libiconv}. Or the @samp{readline} module, which
180 interfaces to the GNU readline library.
182 @subsection Build / maintenance infrastructure
184 An example is the @samp{maintainer-makefile} module, which provides extra
185 Makefile tags for maintaining a package.
187 @node Collaborative Development
188 @section Collaborative Development
190 Gnulib is maintained collaboratively. The mailing list is
191 @code{<bug-gnulib at gnu dot org>}. Be warned that some people on the
192 list may be very active at some times and unresponsive at other times.
194 Every module has one or more maintainers. While issues are discussed
195 collaboratively on the list, the maintainer of a module nevertheless has
196 a veto right regarding changes in his module.
198 All patches should be posted the list, regardless whether they are
199 proposed patches or whether they are committed immediately by the
200 maintainer of the particular module. The purpose is not only to inform
201 the other users of the module, but mainly to allow peer review. It is not
202 uncommon that several people contribute comments or spot bugs after a
205 Conversely, if you are using Gnulib, and a patch is posted that affects
206 one of the modules that your package uses, you have an interest in
207 proofreading the patch.
212 Most modules are under the GPL. Some, mostly modules which can
213 reasonably be used in libraries, are under LGPL. The source files
214 always say "GPL", but the real license specification is in the module
217 More precisely, the license specification is in the module description
218 file applies to the files in @file{lib/} and @file{build-aux/}. Different
219 licenses apply to files in special directories:
223 Module description files are under this copyright:
226 Copyright @copyright{} 2002-2007 Free Software Foundation, Inc.@*
227 Copying and distribution of this file, with or without modification,
228 in any medium, are permitted without royalty provided the copyright
229 notice and this notice are preserved.
233 Autoconf macro files are under this copyright:
236 Copyright @copyright{} 2002-2007 Free Software Foundation, Inc.@*
237 This file is free software; the Free Software Foundation
238 gives unlimited permission to copy and/or distribute it,
239 with or without modifications, as long as this notice is preserved.
243 If a license statement is not present in a test module, the test files are
244 under GPL. Even if the corresponding source module is under LGPL, this is
245 not a problem, since compiled tests are not installed by ``make install''.
248 Documentation files are under this copyright:
251 Copyright @copyright{} 2002-2007 Free Software Foundation, Inc.@*
252 Permission is granted to copy, distribute and/or modify this document
253 under the terms of the GNU Free Documentation License, Version 1.1 or
254 any later version published by the Free Software Foundation; with no
255 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
260 If you want to use some Gnulib modules under LGPL, you can do so by
261 passing the option @samp{--lgpl} to @code{gnulib-tool}. This will
262 replace the GPL header with an LGPL header while copying the source
263 files to your package.
265 Keep in mind that when you submit patches to files in Gnulib, you should
266 license them under a compatible license. This means that sometimes the
267 contribution will have to be LGPL, if the original file is available
268 under LGPL. You can find out about it by looking for a "License: LGPL"
269 information in the corresponding module description.
271 @node Steady Development
272 @section Steady Development
274 Gnulib modules are continually adapted, to match new practices, to be
275 consistent with newly added modules, or simply as a response to build
276 failure reports. We don't make releases, but instead recommend to use the
277 newest version of Gnulib from the CVS, except in periods of major changes.
282 Gnulib is open in the sense that we gladly accept contributions if they
283 are generally useful, well engineered, and if the contributors have signed
284 the obligatory papers with the FSF.
286 The module system is open in the sense that a package using Gnulib can
289 locally patch or override files in Gnulib,
291 locally add modules that are treated like Gnulib modules by
295 This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}.