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 the
15 basis of the standards relevant for Unix. The objective behind that is to
16 avoid a fragmentation of the user community into disjoint user communities
17 according to the operating system, and instead allow synergies between
18 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 an applicative one -- no standard specifies an
30 API for it --, the na@"ive code has some portability problems because on
31 some platforms the length of file name components is limited to 30
32 characters or so. Gnulib handles that.
34 Similarly, Gnulib has a facility for executing a command in a subprocess.
35 It is at the same time a portability enhancement (it works on Unix and
36 Windows, compared to the classical @code{fork()}/@code{exec()} which is
37 not portable to Windows), as well as an application aid: it takes care of
38 redirecting stdin and/or stdout if desired, and emits an error message if
39 the subprocess failed.
44 Gnulib is divided into modules. Every module implements a single
45 facility. Modules can depend on other modules.
47 A module consists of a number of files and a module description. The
48 files are copied by @code{gnulib-tool} into the package that will use it,
49 usually verbatim, without changes. Source code files (.h, .c files)
50 reside in the @file{lib/} subdirectory. Autoconf macro files reside in
51 the @file{m4/} subdirectory. Build scripts reside in the
52 @file{build-aux/} subdirectory.
54 The module description contains the list of files -- @code{gnulib-tool}
55 copies these files. It contains the module's dependencies --
56 @code{gnulib-tool} installs them as well. It also contains the autoconf
57 macro invocation (usually a single line or nothing at all) --
58 @code{gnulib-tool} ensures this is invoked from the package's
59 @file{configure.ac} file. And also a @file{Makefile.am} snippet --
60 @code{gnulib-tool} collects these into a @file{Makefile.am} for the
61 tailored Gnulib part. The module description and include file
62 specification are for documentation purposes; they are combined into
65 The module system serves two purposes:
69 It ensures consistency of the used autoconf macros and @file{Makefile.am}
70 rules with the source code. For example, source code which uses the
71 @code{getopt_long} function -- this is a common way to implement parsing
72 of command line options in a way that complies with the GNU standards --
73 needs the source code (@file{lib/getopt.c} and others), the autoconf macro
74 which detects whether the system's libc already has this function (in
75 @file{m4/getopt.m4}), and a few @file{Makefile.am} lines that create the
76 substitute @file{getopt.h} if not. These three pieces belong together.
77 They cannot be used without each other. The module description and
78 @code{gnulib-tool} ensure that they are copied altogether into the
82 It allows for scalability. It is well-known since the inception of the
83 MODULA-2 language around 1978 that dissection into modules with
84 dependencies allows for building large sets of code in a maintainable way.
85 The maintainability comes from the facts that:
89 Every module has a single purpose; you don't worry about other parts of
90 the program while creating, reading or modifying the code of a module.
93 The code you have to read in order to understand a module is limited to
94 the source of the module and the .h files of the modules listed as
95 dependencies. It is for this reason also that we recommend to put the
96 comments describing the functions exported by a module into its .h file.
99 In other words, the module is the elementary unit of code in Gnulib,
100 comparable to a class in object-oriented languages like Java or C#.
103 The module system is the basis of @code{gnulib-tool}. When
104 @code{gnulib-tool} copies a part of Gnulib into a package, it first
105 compiles a module list, starting with the requested modules and adding all
106 the dependencies, and then collects the files, @file{configure.ac}
107 snippets and @file{Makefile.am} snippets.
109 @node Various Kinds of Modules
110 @section Various Kinds of Modules
112 There are modules of various kinds in Gnulib. For a complete list of the
113 modules, see in @file{MODULES.html}.
115 @subsection Support for ISO C or POSIX functions.
117 When a function is not implemented by a system, the Gnulib module provides
118 an implementation under the same name. Examples are the @samp{snprintf}
119 and @samp{readlink} modules.
121 Similarly, when a function is not correctly implemented by a system,
122 Gnulib provides a replacement. For functions, we use the pattern
125 #if !HAVE_WORKING_FOO
131 and implement the @code{foo} function under the name @code{rpl_foo}. This
132 renaming is needed to avoid conflicts at compile time (in case the system
133 header files declare @code{foo}) and at link/run time (because the code
134 making use of @code{foo} could end up residing in a shared library, and
135 the executable program using this library could be defining @code{foo}
138 For header files, such as @code{stdbool.h} or @code{stdint.h}, we provide
139 the substitute only if the system doesn't provide a correct one. The
140 template of this replacement is distributed in a slightly different name,
141 with an added underscore, so that on systems which do provide a correct
142 header file the system's one is used.
144 @subsection Enhancements of ISO C or POSIX functions
146 These are sometimes POSIX functions with GNU extensions also found in
147 glibc -- examples: @samp{getopt}, @samp{fnmatch} --, and often new APIs
148 -- for example, for all functions that allocate memory in one way or the
149 other, we have variants which also include the error checking against the
150 out-of-memory condition.
152 @subsection Portable general use facilities
154 Examples are a module for copying a file -- the portability problems
155 relate to the copying of the file's modification time, access rights, and
156 extended attributes -- or a module for extracting the tail component of a
157 file name -- here the portability to Woe32 requires a different API than
158 the classical POSIX @code{basename} function.
160 @subsection Reusable application code
162 Examples are an error reporting function, a module that allows output of
163 numbers with K/M/G suffixes, or cryptographic facilities.
165 @subsection Object oriented classes
167 Examples are data structures like @samp{list}, or abstract output stream
168 classes that work around the fact that an application cannot implement an
169 stdio @code{FILE} with its logic. Here, while staying in C, we use
170 implementation techniques like tables of function pointers, known from the
171 C++ language or from the Linux kernel.
173 @subsection Interfaces to external libraries
175 Examples are the @samp{iconv} module, which interfaces to the
176 @code{iconv()} facility, regardless whether it is contained in libc or in
177 an external @code{libiconv}. Or the @samp{readline} module, which
178 interfaces to the GNU readline library.
180 @subsection Build / maintenance infrastructure
182 An example is the @samp{maintainer-makefile} module, which provides extra
183 Makefile tags for maintaining a package.
185 @node Collaborative Development
186 @section Collaborative Development
188 Gnulib is maintained collaboratively. The mailing list is
189 @code{<bug-gnulib at gnu dot org>}. Be warned that some people on the
190 list may be very active at some times and unresponsive at other times.
192 Every module has one or more maintainers. While issues are discussed
193 collaboratively on the list, the maintainer of a module nevertheless has
194 a veto right regarding changes in his module.
196 All patches should be posted the list, regardless whether they are
197 proposed patches or whether they are committed immediately by the
198 maintainer of the particular module. The purpose is not only to inform
199 the other users of the module, but mainly to allow peer review. It is not
200 uncommon that several people contribute comments or spot bugs after a
203 Conversely, if you are using Gnulib, and a patch is posted that affects
204 one of the modules that your package uses, you have an interest in
205 proofreading the patch.
210 Most modules are under the GPL. Some -- mostly modules which can
211 reasonably be used in libraries -- are under LGPL. The source files
212 always say "GPL", but the real license specification is in the module
215 If you want to use some Gnulib modules under LGPL, you can do so by
216 passing the option --lgpl to @code{gnulib-tool}. This will replace the
217 GPL header with an LGPL header while copying the source files to your
220 Keep in mind that when you submit patches to files in Gnulib, you should
221 license them under a compatible license. This means that sometimes the
222 contribution will have to be LGPL, if the original file is available
223 under LGPL. You can find out about it by looking for a "License: LGPL"
224 information in the corresponding module description.
226 @node Steady Development
227 @section Steady Development
229 Gnulib modules are continually adapted, to match new practices, to be
230 consistent with newly added modules, or simply as a response to build
231 failure reports. We don't make releases, but instead recommend to use the
232 newest version of Gnulib from the CVS, except in periods of major changes.
237 Gnulib is open in the sense that we gladly accept contributions if they
238 are generally useful, well engineered, and if the contributors have signed
239 the obligatory papers with the FSF.
241 The module system is open in the sense that a package using Gnulib can
244 locally patch or override files in Gnulib,
246 locally add modules that are treated like Gnulib modules by
250 This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}.