Extra tests modules
===================

Test modules can be marked with some special status attributes.  When a test module has such an attribute, gnulib-tool --import will not include it by default.

The supported status attributes are:

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.

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.

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.

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.

gnulib-tool --import --with-tests will not include tests marked with these attributes by default.  When gnulib-tool is invoked with one of the options --with-c++-tests, --with-longrunning-tests, --with-privileged-tests, --with-unportable-tests, it will include tests despite the corresponding special status attribute. When gnulib-tool receives the option --with-all-tests, it will include all tests regardless of their status attributes.

gnulib-tool --create-testdir --with-tests and gnulib-tool --create-megatestdir --with-tests 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 --with-c++-tests, --with-longrunning-tests, --with-privileged-tests, --with-unportable-tests are recognized here as well.  Additionally, gnulib-tool also understands the options --without-c++-tests, --without-longrunning-tests, --without-privileged-tests, --without-unportable-tests.

In order to mark a module with a status attribute, you need to add it to the module description, like this:

     Status:
     longrunning-test

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 foo-tests and foo-extra-tests.  Then add a dependency from foo-tests to foo-extra-tests, and mark the foo-extra-tests with the particular status attribute.