gcc/testsuite/README.compat

   1 Compatibility test suites that use lib/compat.exp test interoperability
   2 of two compilers that follow the same ABI, or of multiple sets of
   3 compiler options that are not intended to affect binary compatibility.
   4 They do not test conformance to a formal ABI; they check that things are
   5 done consistently, not that they are done correctly.  They are meant to
   6 complement ABI test suites, not to replace them.
   7
   8 Each test in these suites splits up functionality into two source files
   9 that can be compiled with two different versions of GCC and with two
  10 sets of compiler options.
  11
  12   Override the default pairs of compiler options (from compat.exp) by
  13   defining the environment variable COMPAT_OPTIONS as:
  14   COMPAT_OPTIONS="[list [list {tst1} {alt1}]...[list {tstn} {altn}]]"
  15   where tsti and alti are lists of options, with "tsti" used by the
  16   compiler under test and "alti" used by the alternate compiler. The
  17   characters "[", "{", "}", and "]" are really in the string, as in
  18   "[list [list {-g} {-O3}] [list {-O3} {-g}]]".
  19
  20   To use an alternate compiler, define the environment variable for the
  21   language you're testing; e.g., for C++ define ALT_CXX_UNDER_TEST to be
  22   the full pathname of an installed compiler.  That will be written to
  23   the site.exp file used by DejaGNU.  The default is to build each test
  24   with the compiler under test using the first of each pair of compiler
  25   options from COMPAT_OPTIONS.  When ALT_CXX_UNDER_TEST is "same", each
  26   test is built using the compiler under test but with combinations of
  27   the options from COMPAT_OPTIONS.
  28
  29 A test that fails when the pieces are compiled with different compilers
  30 but passes when the pieces are compiled with the same compiler
  31 demonstrates incompatibility of the generated code or runtime support.
  32 A test that fails for the alternate compiler but passes for the compiler
  33 under test probably tests for a fix that is not present in the alternate
  34 compiler.
  35
  36 There's a lot more that can be done with these tests.
  37
  38   Increase the robustness of the existing tests:
  39
  40    -  recognize target triples in dg-options strings in test files
  41
  42    -  continue to split up tests that rely on language runtime support
  43       and add them to this set of tests
  44
  45    -  make sure they work for testing with a simulator
  46
  47    -  multilibs support?
  48
  49   Build test pieces into more combinations that will be likely to find
  50   unusual errors:
  51
  52    -  link using the alternate compiler; this requires support for
  53       LD_LIBRARY_PATH for the alternate compiler in the support for each
  54       language
  55
  56    -  build pieces of the test into shared libraries; this requires
  57       support for LD_LIBRARY_PATH for the alternate compiler, and
  58       knowledge about how to build a shared library for each target
  59
  60    -  build pieces of the test into static libraries; this requires
  61       knowledge about how to build a static library for each target
  62
  63   Continue to add tests to g++.dg/compat, based on existing tests for
  64   language runtime support and for test cases in PRs that didn't used to
  65   fit into the test suite.
  66
  67   Set up similar tests in libstdc++-v3/testsuite.
  68
  69   Set up similar tests for additional languages and libraries.
  70
  71 Janis Johnson, <janis187@us.ibm.com>
  72 October 2002