Merge branch 'upstream' into stable

[gnulib.git] / doc / gnulib-intro.texi

@node Benefits
@section Benefits of using Gnulib

Gnulib is useful to enhance various aspects of a package:

@itemize @bullet
@item
Portability: With Gnulib, a package maintainer can program against the
POSIX and GNU libc APIs and nevertheless expect good portability to
platforms that don't implement POSIX.

@item
Maintainability: When a package uses modules from Gnulib instead of code
written specifically for that package, the maintainer has less code to
maintain.

@item
Security: Gnulib provides functions that are immune against vulnerabilities
that plague the uses of the corresponding commonplace functions. For
example, @code{asprintf}, @code{canonicalize_file_name} are not affected
by buffer sizing problems that affect @code{sprintf}, @code{realpath}.
@code{openat} does not have the race conditions that @code{open} has. Etc.

@item
Reliability: Gnulib provides functions that combine a call to a system
function with a check of the result. Examples are @code{xalloc},
@code{xprintf}, @code{xstrtod}, @code{xgetcwd}.

@item
Structure: Gnulib offers a way to structure code into modules, typically
one include file, one source code file, and one autoconf macro for each
functionality. Modularity helps maintainability.
@end itemize

@node Library vs Reusable Code
@section Library vs. Reusable Code

Classical libraries are installed as binary object code.  Gnulib is
different: It is used as a source code library.  Each package that uses
Gnulib thus ships with part of the Gnulib source code.  The used portion
of Gnulib is tailored to the package: A build tool, called
@code{gnulib-tool}, is provided that copies a tailored subset of Gnulib
into the package.

@node Portability and Application Code
@section Portability and Application Code

One of the goals of Gnulib is to make portable programming easy, on
the basis of the standards relevant for GNU (and Unix).  The objective
behind that is to avoid a fragmentation of the user community into
disjoint user communities according to the operating system, and
instead allow synergies between users on different operating systems.

Another goal of Gnulib is to provide application code that can be shared
between several applications.  Some people wonder: "What? glibc doesn't
have a function to copy a file?"  Indeed, the scope of a system's libc is
to implement the relevant standards (ISO C99, POSIX:2001) and to provide
access functions to the kernel's system calls, and little more.

There is no clear borderline between both areas.

For example, Gnulib has a facility for generating the name of backup
files.  While this task is entirely at the application level --- no
standard specifies an API for it --- the na@"{@dotless{i}}ve code has
some portability problems because on some platforms the length of file
name components is limited to 30 characters or so.  Gnulib handles
that.

Similarly, Gnulib has a facility for executing a command in a
subprocess.  It is at the same time a portability enhancement (it
works on GNU, Unix, and Windows, compared to the classical
@code{fork}/@code{exec} idiom which is not portable to Windows), as well
as an application aid: it takes care of redirecting stdin and/or
stdout if desired, and emits an error message if the subprocess
failed.

@node Modules
@section Modules

Gnulib is divided into modules.  Every module implements a single
facility.  Modules can depend on other modules.

A module consists of a number of files and a module description.  The
files are copied by @code{gnulib-tool} into the package that will use it,
usually verbatim, without changes.  Source code files (.h, .c files)
reside in the @file{lib/} subdirectory.  Autoconf macro files reside in
the @file{m4/} subdirectory.  Build scripts reside in the
@file{build-aux/} subdirectory.

The module description contains the list of files --- @code{gnulib-tool}
copies these files.  It contains the module's
dependencies --- @code{gnulib-tool} installs them as well.  It also
contains the autoconf macro invocation (usually a single line or
nothing at all) --- @code{gnulib-tool} ensures this is invoked from the
package's @file{configure.ac} file.  And also a @file{Makefile.am}
snippet --- @code{gnulib-tool} collects these into a @file{Makefile.am}
for the tailored Gnulib part.  The module description and include file
specification are for documentation purposes; they are combined into
@file{MODULES.html}.

The module system serves two purposes:

