Simplify gl_LIBUNISTRING_VERSION_CMP expansion.

[gnulib.git] / doc / gnulib.texi

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index d3c811b..4cbc9e7 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -614,6 +614,7 @@ before every release.
 @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::
@@ -689,6 +690,81 @@ This module is obsolete.
 @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
 
@@ -6236,6 +6312,7 @@ This list of functions is sorted according to the header that declares them.
 * setutent::
 * updwtmp::
 * utmpname::
+* login_tty::
 @end menu
 
 @include glibc-functions/endutent.texi
@@ -6249,6 +6326,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/login_tty.texi
 
 @node Glibc utmpx.h
 @section Glibc Extensions to @code{<utmpx.h>}
@@ -6338,6 +6416,7 @@ This list of functions is sorted according to the header that declares them.
 * func::
 * warnings::
 * manywarnings::
+* Running self-tests under valgrind::
 @end menu
 
 @node alloca
@@ -6436,6 +6515,8 @@ generated automatically.
 
 @include manywarnings.texi
 
+@include valgrind-tests.texi
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License