This is ../../gcc-3.4/gcc/doc/gccint.info, produced by makeinfo version
4.2 from ../../gcc-3.4/gcc/doc/gccint.texi.

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gccint: (gccint).            Internals of the GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the internals of the GNU compilers.

   Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

File: gccint.info,  Node: Front End,  Next: Back End,  Prev: Documentation,  Up: gcc Directory

Anatomy of a Language Front End
-------------------------------

   A front end for a language in GCC has the following parts:

   * A directory `LANGUAGE' under `gcc' containing source files for
     that front end.  *Note The Front End `LANGUAGE' Directory: Front
     End Directory, for details.

   * A mention of the language in the list of supported languages in
     `gcc/doc/install.texi'.

   * Details of contributors to that front end in
     `gcc/doc/contrib.texi'.  If the details are in that front end's
     own manual then there should be a link to that manual's list in
     `contrib.texi'.

   * Information about support for that language in
     `gcc/doc/frontends.texi'.

   * Information about standards for that language, and the front end's
     support for them, in `gcc/doc/standards.texi'.  This may be a link
     to such information in the front end's own manual.

   * Details of source file suffixes for that language and `-x LANG'
     options supported, in `gcc/doc/invoke.texi'.

   * Entries in `default_compilers' in `gcc.c' for source file suffixes
     for that language.

   * Preferably test suites, which may be under `gcc/testsuite' or
     runtime library directories.  FIXME: document somewhere how to
     write test suite harnesses.

   * Probably a runtime library for the language, outside the `gcc'
     directory.  FIXME: document this further.

   * Details of the directories of any runtime libraries in
     `gcc/doc/sourcebuild.texi'.

   If the front end is added to the official GCC CVS repository, the
following are also necessary:

   * At least one Bugzilla component for bugs in that front end and
     runtime libraries.  This category needs to be mentioned in
     `gcc/gccbug.in', as well as being added to the Bugzilla database.

   * Normally, one or more maintainers of that front end listed in
     `MAINTAINERS'.

   * Mentions on the GCC web site in `index.html' and `frontends.html',
     with any relevant links on `readings.html'.  (Front ends that are
     not an official part of GCC may also be listed on
     `frontends.html', with relevant links.)

   * A news item on `index.html', and possibly an announcement on the
     <gcc-announce@gcc.gnu.org> mailing list.

   * The front end's manuals should be mentioned in
     `maintainer-scripts/update_web_docs' (*note Texinfo Manuals::) and
     the online manuals should be linked to from
     `onlinedocs/index.html'.

   * Any old releases or CVS repositories of the front end, before its
     inclusion in GCC, should be made available on the GCC FTP site
     `ftp://gcc.gnu.org/pub/gcc/old-releases/'.

   * The release and snapshot script `maintainer-scripts/gcc_release'
     should be updated to generate appropriate tarballs for this front
     end.  The associated `maintainer-scripts/snapshot-README' and
     `maintainer-scripts/snapshot-index.html' files should be updated
     to list the tarballs and diffs for this front end.

   * If this front end includes its own version files that include the
     current date, `maintainer-scripts/update_version' should be
     updated accordingly.

   * `CVSROOT/modules' in the GCC CVS repository should be updated.

* Menu:

* Front End Directory::  The front end `LANGUAGE' directory.
* Front End Config::     The front end `config-lang.in' file.


File: gccint.info,  Node: Front End Directory,  Next: Front End Config,  Up: Front End

The Front End `LANGUAGE' Directory
..................................

   A front end `LANGUAGE' directory contains the source files of that
front end (but not of any runtime libraries, which should be outside
the `gcc' directory).  This includes documentation, and possibly some
subsidiary programs build alongside the front end.  Certain files are
special and other parts of the compiler depend on their names:

`config-lang.in'
     This file is required in all language subdirectories.  *Note The
     Front End `config-lang.in' File: Front End Config, for details of
     its contents

