install.texi: Document the multiple testsuite options.

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

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

From-SVN: r71582

2 files changed, 76 insertions, 2 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index fbf3472..5aa6ebc 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,7 @@
+2003-09-19  Phil Edwards  <phil@codesourcery.com>
+
+	* doc/install.texi:  Document the multiple testsuite options.
+
 2003-09-19  Gerald Pfeifer  <gerald@pfeifer.com>
 
 	* doc/install.texi (Specific): Add the specific versions of GCC
diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index fcde3e8..ab2efa4 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -1514,12 +1514,82 @@ To get a list of the possible @file{*.exp} files, pipe the
 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 involving @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}, 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.)
+
+
+@section Additional testing for Java Class Libraries
+
 The Java runtime tests can be executed via @samp{make check}
 in the @file{@var{target}/libjava/testsuite} directory in
 the build tree.
 
-@section Additional testing for Java Class Libraries
-
 The @uref{http://sources.redhat.com/mauve/,,Mauve Project} provides
 a suite of tests for the Java Class Libraries.  This suite can be run
 as part of libgcj testing by placing the Mauve tree within the libjava