doc: Complete wvtest documentation

diff --git a/doc/omk-manual.texinfo b/doc/omk-manual.texinfo
index 559c6684ad1afd5459f752636c32ab12ad73a61d..f695b1319e1b0ab5dec664e102ceb6e92060bdb8 100644 (file)
--- a/doc/omk-manual.texinfo
+++ b/doc/omk-manual.texinfo
@@ -910,22 +910,52 @@ generated_header.h: $(SOURCES_DIR)/data_file.txt
 @node Integration of Wvtest Framework,  , Adding Hooks to Passes, Advanced OMK Features
 @subsection Integration of Wvtest Framework
 
-OMK has integrated support for Wvtest unit testing framework (see
-@uref{https://github.com/apenwarr/wvtest}).
+OMK has integrated support for
+@uref{https://github.com/apenwarr/wvtest,Wvtest unit testing framework}.
+It is a very minimalistic framework whose integration with OMK does not
+impose almost any particular policy of writing the tests. Wvtest tests
+are specified by the following two variables:
 
 @defvar wvtest_PROGRAMS
-This variable is the same as @ref{test_PROGRAMS} with the exception that
-the program is automatically executed by @command{make wvtest} (see
-below).
+This variable has the same meaning as @ref{test_PROGRAMS} with two
+exceptions: (1) the program is automatically linked with the library
+specified by @code{WVTEST_LIBRARY} variable and (2) the program is
+automatically executed by @command{make wvtest} (see below).
 @end defvar
 
-@defvar wvtest_SCRIPT
-TODO
+@defvar wvtest_SCRIPTS
+Defines the name of a script (e.g. shell script) which is executed by
+@command{make wvtest}. Write the scripts so, that they can be run from
+arbitrary directory, i.e. in the case of shell scripts ensure that the
+@file{wvtest.sh} library is sourced like this:
+@example
+@code{. $(dirname $0)/wvtest.sh}
+@end example
 @end defvar
 
-@command{make wvtest} TODO
-
+@defvar WVTEST_LIBRARY
+Specifies the name of the library that is automatically linked with
+@code{wvtest_PROGRAMS}. The default is @file{wvtest}.
+@end defvar
 
+There is also an OMK pass called @code{wvtest-pass} which consecutively
+runs all @code{wvtest_PROGRAMS} and @code{wvtest_SCRIPTS} in the
+traversed subdirectories of the current directory. Every program or
+script is executed in a temporary directory under @file{_build}
+directory with @code{PATH} variable modified to include
+@file{_compiled/bin} as the first component and @code{LD_LIBRARY_PATH}
+modified to include @file{_compiled/lib} as the first component. This
+allows the tests to run the @code{bin_PROGRAMS} without explicitly
+specifying their full path and to use shared libraries without the path
+as well.
+
+When make is invoked as @command{make wvtest} it runs @command{make
+wvtest-pass} under the control of @file{wvtestrun} script, which must be
+present in the same directory as @file{Makefile.rules}. This script
+suppresses the normal output of passed tests and prints only their
+summary. For failed tests, the full output is shown. Additionally, when
+the output is written to a terminal, the status of each test is
+displayed in color for easy inspection.
 
 @node Properties of Specific Makefile.rules, Running OMK under Windows OS, Advanced OMK Features, User's Manual
 @section Properties of Specific Makefile.rules