`Make-lang.in'
     This file is required in all language subdirectories.  It contains
     targets `LANG.HOOK' (where `LANG' is the setting of `language' in
     `config-lang.in') for the following values of `HOOK', and any
     other Makefile rules required to build those targets (which may if
     necessary use other Makefiles specified in `outputs' in
     `config-lang.in', although this is deprecated).

    `all.build'
    `all.cross'
    `start.encap'
    `rest.encap'
          FIXME: exactly what goes in each of these targets?

    `tags'
          Build an `etags' `TAGS' file in the language subdirectory in
          the source tree.

    `info'
          Build info documentation for the front end, in the source
          directory.  This target is only called by `make bootstrap' if
          a suitable version of `makeinfo' is available, so does not
          need to check for this, and should fail if an error occurs.

    `dvi'
          Build DVI documentation for the front end, in the build
          directory.  This should be done using `$(TEXI2DVI)', with
          appropriate `-I' arguments pointing to directories of
          included files.

    `generated-manpages'
          Build generated man pages for the front end from Texinfo
          manuals (*note Man Page Generation::), in the source
          directory.  This target is only called if the necessary tools
          are available, but should ignore errors so as not to stop the
          build if errors occur; man pages are optional and the tools
          involved may be installed in a broken way.

    `install-normal'
          FIXME: what is this target for?

    `install-common'
          Install everything that is part of the front end, apart from
          the compiler executables listed in `compilers' in
          `config-lang.in'.

    `install-info'
          Install info documentation for the front end, if it is
          present in the source directory.  (It may not be present if a
          suitable version of `makeinfo' was not installed.)  This
          target should run the command `install-info' to update the
          info directory, but should ignore errors when running that
          command.

    `install-man'
          Install man pages for the front end.  This target should
          ignore errors.

    `uninstall'
          Uninstall files installed by installing the compiler.  This is
          currently documented not to be supported, so the hook need
          not do anything.

    `mostlyclean'
    `clean'
    `distclean'
    `extraclean'
    `maintainer-clean'
          Except for `extraclean', the language parts of the standard
          GNU `*clean' targets. *Note Standard Targets for Users:
          (standards)Standard Targets, for details of the standard
          targets.  `extraclean' does `distclean' and also deletes
          anything likely to be found in the source directory that
          shouldn't be in the distribution.  For GCC,
          `maintainer-clean' should delete all generated files in the
          source directory that are not checked into CVS, but should
          not delete anything checked into CVS.

    `stage1'
    `stage2'
    `stage3'
    `stage4'
    `stageprofile'
    `stagefeedback'
          Move to the stage directory files not included in
          `stagestuff' in `config-lang.in' or otherwise moved by the
          main `Makefile'.

`lang.opt'
     This file registers the set of switches that the front end accepts
     on the command line, and their -help text.  The file format is
     documented in the file `c.opt'.  These files are processed by the
     script `opts.sh'.

`lang-specs.h'
     This file provides entries for `default_compilers' in `gcc.c'
     which override the default of giving an error that a compiler for
     that language is not installed.

`LANGUAGE-tree.def'
     This file, which need not exist, defines any language-specific tree
     codes.


File: gccint.info,  Node: Front End Config,  Prev: Front End Directory,  Up: Front End

The Front End `config-lang.in' File
...................................

   Each language subdirectory contains a `config-lang.in' file.  In
addition the main directory contains `c-config-lang.in', which contains
limited information for the C language.  This file is a shell script
that may define some variables describing the language:

`language'
     This definition must be present, and gives the name of the language
     for some purposes such as arguments to `--enable-languages'.

`lang_requires'
     If defined, this variable lists (space-separated) language front
     ends other than C that this front end requires to be enabled (with
     the names given being their `language' settings).  For example, the
     Java front end depends on the C++ front end, so sets
     `lang_requires=c++'.

`target_libs'
     If defined, this variable lists (space-separated) targets in the
     top level `Makefile' to build the runtime libraries for this
     language, such as `target-libobjc'.

`lang_dirs'
     If defined, this variable lists (space-separated) top level
     directories (parallel to `gcc'), apart from the runtime libraries,
     that should not be configured if this front end is not built.

`build_by_default'
     If defined to `no', this language front end is not built unless
     enabled in a `--enable-languages' argument.  Otherwise, front ends
     are built by default, subject to any special logic in
     `configure.in' (as is present to disable the Ada front end if the
     Ada compiler is not already installed).

`boot_language'
     If defined to `yes', this front end is built in stage 1 of the
     bootstrap.  This is only relevant to front ends written in their
     own languages.

`compilers'
     If defined, a space-separated list of compiler executables that
     will be run by the driver.  The names here will each end with
     `\$(exeext)'.

`stagestuff'
     If defined, a space-separated list of files that should be moved to
     the `stageN' directories in each stage of bootstrap.

`outputs'
     If defined, a space-separated list of files that should be
     generated by `configure' substituting values in them.  This
     mechanism can be used to create a file `LANGUAGE/Makefile' from
     `LANGUAGE/Makefile.in', but this is deprecated, building
     everything from the single `gcc/Makefile' is preferred.

`gtfiles'
     If defined, a space-separated list of files that should be scanned
     by gengtype.c to generate the garbage collection tables and
     routines for this language.  This excludes the files that are
     common to all front ends. *Note Type Information::.


File: gccint.info,  Node: Back End,  Prev: Front End,  Up: gcc Directory

Anatomy of a Target Back End
----------------------------

   A back end for a target architecture in GCC has the following parts:

   * A directory `MACHINE' under `gcc/config', containing a machine
     description `MACHINE.md' file (*note Machine Descriptions: Machine
     Desc.), header files `MACHINE.h' and `MACHINE-protos.h' and a
     source file `MACHINE.c' (*note Target Description Macros and
     Functions: Target Macros.), possibly a target Makefile fragment
     `t-MACHINE' (*note The Target Makefile Fragment: Target
     Fragment.), and maybe some other files.  The names of these files
     may be changed from the defaults given by explicit specifications
     in `config.gcc'.

   * If necessary, a file `MACHINE-modes.def' in the `MACHINE'
     directory, containing additional machine modes to represent
     condition codes.  *Note Condition Code::, for further details.

   * Entries in `config.gcc' (*note The `config.gcc' File: System
     Config.) for the systems with this target architecture.

   * Documentation in `gcc/doc/invoke.texi' for any command-line
     options supported by this target (*note Run-time Target
     Specification: Run-time Target.).  This means both entries in the
     summary table of options and details of the individual options.

   * Documentation in `gcc/doc/extend.texi' for any target-specific
     attributes supported (*note Defining target-specific uses of
     `__attribute__': Target Attributes.), including where the same
     attribute is already supported on some targets, which are
     enumerated in the manual.

   * Documentation in `gcc/doc/extend.texi' for any target-specific
     pragmas supported.

   * Documentation in `gcc/doc/extend.texi' of any target-specific
     built-in functions supported.

   * Documentation in `gcc/doc/md.texi' of any target-specific
     constraint letters (*note Constraints for Particular Machines:
     Machine Constraints.).

   * A note in `gcc/doc/contrib.texi' under the person or people who
     contributed the target support.

   * Entries in `gcc/doc/install.texi' for all target triplets
     supported with this target architecture, giving details of any
     special notes about installation for this target, or saying that
     there are no special notes if there are none.

   * Possibly other support outside the `gcc' directory for runtime
     libraries.  FIXME: reference docs for this.  The libstdc++ porting
     manual needs to be installed as info for this to work, or to be a
     chapter of this manual.

   If the back end is added to the official GCC CVS repository, the
following are also necessary:

   * An entry for the target architecture in `readings.html' on the GCC
     web site, with any relevant links.

   * A news item about the contribution of support for that target
     architecture, in `index.html' on the GCC web site.

   * Normally, one or more maintainers of that target listed in
     `MAINTAINERS'.  Some existing architectures may be unmaintained,
     but it would be unusual to add support for a target that does not
     have a maintainer when support is added.


File: gccint.info,  Node: Test Suites,  Prev: gcc Directory,  Up: Source Tree

Test Suites
===========

   GCC contains several test suites to help maintain compiler quality.
Most of the runtime libraries and language front ends in GCC have test
suites.  Currently only the C language test suites are documented here;
FIXME: document the others.

* Menu:

* Test Idioms::     Idioms used in test suite code.
* C Tests::         The C language test suites.
* 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.


File: gccint.info,  Node: Test Idioms,  Next: C Tests,  Up: Test Suites

Idioms Used in Test Suite Code
------------------------------

   In the `gcc.c-torture' test suites, test cases are commonly named
after the date on which they were added.  This allows people to tell at
a glance whether a test failure is because of a recently found bug that
has not yet been fixed, or whether it may be a regression.  In other
test suites, more descriptive names are used.  In general C test cases
have a trailing `-N.c', starting with `-1.c', in case other test cases
with similar names are added later.

   Test cases should use `abort ()' to indicate failure and `exit (0)'
for success; on some targets these may be redefined to indicate failure
and success in other ways.

   In the `gcc.dg' test suite, it is often necessary to test that an
error is indeed a hard error and not just a warning--for example, where
it is a constraint violation in the C standard, which must become an
error with `-pedantic-errors'.  The following idiom, where the first
line shown is line LINE of the file and the line that generates the
error, is used for this:

     /* { dg-bogus "warning" "warning in place of error" } */
     /* { dg-error "REGEXP" "MESSAGE" { target *-*-* } LINE } */

   It may be necessary to check that an expression is an integer
constant expression and has a certain value.  To check that `E' has
value `V', an idiom similar to the following is used:

     char x[((E) == (V) ? 1 : -1)];

   In `gcc.dg' tests, `__typeof__' is sometimes used to make assertions
about the types of expressions.  See, for example,
`gcc.dg/c99-condexpr-1.c'.  The more subtle uses depend on the exact
rules for the types of conditional expressions in the C standard; see,
for example, `gcc.dg/c99-intconst-1.c'.

   It is useful to be able to test that optimizations are being made
properly.  This cannot be done in all cases, but it can be done where
the optimization will lead to code being optimized away (for example,
where flow analysis or alias analysis should show that certain code
cannot be called) or to functions not being called because they have
been expanded as built-in functions.  Such tests go in
`gcc.c-torture/execute'.  Where code should be optimized away, a call
to a nonexistent function such as `link_failure ()' may be inserted; a
definition

     #ifndef __OPTIMIZE__
     void
     link_failure (void)
     {
       abort ();
     }
     #endif

will also be needed so that linking still succeeds when the test is run
without optimization.  When all calls to a built-in function should
have been optimized and no calls to the non-built-in version of the
function should remain, that function may be defined as `static' to
call `abort ()' (although redeclaring a function as static may not work
on all targets).

   All testcases must be portable.  Target-specific testcases must have
