X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-intro.texi;h=d962ace7a23b24a89efd094186f4be88eede1e41;hb=b5cc9885b4b5a247870adf0ed9b9f4a5a3347a26;hp=15698313874d5cf3d5e06a6229e5bd88fe0358d4;hpb=55d7443b920dbab780cc2ad2d1b138c31cf0b0b9;p=gnulib.git diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi index 156983138..d962ace7a 100644 --- a/doc/gnulib-intro.texi +++ b/doc/gnulib-intro.texi @@ -1,4 +1,38 @@ -@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 @@ -11,11 +45,11 @@ 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 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 @@ -26,23 +60,138 @@ 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 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 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 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, @@ -51,14 +200,14 @@ 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 +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}. @@ -68,8 +217,8 @@ The module system serves two purposes: @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 @@ -138,24 +287,25 @@ 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 +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 native Windows +requires a different API than the classical POSIX @code{basename} function. @subsection Reusable application code @@ -173,7 +323,7 @@ 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 +@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. @@ -207,15 +357,63 @@ 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 +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 @@ -228,8 +426,23 @@ information in the corresponding module description. 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 @@ -247,5 +460,5 @@ 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}. - +This is achieved by the @samp{--local-dir} option of @code{gnulib-tool} +(@pxref{Extending Gnulib}).