X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-intro.texi;h=2a32c81643a21373184058f5b66f30f7953c5b3b;hb=55898ee1c7c12e63772c65e772577f10bb7adb31;hp=63137fefc03a502ed87cccba0d0bdde8120f20d5;hpb=85392f85300352373c54186bdd503c8a28f16359;p=gnulib.git diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi index 63137fefc..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 @@ -35,7 +69,7 @@ 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()} 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. @@ -140,7 +174,8 @@ 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 @@ -175,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. @@ -250,19 +285,22 @@ not a problem, since compiled tests are not installed by ``make install''. 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 @@ -275,10 +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 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 @@ -296,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}).