poll-h: Create poll.h on all platforms.

[gnulib.git] / doc / gnulib-intro.texi

diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi
index 1569831..2a32c81 100644 (file)
--- 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
 @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
 
 @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
 
 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
 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
 
 @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,
 
 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 @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}.
 
 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
 @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
 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,
 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
 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
 
 
 @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
 
 
 @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
 @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.
 
 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
 
 @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
 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
 
 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
 
 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
 
 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
 
 @node Openness
 @section Openness


@@ -247,5 +347,5 @@ locally add modules that are treated like Gnulib modules by
 @code{gnulib-tool}.
 @end enumerate
 
 @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}).