@enumerate
@item
It ensures consistency of the used autoconf macros and @file{Makefile.am}
rules with the source code.  For example, source code which uses the
@code{getopt_long} function --- this is a common way to implement parsing
of command line options in a way that complies with the GNU standards ---
needs the source code (@file{lib/getopt.c} and others), the autoconf macro
which detects whether the system's libc already has this function (in
@file{m4/getopt.m4}), and a few @file{Makefile.am} lines that create the
substitute @file{getopt.h} if not.  These three pieces belong together.
They cannot be used without each other.  The module description and
@code{gnulib-tool} ensure that they are copied altogether into the
destination package.

@item
It allows for scalability.  It is well-known since the inception of the
MODULA-2 language around 1978 that dissection into modules with
dependencies allows for building large sets of code in a maintainable way.
The maintainability comes from the facts that:

@itemize @bullet
@item
Every module has a single purpose; you don't worry about other parts of
the program while creating, reading or modifying the code of a module.

@item
The code you have to read in order to understand a module is limited to
the source of the module and the .h files of the modules listed as
dependencies.  It is for this reason also that we recommend to put the
comments describing the functions exported by a module into its .h file.
@end itemize

In other words, the module is the elementary unit of code in Gnulib,
comparable to a class in object-oriented languages like Java or C#.
@end enumerate

The module system is the basis of @code{gnulib-tool}.  When
@code{gnulib-tool} copies a part of Gnulib into a package, it first
compiles a module list, starting with the requested modules and adding all
the dependencies, and then collects the files, @file{configure.ac}
snippets and @file{Makefile.am} snippets.

@node Various Kinds of Modules
@section Various Kinds of Modules

There are modules of various kinds in Gnulib.  For a complete list of the
modules, see in @file{MODULES.html}.

@subsection Support for ISO C or POSIX functions.

When a function is not implemented by a system, the Gnulib module provides
an implementation under the same name.  Examples are the @samp{snprintf}
and @samp{readlink} modules.

Similarly, when a function is not correctly implemented by a system,
Gnulib provides a replacement.  For functions, we use the pattern

@smallexample
#if !HAVE_WORKING_FOO
# define foo rpl_foo
#endif
@end smallexample

@noindent
and implement the @code{foo} function under the name @code{rpl_foo}.  This
renaming is needed to avoid conflicts at compile time (in case the system
header files declare @code{foo}) and at link/run time (because the code
making use of @code{foo} could end up residing in a shared library, and
the executable program using this library could be defining @code{foo}
itself).

For header files, such as @code{stdbool.h} or @code{stdint.h}, we provide
the substitute only if the system doesn't provide a correct one.  The
template of this replacement is distributed in a slightly different name,
with an added underscore, so that on systems which do provide a correct
header file the system's one is used.

@subsection Enhancements of ISO C or POSIX functions

These are sometimes POSIX functions with GNU extensions also found in
glibc --- examples: @samp{getopt}, @samp{fnmatch} --- and often new
APIs --- for example, for all functions that allocate memory in one way
or the other, we have variants which also include the error checking
against the out-of-memory condition.

@subsection Portable general use facilities

Examples are a module for copying a file --- the portability problems
relate to the copying of the file's modification time, access rights,
and extended attributes --- or a module for extracting the tail
component of a file name --- here the portability to Woe32 requires a
different API than the classical POSIX @code{basename} function.

@subsection Reusable application code

Examples are an error reporting function, a module that allows output of
numbers with K/M/G suffixes, or cryptographic facilities.

@subsection Object oriented classes

Examples are data structures like @samp{list}, or abstract output stream
classes that work around the fact that an application cannot implement an
stdio @code{FILE} with its logic.  Here, while staying in C, we use
implementation techniques like tables of function pointers, known from the
C++ language or from the Linux kernel.

@subsection Interfaces to external libraries

Examples are the @samp{iconv} module, which interfaces to the
@code{iconv} facility, regardless whether it is contained in libc or in
an external @code{libiconv}.  Or the @samp{readline} module, which
interfaces to the GNU readline library.

