X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-intro.texi;h=ab518c8440d558a4f77544dece4de2c36c413e31;hb=07809063056aef043ba738ab8229042f1ffc9659;hp=c42a2080349893b71e36beb7d1afbe5328e6518e;hpb=f0081f71b5ac063b48f242d6f770d7826f2ec196;p=gnulib.git diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi index c42a20803..ab518c844 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 @@ -40,6 +74,119 @@ 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 @@ -140,7 +287,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 @@ -250,12 +398,13 @@ 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 @@ -277,10 +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 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 @@ -298,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}).