appropriate code to avoid causing failures on unsupported systems;
unfortunately, the mechanisms for this differ by directory.

   FIXME: discuss non-C test suites here.


File: gccint.info,  Node: C Tests,  Next: libgcj Tests,  Prev: Test Idioms,  Up: Test Suites

C Language Test Suites
----------------------

   GCC contains the following C language test suites, in the
`gcc/testsuite' directory:

`gcc.dg'
     This contains tests of particular features of the C compiler,
     using the more modern `dg' harness.  Correctness tests for various
     compiler features should go here if possible.

     Magic comments determine whether the file is preprocessed,
     compiled, linked or run.  In these tests, error and warning
     message texts are compared against expected texts or regular
     expressions given in comments.  These tests are run with the
     options `-ansi -pedantic' unless other options are given in the
     test.  Except as noted below they are not run with multiple
     optimization options.

`gcc.dg/compat'
     This subdirectory contains tests for binary compatibility using
     `compat.exp', which in turn uses the language-independent support
     (*note Support for testing binary compatibility: compat Testing.).

`gcc.dg/cpp'
     This subdirectory contains tests of the preprocessor.

`gcc.dg/debug'
     This subdirectory contains tests for debug formats.  Tests in this
     subdirectory are run for each debug format that the compiler
     supports.

