-@node Library vs. Reusable Code
+@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
@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 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.
+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
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 an applicative one -- no standard specifies an
-API for it --, the na@"ive 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 Unix and
-Windows, compared to the classical @code{fork()}/@code{exec()} 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.
+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 Target Platforms
+@section Target Platforms
+
+Gnulib supports a number of platforms that we call the ``reasonable
+portability targets''. This class consists of widespread operating systems,
+for three years after their last availability, or --- for proprietary
+operating systems --- as long as the vendor provides commercial support for
+it. Already existing Gnulib code for older operating systems is usually
+left in place for longer than these three years. So it comes that programs
+that use Gnulib run pretty well also on these older operating systems.
+
+Some operating systems are not very widespread, but are Free Software and
+are actively developed. Such platforms are also supported by Gnulib, if
+that OS's developers community keeps in touch with the Gnulib developers,
+by providing bug reports, analyses, or patches. For such platforms, Gnulib
+supports only the versions of the last year or the last few months,
+depending on the maturity of said OS project, the number of its users, and
+how often these users upgrade.
+
+Niche operating systems are generally unsupported by Gnulib, unless some
+of their developers or users contribute support to Gnulib.
+
+The degree of support Gnulib guarantees for a platform depends on the
+amount of testing it gets from volunteers. Platforms on which Gnulib
+is frequently tested are the best supported. Then come platforms with
+occasional testing, then platforms which are rarely tested. Usually,
+we fix bugs when they are reported. Except that some rarely tested
+platforms are also low priority; bug fixes for these platforms can
+take longer.
+
+As of 2011, the list of supported platforms is the following:
+
+@itemize
+@item
+glibc systems. With glibc 2.8 or newer, they are frequently tested. With
+glibc 2.3 or newer, they are occasionally tested.
+@item
+MacOS X. In versions 10.5 and 10.6, it's frequently tested. In version
+10.4, it's rarely tested.
+@item
+FreeBSD 6.0 or newer is occasionally tested. FreeBSD 5.x is rarely tested.
+@item
+NetBSD 5.0 or newer is occasionally tested. NetBSD 3.0 or newer is rarely
+tested.
+@item
+OpenBSD 4.0 or newer is occasionally tested. OpenBSD 3.8 or newer is rarely
+tested.
+@item
+AIX 6.1 or newer is occasionally tested. AIX 5.1 or newer is rarely tested.
+@item
+HP-UX 11.11 or newer is occasionally tested. HP-UX 11.00 is rarely tested.
+HP-UX 10.20 is rarely tested and low priority.
+@item
+IRIX 6.5 is occasionally tested. IRIX 5.3 is rarely tested and low priority.
+@item
+OSF/1 5.1 is occasionally tested. OSF/1 4.0 is rarely tested and low
+priority.
+@item
+Solaris 8 and newer are occasionally tested. Solaris 7 is rarely tested.
+Solaris 2.6 and older are rarely tested and low priority.
+@item
+Cygwin 1.7.x is frequently tested. Cygwin 1.5.x is occasionally tested.
+@item
+mingw is frequently tested. But note that some modules are currently
+unsupported on mingw: @code{mgetgroups}, @code{getugroups}, @code{idcache},
+@code{userspec}, @code{openpty}, @code{login_tty}, @code{forkpty},
+@code{pt_chown}, @code{grantpt}, @code{pty}, @code{savewd},
+@code{mkancesdirs}, @code{mkdir-p}, @code{euidaccess}, @code{faccessat}.
+The versions of Windows that are supported are Windows XP and newer.
+@item
+Native Windows, with MSVC as compiler, is not tested and low priority.
+@item
+mingw in 64-bit mode is not tested and low priority so far.
+@item
+Interix 6.1 is rarely tested, and requires the @code{suacomp} library
+(@url{http://sourceforge.net/projects/suacomp/}) in version 0.6.8 or newer.
+Interix 3.5 is not tested.
+@item
+Haiku is rarely tested, BeOS is not tested and low priority.
+@item
+uClibc on Linux is rarely tested.
+@item
+QNX is not tested and low priority.
+@end itemize
+
+Gnulib supports these operating systems only in an unvirtualized environment.
+When you run an OS inside a virtual machine, you have to be aware that the
+virtual machine can bring in bugs of its own. For example, floating-point
+operations on Solaris can behave slightly differently in QEMU than on real
+hardware. And Haiku's @command{bash} program misbehaves in VirtualBox 3,
+whereas it behaves fine in VirtualBox 4.
+
+Similarly, running native Windows binaries on GNU/Linux under WINE is
+rarely tested and low priority: WINE has a set of behaviours and bugs that
+is slightly different from native Windows.
+
+The following platforms are not supported by Gnulib. The cost of
+supporting them would exceed the benefit because they are rarely used, or
+poorly documented, or have been supplanted by other platforms, or diverge
+too much from POSIX, or some combination of these and other factors.
+Please don't bother sending us patches for them.
+
+@itemize
+@item
+Windows 95/98/ME.
+@item
+DJGPP and EMX (the 32-bit operating systems running in DOS).
+@item
+MSDOS (the 16-bit operating system).
+@item
+Windows Mobile, Symbian OS, iOS.
+@end itemize
@node Modules
@section Modules
Gnulib is divided into modules. Every module implements a single
-facility. Modules can depend on other modules.
+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,
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
+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}.
@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 --
+@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
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
+with @samp{.in} inserted before the @samp{.h} extension, 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.
+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.
+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
@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
+@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.
@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
+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.
+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 --lgpl to @code{gnulib-tool}. This will replace the
-GPL header with an LGPL header while copying the source files to your
-package.
+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
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. We don't make releases, but instead recommend to use the
-newest version of Gnulib from the CVS, except in periods of major changes.
+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
@code{gnulib-tool}.
@end enumerate
-This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}.
-
+This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}
+(@pxref{Extending Gnulib}).
projects / gnulib.git / blobdiff