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