`gcc.dg/format'
     This subdirectory contains tests of the `-Wformat' format
     checking.  Tests in this directory are run with and without
     `-DWIDE'.

`gcc.dg/noncompile'
     This subdirectory contains tests of code that should not compile
     and does not need any special compilation options.  They are run
     with multiple optimization options, since sometimes invalid code
     crashes the compiler with optimization.

`gcc.dg/special'
     FIXME: describe this.

`gcc.c-torture'
     This contains particular code fragments which have historically
     broken easily.  These tests are run with multiple optimization
     options, so tests for features which only break at some
     optimization levels belong here.  This also contains tests to
     check that certain optimizations occur.  It might be worthwhile to
     separate the correctness tests cleanly from the code quality
     tests, but it hasn't been done yet.

`gcc.c-torture/compat'
     FIXME: describe this.

     This directory should probably not be used for new tests.

`gcc.c-torture/compile'
     This test suite contains test cases that should compile, but do not
     need to link or run.  These test cases are compiled with several
     different combinations of optimization options.  All warnings are
     disabled for these test cases, so this directory is not suitable if
     you wish to test for the presence or absence of compiler warnings.
     While special options can be set, and tests disabled on specific
     platforms, by the use of `.x' files, mostly these test cases
     should not contain platform dependencies.  FIXME: discuss how
     defines such as `NO_LABEL_VALUES' and `STACK_SIZE' are used.

