sourcebuild.texi (Test Suites): Improve.

2002-10-22  Nathanael Nerode  <neroden@gcc.gnu.org>

	* doc/sourcebuild.texi (Test Suites): Improve.

From-SVN: r58445

2 files changed, 46 insertions, 24 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 528fc779958..5681b67a3c0 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,7 @@
+2002-10-22  Nathanael Nerode  <neroden@gcc.gnu.org>
+
+	* doc/sourcebuild.texi (Test Suites): Improve.
+
 2002-10-22  Stan Shebs  <shebs@apple.com>
 
 	* config/rs6000/rs6000.c (rs6000_output_mi_thunk): Add missing
diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index 2a6b9163027..275a1042be5 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -824,6 +824,10 @@ the function should remain, that function may be defined as
 @code{static} to call @code{abort ()} (although redeclaring a function
 as static may not work on all targets).
 
+All testcases must be portable.  Target-specific testcases must have
+appropriate code to avoid causing failures on unsupported systems;
+unfortunately, the mechanisms for this differ by directory.
+
 FIXME: discuss non-C test suites here.
 
 @node C Tests
@@ -833,6 +837,42 @@ GCC contains the following C language test suites, in the
 @file{gcc/testsuite} directory:
 
 @table @file
+@item gcc.dg
+This contains tests of particular features of the C compiler, using the 
+more modern @samp{dg} harness.  Correctness tests for various compiler
+features should go here if possible.
+
+Magic comments determine whether the file 
+is preprocessed, compiled, linked or run.  In these tests, error and warning 
+message texts are compared against expected texts or regular expressions 
+given in comments.  These tests are run with the options @samp{-ansi -pedantic}
+unless other options are given in the test.  Except as noted below they
+are not run with multiple optimization options.
+@item gcc.dg/cpp
+This subdirectory contains tests of the preprocessor.
+@item gcc.dg/debug
+This subdirectory contains tests for debug formats.  Tests in this
+subdirectory are run for each debug format that the compiler supports.
+@item gcc.dg/format
+This subdirectory contains tests of the @option{-Wformat} format
+checking.  Tests in this directory are run with and without
+@option{-DWIDE}.
+@item gcc.dg/noncompile
+This subdirectory contains tests of code that should not compile and
+does not need any special compilation options.  They are run with
+multiple optimization options, since sometimes invalid code crashes
+the compiler with optimization.
+@item gcc.dg/special
+FIXME: describe this.
+
+@item gcc.c-torture
+This contains particlar code fragments which have historically broken easily.
+These tests are run with multiple optimization options, so tests for features
+which only break at some optimization levels belong here.  This also contains
+tests to check that certain optimizations occur.  It might be worthwhile to 
+separate the correctness tests cleanly from the code quality tests, but
+it hasn't been done yet.
+
 @item gcc.c-torture/compat
 FIXME: describe this.
 
@@ -850,34 +890,12 @@ such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
 @item gcc.c-torture/execute
 This test suite contains test cases that should compile, link and run;
 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
+@item gcc.c-torture/execute/ieee
+This contains tests which are specific to IEEE floating point.
 @item gcc.c-torture/unsorted
 FIXME: describe this.
 
 This directory should probably not be used for new tests.
-@item gcc.dg
-This test suite contains tests using the more modern @samp{dg} harness.
-Magic comments determine whether the file is preprocessed, compiled,
-linked or run.  In these tests, error and warning message texts are
-compared against expected texts or regular expressions given in
-comments.  These tests are run with the options @samp{-ansi -pedantic}
-unless other options are given in the test.  Except as noted below they
-are not run with multiple optimization options.
-@item gcc.dg/cpp
-This subdirectory contains tests of the preprocessor.
-@item gcc.dg/debug
-This subdirectory contains tests for debug formats.  Tests in this
-subdirectory are run for each debug format that the compiler supports.
-@item gcc.dg/format
-This subdirectory contains tests of the @option{-Wformat} format
-checking.  Tests in this directory are run with and without
-@option{-DWIDE}.
-@item gcc.dg/noncompile
-This subdirectory contains tests of code that should not compile and
-does not need any special compilation options.  They are run with
-multiple optimization options, since sometimes invalid code crashes
-the compiler with optimization.
-@item gcc.dg/special
-FIXME: describe this.
 @item gcc.c-torture/misc-tests
 FIXME: describe this, when it should be used for new tests and when it
 shouldn't.