X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-intro.texi;h=2a32c81643a21373184058f5b66f30f7953c5b3b;hb=55898ee1c7c12e63772c65e772577f10bb7adb31;hp=15698313874d5cf3d5e06a6229e5bd88fe0358d4;hpb=55d7443b920dbab780cc2ad2d1b138c31cf0b0b9;p=gnulib.git diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi index 156983138..2a32c8164 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,25 @@ 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 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 +87,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 +104,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 +174,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 Woe32 requires a +different API than the classical POSIX @code{basename} function. @subsection Reusable application code @@ -173,7 +210,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 +244,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 +313,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 +347,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}).