`gcc.c-torture/execute'
     This test suite contains test cases that should compile, link and
     run; otherwise the same comments as for `gcc.c-torture/compile'
     apply.

`gcc.c-torture/execute/ieee'
     This contains tests which are specific to IEEE floating point.

`gcc.c-torture/unsorted'
     FIXME: describe this.

     This directory should probably not be used for new tests.

`gcc.c-torture/misc-tests'
     This directory contains C tests that require special handling.
     Some of these tests have individual expect files, and others share
     special-purpose expect files:

    ``bprob*.c''
          Test `-fbranch-probabilities' using `bprob.exp', which in
          turn uses the generic, language-independent framework (*note
          Support for testing profile-directed optimizations: profopt
          Testing.).

    ``dg-*.c''
          Test the testsuite itself using `dg-test.exp'.

    ``gcov*.c''
          Test `gcov' output using `gcov.exp', which in turn uses the
          language-independent support (*note Support for testing gcov:
          gcov Testing.).

    ``i386-pf-*.c''
          Test i386-specific support for data prefetch using
          `i386-prefetch.exp'.

   FIXME: merge in `testsuite/README.gcc' and discuss the format of
test cases and magic comments more.


File: gccint.info,  Node: libgcj Tests,  Next: gcov Testing,  Prev: C Tests,  Up: Test Suites

The Java library test suites.
-----------------------------

   Runtime tests are executed via `make check' in the
`TARGET/libjava/testsuite' directory in the build tree.  Additional
runtime tests can be checked into this testsuite.

   Regression testing of the core packages in libgcj is also covered by
the Mauve test suite.  The Mauve Project develops tests for the Java
Class Libraries.  These tests are run as part of libgcj testing by
placing the Mauve tree within the libjava testsuite sources at
`libjava/testsuite/libjava.mauve/mauve', or by specifying the location
of that tree when invoking `make', as in `make MAUVEDIR=~/mauve check'.

   To detect regressions, a mechanism in `mauve.exp' compares the
failures for a test run against the list of expected failures in
`libjava/testsuite/libjava.mauve/xfails' from the source hierarchy.
Update this file when adding new failing tests to Mauve, or when fixing
bugs in libgcj that had caused Mauve test failures.

   The Jacks project provides a test suite for Java compilers that can
be used to test changes that affect the GCJ front end.  This test suite
is run as part of Java testing by placing the Jacks tree within the the
libjava testsuite sources at `libjava/testsuite/libjava.jacks/jacks'.

   We encourage developers to contribute test cases to Mauve and Jacks.


File: gccint.info,  Node: gcov Testing,  Next: profopt Testing,  Prev: libgcj Tests,  Up: Test Suites

Support for testing `gcov'
--------------------------

   Language-independent support for testing `gcov', and for checking
that branch profiling produces expected values, is provided by the
expect file `gcov.exp'.  `gcov' tests also rely on procedures in
`gcc.dg.exp' to compile and run the test program.  A typical `gcov'
test contains the following DejaGNU commands within comments:

     { dg-options "-fprofile-arcs -ftest-coverage" }
     { dg-do run { target native } }
     { dg-final { run-gcov sourcefile } }

   Checks of `gcov' output can include line counts, branch percentages,
and call return percentages.  All of these checks are requested via
commands that appear in comments in the test's source file.  Commands
to check line counts are processed by default.  Commands to check
branch percentages and call return percentages are processed if the
`run-gcov' command has arguments `branches' or `calls', respectively.
For example, the following specifies checking both, as well as passing
`-b' to `gcov':

     { dg-final { run-gcov branches calls { -b sourcefile } } }

   A line count command appears within a comment on the source line
that is expected to get the specified count and has the form
`count(CNT)'.  A test should only check line counts for lines that will
get the same count for any architecture.

   Commands to check branch percentages (`branch') and call return
