[doc PATCH] Detailed description of invoking testsuite features in installation manual

[Phil Edwards]

It occurred to me that Alexandre's magic check-%// target in the gcc
makefile wasn't documented anywhere.  Then it also occurred to me that the
only place the slash and brace features of --target_board were documented
is the old GCC FAQ.

This adds descriptions to the "Testing" section of the installation
instructions.  It goes through install.texi2html with no problems.  Comments?


2003-09-13  Phil Edwards  <phil@codesourcery.com>

	* doc/install.texi:  Document the multiple testsuite options.


Index: doc/install.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/install.texi,v
retrieving revision 1.223
diff -u -3 -p -r1.223 install.texi
--- doc/install.texi	26 Aug 2003 18:47:26 -0000	1.223
+++ doc/install.texi	13 Sep 2003 05:09:32 -0000
@@ -1514,6 +1514,76 @@ To get a list of the possible @file{*.ex
 output of @samp{make check} into a file and look at the
 @samp{Running @dots{}  .exp} lines.
 
+@section Passing options and running multiple testsuites
+
+You can pass multiple options to the testsuite using the
+@samp{--target_board} option of DejaGNU, either passed as part of
+@samp{RUNTESTFLAGS}, or directly to @command{runtest} if you prefer to
+work outside the makefiles.  For example,
+
+@example
+    make check-g++ RUNTESTFLAGS="--target_board=unix/-O3/-fno-strength-reduce"
+@end example
+
+will run the standard @command{g++} testsuites (``unix'' is the target name
+for a standard native testsuite situation), passing
+``@samp{-O3 -fno-strength-reduce}'' to the compiler on every test, i.e.,
+slashes separate options.
+
+You can run the testsuites multiple times using combinations of options
+with a syntax similar to the brace expansion of popular shells:
+
+@example
+    @dots{}"--target_board=arm-sim@{-mhard-float,-msoft-float@}@{-O1,-O2,-O3,@}"
+@end example
+
+(Note the empty option caused by the trailing comma in the final group.)
+The following will run each testsuite eight times using the @samp{arm-sim}
+target, as if you had specified all possible combinations yourself:
+
+@example
+    --target_board=arm-sim/-mhard-float/-O1
+    --target_board=arm-sim/-mhard-float/-O2
+    --target_board=arm-sim/-mhard-float/-O3
+    --target_board=arm-sim/-mhard-float
+    --target_board=arm-sim/-msoft-float/-O1
+    --target_board=arm-sim/-msoft-float/-O2
+    --target_board=arm-sim/-msoft-float/-O3
+    --target_board=arm-sim/-msoft-float
+@end example
+
+They can be combined as many times as you wish, in arbitrary ways.  This
+list:
+
+@example
+    @dots{}"--target_board=unix/-Wextra@{-O3,-fno-strength-reduce@}@{-fomit-frame-pointer,@}"
+@end example
+
+will generate four combinations, all incolving @samp{-Wextra}.
+
+The disadvantage to this method is that the testsuites are run in serial,
+which is a waste on multiprocessor systems.  For users with GNU Make and
+a shell which performs brace expansion, you can run the testsuites in
+parallel by having the shell perform the combinations and @command{make}
+do the parallel runs.  Instead of using @samp{--target_board} yourself,
+use a special makefile target:
+
+@example
+    make -j@var{N} check-@var{testsuite}//@var{test-target}/@var{option1}/@var{option2}/@dots{}
+@end example
+
+For example,
+
+@example
+    make -j3 check-gcc//sh-hms-sim/@{-m1,-m2,-m3,-m3e,-m4@}/@{,-nofpu@}
+@end example
+
+will run three concurrent ``make-gcc'' testsuites, eventually testing all
+ten combinations as described above.  Note that this is currently only
+supported in the @file{gcc} subdirectory.  (To see how this works, try
+typing @command{echo} before the example given here.)
+
+
 The Java runtime tests can be executed via @samp{make check}
 in the @file{@var{target}/libjava/testsuite} directory in
 the build tree.