[DOC PATCH] sourcebuild.texi, describe binary compatibility testing

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

This patch moves the documentation for language-independent support for
binary compatibility testing from a README file to the test suite
section of the internals manual.  I wrote this support, so I doubt that
anyone else will review it for technical content.  I would greatly
appreciate a review from a documentation maintainer.

This information applies to mainline and gcc-3.3-branch.  It's been
tested using "make info" and "make dvi".  OK to apply?

2003-04-09  Janis Johnson  <janis187 at us dot ibm dot com>

	* doc/sourcebuild.texi (Test Suites): Document support for testing
	binary compatibility.

testsuite:

2003-04-09  Janis Johnson  <janis187 at us dot ibm dot com>

	* README.compat: Delete.

Index: doc/sourcebuild.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/sourcebuild.texi,v
retrieving revision 1.17
diff -u -p -r1.17 sourcebuild.texi
--- doc/sourcebuild.texi	8 Apr 2003 06:39:14 -0000	1.17
+++ doc/sourcebuild.texi	9 Apr 2003 18:33:27 -0000
@@ -759,6 +759,7 @@ here; FIXME: document the others.
 * libgcj Tests::    The Java library test suites.
 * gcov Testing::    Support for testing gcov.
 * profopt Testing:: Support for testing profile-directed optimizations.
+* compat Testing::  Support for testing binary compatibility.
 @end menu
 
 @node Test Idioms
@@ -1063,3 +1064,83 @@ suffix of profile data files
 list of options with which to run each test, similar to the lists for
 torture tests
 @end table
+
+ at node compat Testing
+ at subsection Support for testing binary compatibility
+
+The file @file{compat.exp} provides language-independent support for
+binary compatibility testing.  It supports testing interoperability
+of two compilers that follow the same ABI, or of multiple sets of
+compiler options that are not intended to affect binary compatibility.
+It is intended to be used for test suites that complement ABI test
+suites.
+
+A test supported by this framework is split into three parts, each in
+a separate source file: a main program and two pieces that split up
+the functionality being tested.
+
+ at table @file
+ at item @var{testname}_main dot  at var{suffix}
+contains the main program, which calls a function in file
+ at file{@var{testname}_x dot  at var{suffix}}
+
+ at item @var{testname}_x dot  at var{suffix}
+contains at least one call to a function in
+ at file{@var{testname}_y dot  at var{suffix}}
+
+ at item @var{testname}_y dot  at var{suffix}
+shares data with, or gets arguments from,
+ at file{@var{testname}_x dot  at var{suffix}}
+ at end table
+
+Within each test, the main program and
+one funtional piece are compiled by the GCC under test.  The other
+piece can be compiled by an alternate compiler.  If no alternate
+compiler is specified, then they 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.
+
+ at file{compat dot exp} defines default pairs of compiler options.
+These can be overridden by defining the environment variable
+ at code{COMPAT_OPTIONS} as:
+
+ at smallexample
+COMPAT_OPTIONS="[list [list @{ at var{tst1}@} @{ at var{alt1}@}]
+  ...[list @{ at var{tstn}@} @{ at var{altn}@}]]"
+ at end smallexample
+
+where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
+used by the compiler under test and @var{alti} used by the alternate
+compiler.  For example:
+ at code{[list [list @{-g at } @{-O3 at }] [list @{-O3 at } @{-g at }]]} dot 
+
+An alternate compiler is specified by defining an environment
+variable; for C++ define @code{ALT_CXX_UNDER_TEST} to be the full
+pathname of an installed compiler.  That will be written to the
+ at file{site dot 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 @code{COMPAT_OPTIONS}.  When
+ at code{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
+the compiler under test but with combinations of the options from
+ at code{COMPAT_OPTIONS} dot 
+
+To run only the C++ compatibility suite using the compiler under test
+and another version of GCC, using non-default pairs of compiler options
+lists, do the following from @file{$ at {objdir@}/gcc}:
+
+ at smallexample
+rm site.exp
+make -k \
+  ALT_CXX_UNDER_TEST=$ at {alt_prefix@}/bin/g++ \
+  COMPAT_OPTIONS="lists as shown above" \
+  check-c++ \
+  RUNTESTFLAGS="compat.exp"
+ at end smallexample
+
+A test that fails when the pieces are compiled with different
+compilers but passes when the pieces are compiled with the same
+compiler demonstrates incompatibility of the generated code or
+runtime support.  A test that fails for the alternate compiler but
+passes for the compiler under test probably tests for a fix that
+is not present in the alternate compiler.