gccint: compat Testing

1 
1 7.8 Support for testing binary compatibility
1 ============================================
1 
1 The file 'compat.exp' provides language-independent support for binary
1 compatibility testing.  It supports testing interoperability of two
1 compilers that follow the same ABI, or of multiple sets of compiler
1 options that should not affect binary compatibility.  It is intended to
1 be used for testsuites that complement ABI testsuites.
1 
1  A test supported by this framework has three parts, each in a separate
1 source file: a main program and two pieces that interact with each other
1 to split up the functionality being tested.
1 
1 'TESTNAME_main.SUFFIX'
1      Contains the main program, which calls a function in file
1      'TESTNAME_x.SUFFIX'.
1 
1 'TESTNAME_x.SUFFIX'
1      Contains at least one call to a function in 'TESTNAME_y.SUFFIX'.
1 
1 'TESTNAME_y.SUFFIX'
1      Shares data with, or gets arguments from, 'TESTNAME_x.SUFFIX'.
1 
1  Within each test, the main program and one functional piece are
1 compiled by the GCC under test.  The other piece can be compiled by an
1 alternate compiler.  If no alternate compiler is specified, then all
1 three source files are all compiled by the GCC under test.  You can
1 specify pairs of sets of compiler options.  The first element of such a
1 pair specifies options used with the GCC under test, and the second
1 element of the pair specifies options used with the alternate compiler.
1 Each test is compiled with each pair of options.
1 
1  'compat.exp' defines default pairs of compiler options.  These can be
1 overridden by defining the environment variable 'COMPAT_OPTIONS' as:
1 
1      COMPAT_OPTIONS="[list [list {TST1} {ALT1}]
1        ...[list {TSTN} {ALTN}]]"
1 
1  where TSTI and ALTI are lists of options, with TSTI used by the
1 compiler under test and ALTI used by the alternate compiler.  For
1 example, with '[list [list {-g -O0} {-O3}] [list {-fpic} {-fPIC -O2}]]',
1 the test is first built with '-g -O0' by the compiler under test and
1 with '-O3' by the alternate compiler.  The test is built a second time
1 using '-fpic' by the compiler under test and '-fPIC -O2' by the
1 alternate compiler.
1 
1  An alternate compiler is specified by defining an environment variable
1 to be the full pathname of an installed compiler; for C define
1 'ALT_CC_UNDER_TEST', and for C++ define 'ALT_CXX_UNDER_TEST'.  These
1 will be written to the 'site.exp' file used by DejaGnu.  The default is
1 to build each test with the compiler under test using the first of each
1 pair of compiler options from 'COMPAT_OPTIONS'.  When
1 'ALT_CC_UNDER_TEST' or 'ALT_CXX_UNDER_TEST' is 'same', each test is
1 built using the compiler under test but with combinations of the options
1 from 'COMPAT_OPTIONS'.
1 
1  To run only the C++ compatibility suite using the compiler under test
1 and another version of GCC using specific compiler options, do the
1 following from 'OBJDIR/gcc':
1 
1      rm site.exp
1      make -k \
1        ALT_CXX_UNDER_TEST=${alt_prefix}/bin/g++ \
1        COMPAT_OPTIONS="LISTS AS SHOWN ABOVE" \
1        check-c++ \
1        RUNTESTFLAGS="compat.exp"
1 
1  A test that fails when the source files are compiled with different
1 compilers, but passes when the files are compiled with the same
1 compiler, demonstrates incompatibility of the generated code or runtime
1 support.  A test that fails for the alternate compiler but passes for
1 the compiler under test probably tests for a bug that was fixed in the
1 compiler under test but is present in the alternate compiler.
1 
1  The binary compatibility tests support a small number of test framework
1 commands that appear within comments in a test file.
1 
1 'dg-require-*'
1      These commands can be used in 'TESTNAME_main.SUFFIX' to skip the
1      test if specific support is not available on the target.
1 
1 'dg-options'
1      The specified options are used for compiling this particular source
1      file, appended to the options from 'COMPAT_OPTIONS'.  When this
1      command appears in 'TESTNAME_main.SUFFIX' the options are also used
1      to link the test program.
1 
1 'dg-xfail-if'
1      This command can be used in a secondary source file to specify that
1      compilation is expected to fail for particular options on
1      particular targets.
1