percentages (`returns') are very similar to each other.  A beginning
command appears on or before the first of a range of lines that will
report the percentage, and the ending command follows that range of
lines.  The beginning command can include a list of percentages, all of
which are expected to be found within the range.  A range is terminated
by the next command of the same kind.  A command `branch(end)' or
`returns(end)' marks the end of a range without starting a new one.
For example:

     if (i > 10 && j > i && j < 20)  /* branch(27 50 75) */
                                     /* branch(end) */
       foo (i, j);

   For a call return percentage, the value specified is the percentage
of calls reported to return.  For a branch percentage, the value is
either the expected percentage or 100 minus that value, since the
direction of a branch can differ depending on the target or the
optimization level.

   Not all branches and calls need to be checked.  A test should not
check for branches that might be optimized away or replaced with
predicated instructions.  Don't check for calls inserted by the
compiler or ones that might be inlined or optimized away.

   A single test can check for combinations of line counts, branch
percentages, and call return percentages.  The command to check a line
count must appear on the line that will report that count, but commands
to check branch percentages and call return percentages can bracket the
lines that report them.


File: gccint.info,  Node: profopt Testing,  Next: compat Testing,  Prev: gcov Testing,  Up: Test Suites

Support for testing profile-directed optimizations
--------------------------------------------------

   The file `profopt.exp' provides language-independent support for
checking correct execution of a test built with profile-directed
optimization.  This testing requires that a test program be built and
executed twice.  The first time it is compiled to generate profile
data, and the second time it is compiled to use the data that was
generated during the first execution.  The second execution is to
verify that the test produces the expected results.

   To check that the optimization actually generated better code, a
test can be built and run a third time with normal optimizations to
verify that the performance is better with the profile-directed
optimizations.  `profopt.exp' has the beginnings of this kind of
support.

   `profopt.exp' provides generic support for profile-directed
optimizations.  Each set of tests that uses it provides information
about a specific optimization:

`tool'
     tool being tested, e.g., gcc

`profile_option'
     options used to generate profile data

`feedback_option'
     options used to optimize using that profile data

`prof_ext'
     suffix of profile data files

`PROFOPT_OPTIONS'
     list of options with which to run each test, similar to the lists
     for torture tests


File: gccint.info,  Node: compat Testing,  Prev: profopt Testing,  Up: Test Suites

Support for testing binary compatibility
----------------------------------------

   The 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 should not affect binary compatibility.  It is intended to
be used for test suites that complement ABI test suites.

   A test supported by this framework has three parts, each in a
separate source file: a main program and two pieces that interact with
each other to split up the functionality being tested.

`TESTNAME_main.SUFFIX'
     Contains the main program, which calls a function in file
     `TESTNAME_x.SUFFIX'.

`TESTNAME_x.SUFFIX'
     Contains at least one call to a function in `TESTNAME_y.SUFFIX'.

`TESTNAME_y.SUFFIX'
     Shares data with, or gets arguments from, `TESTNAME_x.SUFFIX'.

   Within each test, the main program and one functional 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 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.

   `compat.exp' defines default pairs of compiler options.  These can
be overridden by defining the environment variable `COMPAT_OPTIONS' as:

     COMPAT_OPTIONS="[list [list {TST1} {ALT1}]
       ...[list {TSTN} {ALTN}]]"

   where TSTI and ALTI are lists of options, with TSTI used by the
compiler under test and ALTI used by the alternate compiler.  For
example, with `[list [list {-g -O0} {-O3}] [list {-fpic} {-fPIC -O2}]]',
the test is first built with `-g -O0' by the compiler under test and
with `-O3' by the alternate compiler.  The test is built a second time
using `-fpic' by the compiler under test and `-fPIC -O2' by the
alternate compiler.

   An alternate compiler is specified by defining an environment
variable; for C++ define `ALT_CXX_UNDER_TEST' to be the full pathname
of an installed compiler.  That will be written to the `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
`COMPAT_OPTIONS'.  When `ALT_CXX_UNDER_TEST' is `same', each test is
built using the compiler under test but with combinations of the
options from `COMPAT_OPTIONS'.

   To run only the C++ compatibility suite using the compiler under test
and another version of GCC using specific compiler options, do the
following from `OBJDIR/gcc':

     rm site.exp
     make -k \
       ALT_CXX_UNDER_TEST=${alt_prefix}/bin/g++ \
       COMPAT_OPTIONS="lists as shown above" \
       check-c++ \
       RUNTESTFLAGS="compat.exp"

   A test that fails when the source files are compiled with different
compilers, but passes when the files 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 bug that was fixed in the
compiler under test but is present in the alternate compiler.