@subsection Build / maintenance infrastructure

An example is the @samp{maintainer-makefile} module, which provides extra
Makefile tags for maintaining a package.

@node Collaborative Development
@section Collaborative Development

Gnulib is maintained collaboratively.  The mailing list is
@code{<bug-gnulib at gnu dot org>}.  Be warned that some people on the
list may be very active at some times and unresponsive at other times.

Every module has one or more maintainers.  While issues are discussed
collaboratively on the list, the maintainer of a module nevertheless has
a veto right regarding changes in his module.

All patches should be posted the list, regardless whether they are
proposed patches or whether they are committed immediately by the
maintainer of the particular module.  The purpose is not only to inform
the other users of the module, but mainly to allow peer review.  It is not
uncommon that several people contribute comments or spot bugs after a
patch was proposed.

Conversely, if you are using Gnulib, and a patch is posted that affects
one of the modules that your package uses, you have an interest in
proofreading the patch.

@node Copyright
@section Copyright

Most modules are under the GPL.  Some, mostly modules which can
reasonably be used in libraries, are under LGPL.  The source files
always say "GPL", but the real license specification is in the module
description file.  If the module description file says "GPL", it means
"GPLv3+" (GPLv3 or newer, at the licensee's choice); if it says "LGPL",
it means "LGPLv3+" (LGPLv3 or newer, at the licensee's choice).

More precisely, the license specification in the module description
file applies to the files in @file{lib/} and @file{build-aux/}.  Different
licenses apply to files in special directories:

@table @file
@item modules/
Module description files are under this copyright:

@quotation
Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@*
Copying and distribution of this file, with or without modification,
in any medium, are permitted without royalty provided the copyright
notice and this notice are preserved.
@end quotation

@item m4/
Autoconf macro files are under this copyright:

@quotation
Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@*
This file is free software; the Free Software Foundation
gives unlimited permission to copy and/or distribute it,
with or without modifications, as long as this notice is preserved.
@end quotation

@item tests/
If a license statement is not present in a test module, the test files are
under GPL.  Even if the corresponding source module is under LGPL, this is
not a problem, since compiled tests are not installed by ``make install''.

@item doc/
Documentation files are under this copyright:

@quotation
Copyright @copyright{} 2004-200Y Free Software Foundation, Inc.@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation
@end table

If you want to use some Gnulib modules under LGPL, you can do so by
passing the option @samp{--lgpl} to @code{gnulib-tool}.  This will
replace the GPL header with an LGPL header while copying the source
files to your package.  Similarly, if you want some Gnulib modules
under LGPLv2+ (Lesser GPL version 2.1 or newer), you can do so by
passing the option @samp{--lgpl=2} to @code{gnulib-tool}.

Keep in mind that when you submit patches to files in Gnulib, you should
license them under a compatible license.  This means that sometimes the
contribution will have to be LGPL, if the original file is available
under LGPL.  You can find out about it by looking for a "License: LGPL"
information in the corresponding module description.

@node Steady Development
@section Steady Development

Gnulib modules are continually adapted, to match new practices, to be
consistent with newly added modules, or simply as a response to build
failure reports.  Gnulib is available in two qualities:

@itemize
@item
There is the newest version of Gnulib from the Git repository.  The
source tree can also be fetched from a read-only CVS that mirrors the Git
repository.

@item
We also make stable releases every two months, at
@url{http://erislabs.net/ianb/projects/gnulib/}.
@end itemize

If you are willing to report an occasional regression, we recommend to
use the newest version always, except in periods of major changes.  Most
Gnulib users do this.  If you prefer stable releases, please use the
newest stable release.

@node Openness
@section Openness

Gnulib is open in the sense that we gladly accept contributions if they
are generally useful, well engineered, and if the contributors have signed
the obligatory papers with the FSF.

The module system is open in the sense that a package using Gnulib can
@enumerate
@item
locally patch or override files in Gnulib,
@item
locally add modules that are treated like Gnulib modules by
@code{gnulib-tool}.
@end enumerate

This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}.