[DOC PATCH] compat testing in internals manual

[Janis Johnson <janis187 at us dot ibm dot com>]

Update the section about binary compatibility testsuites in the GCC
internals manual for functionality that's currently supported.  Fix
the spelling of DejaGnu to that prefered by that project.

Tested with 'make dvi' and 'make info' on i686-pc-linux-gnu.  OK?

2004-07-22  Janis Johnson  <janis187@us.ibm.com>

	* doc/sourcebuild.texi (compat testing): Document available
	test framework commands.

Index: doc/sourcebuild.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/sourcebuild.texi,v
retrieving revision 1.54
diff -u -p -r1.54 sourcebuild.texi
--- doc/sourcebuild.texi	19 Jul 2004 14:47:59 -0000	1.54
+++ doc/sourcebuild.texi	22 Jul 2004 21:12:06 -0000
@@ -1072,7 +1072,7 @@ Language-independent support for testing
 that branch profiling produces expected values, is provided by the
 expect file @file{gcov.exp}.  @command{gcov} tests also rely on procedures
 in @file{gcc.dg.exp} to compile and run the test program.  A typical
-@command{gcov} test contains the following DejaGNU commands within comments:
+@command{gcov} test contains the following DejaGnu commands within comments:
 
 @smallexample
 @{ dg-options "-fprofile-arcs -ftest-coverage" @}
@@ -1201,9 +1201,9 @@ Within each test, the main program and o
 compiled by the GCC under test.  The other piece can be compiled by
 an alternate compiler.  If no alternate compiler is specified,
 then all three source files are all compiled by the GCC under test.
-It's also possible to specify a pair of lists of compiler options,
-one list for each compiler, so that each test will be compiled with
-each pair of options.
+It's possible to specify pairs of sets of compiler options, with each
+pair containing a list of options for each compiler, so that each test
+will be compiled with each pair of options.
 
 @file{compat.exp} defines default pairs of compiler options.
 These can be overridden by defining the environment variable
@@ -1224,11 +1224,13 @@ built a second time using @code{-fpic} b
 and @code{-fPIC -O2} by the alternate compiler.
 
 An alternate compiler is specified by defining an environment
-variable; for C++ define @env{ALT_CXX_UNDER_TEST} to be the full
-pathname of an installed compiler.  That will be written to the
-@file{site.exp} file used by DejaGNU.  The default is to build each
+variable to be the full pathname of an installed compiler; for C
+define @env{ALT_CC_UNDER_TEST}, and for C++ define
+@env{ALT_CXX_UNDER_TEST}.  These will be written to the
+@file{site.exp} file used by DejaGnu.  The default is to build each
 test with the compiler under test using the first of each pair of
 compiler options from @env{COMPAT_OPTIONS}.  When
+@env{ALT_CC_UNDER_TEST} or
 @env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
 the compiler under test but with combinations of the options from
 @env{COMPAT_OPTIONS}.
@@ -1253,3 +1255,23 @@ runtime support.  A test that fails for 
 passes for the compiler under test probably tests for a bug that was
 fixed in the compiler under test but is present in the alternate
 compiler.
+
+The binary compatibility tests support a small number of test framework
+commands that appear within comments in a test file.
+
+@table @code
+@item dg-require-*
+These commands can be used in @file{@var{testname}_main.@var{suffix}}
+to skip the test if specific support is not available on the target.
+
+@item dg-options
+The specified options are used for compiling this particular source
+file, appended to the options from @env{COMPAT_OPTIONS}.  When this
+command appears in @file{@var{testname}_main.@var{suffix}} the options
+are also used to link the test program.
+
+@item dg-xfail-if
+This command can be used in a secondary source file to specify that
+compilation is expected to fail for particular options on particular
+targets.
+@end table