autoupdate

[gnulib.git] / doc / gnulib.texi

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index d3c811b..a1f5446 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -54,6 +54,7 @@ Documentation License''.
 * Introduction::
 * Invoking gnulib-tool::
 * Writing modules::
 * Introduction::
 * Invoking gnulib-tool::
 * Writing modules::

+* Extending Gnulib::

 * Miscellaneous Notes::
 * POSIX Substitutes Library::       Building as a separate substitutes library.
 * Header File Substitutes::         Overriding system headers.
 * Miscellaneous Notes::
 * POSIX Substitutes Library::       Building as a separate substitutes library.
 * Header File Substitutes::         Overriding system headers.


@@ -117,8 +118,8 @@ Resources:
 @node Writing modules
 @chapter Writing modules
 
 @node Writing modules
 @chapter Writing modules
 

-This chapter explains how to write modules of your own, either for your own
-package (to be used with gnulib-tool's @samp{--local-dir} option), or for
+This chapter explains how to write modules of your own, either to
+extend Gnulib for your own package (@pxref{Extending Gnulib}), or for

 inclusion in gnulib proper.
 
 The guidelines in this chapter do not necessarily need to be followed for
 inclusion in gnulib proper.
 
 The guidelines in this chapter do not necessarily need to be followed for


@@ -608,12 +609,91 @@ before every release.
 @end enumerate
 
 
 @end enumerate
 
 

+@node Extending Gnulib
+@chapter Extending Gnulib
+
+Gnulib modules are intended to be suitable for widespread use.  Most
+problems with Gnulib can and should be fixed in a generic way, so that
+all of Gnulib's users can benefit from the change.  But occasionally a
+problem arises that is difficult or undesirable to fix generically, or
+a project that uses Gnulib may need to work around an issue before the
+Gnulib maintainers commit a final fix.  Maintainers may also want to
+add their own pools of modules to projects as Gnulib ``staging
+areas.''
+
+The obvious way to make local changes to Gnulib modules is to use
+@command{gnulib-tool} to check out pristine modules, then to modify
+the results in-place.  This works well enough for short-lived
+experiments.  It is harder to keep modified versions of Gnulib modules
+for a long time, even though Git (or another distributed version
+control systems) can help out a lot with this during the development
+process.
+
+Git, however, doesn't address the distribution issue.  When a package
+``foobar'' needs a modified version of, say, @file{stdint.in.h}, it
+either has to put a comment into @file{foobar/autogen.sh} saying
+``Attention! This doesn't work with a pristine Gnulib, you need this
+and that patch after checking out Gnulib,'' or it has to use the
+@samp{--avoid=stdint} option and provide the modified @code{stdint}
+module in a different directory.
+
+The @option{--local-dir} option to @command{gnulib-tool} solves this
+problem.  It allows the package to override or augment Gnulib.  This
+means:
+
+@itemize @bullet
+@item
+You can store files that are to override Gnulib files or modules.
+
+@item
+You can store context diffs to be applied to Gnulib files.
+
+@item
+You can add modules of your own, that are not (yet) in Gnulib.
+
+@item
+You can also add unstructured amounts of code to the library, by
+grouping the non-Gnulib files of the library in a single kitchen-sink
+``module.''  (This kind of kitchen-sink module is not needed when you
+use the @command{gnulib-tool} option @samp{--makefile-name}.)
+@end itemize
+
+In a release tarball, you can distribute the contents of this
+@option{--local-dir} directory that will be combinable with newer
+versions of Gnulib, barring incompatible changes to Gnulib.
+
+If the @samp{--local-dir=@var{directory}} option is specified, then
+@command{gnulib-tool} looks in @file{@var{directory}} whenever it
+reads a file from the Gnulib directory.  Suppose @command{gnulib-tool}
+is looking for @var{file}.  Then:
+
+@itemize @bullet
+@item
+If @file{@var{directory}/@var{file}} exists, then @samp{gnulib-tool} uses
+it instead of the file included in Gnulib.
+
+@item
+Otherwise, if @file{@var{directory}/@var{file}.diff} exists, then
+@command{gnulib-tool} uses the file from Gnulib after applying the diff
+using the @command{patch} program.
+
+@item
+Otherwise, @command{gnulib-tool} uses the file included in Gnulib.
+@end itemize
+
+Please make wise use of this option.  It also allows you to easily
+hold back modifications you make to Gnulib macros in cases it may be
+better to share them.
+
+
+

 @node Miscellaneous Notes
 @chapter Miscellaneous Notes
 
 @menu
 * Out of memory handling::
 * Obsolete modules::
 @node Miscellaneous Notes
 @chapter Miscellaneous Notes
 
 @menu
 * Out of memory handling::
 * Obsolete modules::

+* Extra tests modules::

 * A C++ namespace for gnulib::      A different way of using Gnulib in C++
 * Library version handling::
 * Windows sockets::
 * A C++ namespace for gnulib::      A different way of using Gnulib in C++
 * Library version handling::
 * Windows sockets::


@@ -689,6 +769,81 @@ This module is obsolete.
 @end example
 
 
 @end example
 
 

+@node Extra tests modules
+@section Extra tests modules
+
+@cindex Extra tests modules
+@cindex C++ tests modules
+@cindex tests modules, C++
+@cindex long-running tests modules
+@cindex tests modules, long-running
+@cindex privileged tests modules
+@cindex tests modules, privileged
+@cindex unportable tests modules
+@cindex tests modules, unportable
+Test modules can be marked with some special status attributes.  When a
+test module has such an attribute, @code{gnulib-tool --import} will not
+include it by default.
+
+The supported status attributes are:
+
+@table @code
+@item c++-test
+Indicates that the test is testing C++ interoperability.  Such a test is
+useful in a C++ or mixed C/C++ package, but is useless in a C package.
+
+@item longrunning-test
+Indicates that the test takes a long time to compile or execute (more
+than five minutes or so).  Such a test is better avoided in a release
+that is made for the general public.
+
+@item privileged-test
+Indicates that the test will request special privileges, for example,
+ask for the superuser password.  Such a test may hang when run
+non-interactively and is therefore better avoided in a release that is
+made for the general public.
+
+@item unportable-test
+Indicates that the test is known to fail on some systems, and that
+there is no workaround about it.  Such a test is better avoided in a
+release that is made for the general public.
+@end table
+
+@code{gnulib-tool --import} will not include tests marked with these
+attributes by default.  When @code{gnulib-tool} is invoked with one
+of the options @code{--with-c++-tests}, @code{--with-longrunning-tests},
+@code{--with-privileged-tests}, @code{--with-unportable-tests}, it
+will include tests despite the corresponding special status attribute.
+When @code{gnulib-tool} receives the option @code{--with-all-tests},
+it will include all tests regardless of their status attributes.
+
+@code{gnulib-tool --create-testdir} and
+@code{gnulib-tool --create-megatestdir} by default include all tests of
+modules specified on the command line, regardless of their status
+attributes.  Tests of modules occurring as dependencies are not included
+by default if they have one of these status attributes.  The options
+@code{--with-c++-tests}, @code{--with-longrunning-tests},
+@code{--with-privileged-tests}, @code{--with-unportable-tests} are
+recognized here as well.  Additionally, @code{gnulib-tool} also
+understands the options @code{--without-c++-tests},
+@code{--without-longrunning-tests}, @code{--without-privileged-tests},
+@code{--without-unportable-tests}.
+
+In order to mark a module with a status attribute, you need to add it
+to the module description, like this:
+
+@example
+Status:
+longrunning-test
+@end example
+
+If only a part of a test deserves a particular status attribute, you
+can split the module into a primary and a secondary test module,
+say @code{foo-tests} and @code{foo-extra-tests}.  Then add a dependency
+from @code{foo-tests} to @code{foo-extra-tests}, and mark the
+@code{foo-extra-tests} with the particular status attribute.
+
+

 @node A C++ namespace for gnulib
 @section A C++ namespace for gnulib
 
 @node A C++ namespace for gnulib
 @section A C++ namespace for gnulib
 


@@ -6236,6 +6391,7 @@ This list of functions is sorted according to the header that declares them.
 * setutent::
 * updwtmp::
 * utmpname::
 * setutent::
 * updwtmp::
 * utmpname::

+* login_tty::

 @end menu
 
 @include glibc-functions/endutent.texi
 @end menu
 
 @include glibc-functions/endutent.texi


@@ -6249,6 +6405,7 @@ This list of functions is sorted according to the header that declares them.
 @include glibc-functions/setutent.texi
 @include glibc-functions/updwtmp.texi
 @include glibc-functions/utmpname.texi
 @include glibc-functions/setutent.texi
 @include glibc-functions/updwtmp.texi
 @include glibc-functions/utmpname.texi

+@include glibc-functions/login_tty.texi

 
 @node Glibc utmpx.h
 @section Glibc Extensions to @code{<utmpx.h>}
 
 @node Glibc utmpx.h
 @section Glibc Extensions to @code{<utmpx.h>}


@@ -6338,6 +6495,7 @@ This list of functions is sorted according to the header that declares them.
 * func::
 * warnings::
 * manywarnings::
 * func::
 * warnings::
 * manywarnings::

+* Running self-tests under valgrind::

 @end menu
 
 @node alloca
 @end menu
 
 @node alloca


@@ -6436,6 +6594,8 @@ generated automatically.
 
 @include manywarnings.texi
 
 
 @include manywarnings.texi
 

+@include valgrind-tests.texi
+

 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License