-@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
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()} which is not portable to Windows), as well
+@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
+Mac OS 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 rarely 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
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
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.
+component of a file name --- here the portability to native Windows
+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.
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 currently
-means "GPLv2+" (GPLv2 or newer, at the licensee's choice); if it says "LGPL",
-it currently means "LGPLv2+" (LGPLv2 or newer, at the licensee's choice).
+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
Documentation files are under this copyright:
@quotation
-Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@*
+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.1 or
+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, with no Front-Cover Texts, and with no Back-Cover
-Texts.
+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.
+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 Git repository, except in periods of major
-changes. The source tree can also be fetched from a read-only CVS that
-mirrors the Git repository.
+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