This is
/es/build/frv-050408/1/frv550-uclinux/X-tools-build/gcc/doc/gccint.info,
produced by makeinfo version 4.0 from
/es/build/frv-050408/1/frv550-uclinux/sources/tools-src/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: Headers,  Next: Documentation,  Prev: Library Files,  Up: gcc Directory

Headers Installed by GCC
------------------------

   In general, GCC expects the system C library to provide most of the
headers to be used with it.  However, GCC will fix those headers if
necessary to make them work with GCC, and will install some headers
required of freestanding implementations.  These headers are installed
in `LIBSUBDIR/include'.  Headers for non-C runtime libraries are also
installed by GCC; these are not documented here.  (FIXME: document them
somewhere.)

   Several of the headers GCC installs are in the `ginclude' directory.
These headers, `iso646.h', `stdarg.h', `stdbool.h', and `stddef.h',
are installed in `LIBSUBDIR/include', unless the target Makefile
fragment (*note Target Fragment::) overrides this by setting `USER_H'.

   In addition to these headers and those generated by fixing system
headers to work with GCC, some other headers may also be installed in
`LIBSUBDIR/include'.  `config.gcc' may set `extra_headers'; this
specifies additional headers under `config' to be installed on some
systems.

   GCC installs its own version of `<float.h>', from `ginclude/float.h'.
This is done to cope with command-line options that change the
representation of floating point numbers.

   GCC also installs its own version of `<limits.h>'; this is generated
from `glimits.h', together with `limitx.h' and `limity.h' if the system
also has its own version of `<limits.h>'.  (GCC provides its own header
because it is required of ISO C freestanding implementations, but needs
to include the system header from its own header as well because other
standards such as POSIX specify additional values to be defined in
`<limits.h>'.)  The system's `<limits.h>' header is used via
`LIBSUBDIR/include/syslimits.h', which is copied from `gsyslimits.h' if
it does not need fixing to work with GCC; if it needs fixing,
`syslimits.h' is the fixed copy.


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

Building Documentation
----------------------

   The main GCC documentation is in the form of manuals in Texinfo
format.  These are installed in Info format, and DVI versions may be
generated by `make dvi'.  In addition, some man pages are generated
from the Texinfo manuals, there are some other text files with
miscellaneous documentation, and runtime libraries have their own
documentation outside the `gcc' directory.  FIXME: document the
documentation for runtime libraries somewhere.

* Menu:

* Texinfo Manuals::      GCC manuals in Texinfo format.
* Man Page Generation::  Generating man pages from Texinfo manuals.
* Miscellaneous Docs::   Miscellaneous text files with documentation.


File: gccint.info,  Node: Texinfo Manuals,  Next: Man Page Generation,  Up: Documentation

Texinfo Manuals
...............

   The manuals for GCC as a whole, and the C and C++ front ends, are in
files `doc/*.texi'.  Other front ends have their own manuals in files
`LANGUAGE/*.texi'.  Common files `doc/include/*.texi' are provided
which may be included in multiple manuals; the following files are in
`doc/include':

`fdl.texi'
     The GNU Free Documentation License.

`funding.texi'
     The section "Funding Free Software".

`gcc-common.texi'
     Common definitions for manuals.

`gpl.texi'
     The GNU General Public License.

`texinfo.tex'
     A copy of `texinfo.tex' known to work with the GCC manuals.

   DVI formatted manuals are generated by `make dvi', which uses
`texi2dvi' (via the Makefile macro `$(TEXI2DVI)').  Info manuals are
generated by `make info' (which is run as part of a bootstrap); this
generates the manuals in the source directory, using `makeinfo' via the
Makefile macro `$(MAKEINFO)', and they are included in release
distributions.

   Manuals are also provided on the GCC web site, in both HTML and
PostScript forms.  This is done via the script
`maintainer-scripts/update_web_docs'.  Each manual to be provided
online must be listed in the definition of `MANUALS' in that file; a
file `NAME.texi' must only appear once in the source tree, and the
output manual must have the same name as the source file.  (However,
other Texinfo files, included in manuals but not themselves the root
files of manuals, may have names that appear more than once in the
source tree.)  The manual file `NAME.texi' should only include other
files in its own directory or in `doc/include'.  HTML manuals will be
generated by `makeinfo --html' and PostScript manuals by `texi2dvi' and
`dvips'.  All Texinfo files that are parts of manuals must be checked
into CVS, even if they are generated files, for the generation of
online manuals to work.

   The installation manual, `doc/install.texi', is also provided on the
GCC web site.  The HTML version is generated by the script
`doc/install.texi2html'.


File: gccint.info,  Node: Man Page Generation,  Next: Miscellaneous Docs,  Prev: Texinfo Manuals,  Up: Documentation

Man Page Generation
...................

   Because of user demand, in addition to full Texinfo manuals, man
pages are provided which contain extracts from those manuals.  These man
pages are generated from the Texinfo manuals using
`contrib/texi2pod.pl' and `pod2man'.  (The man page for `g++',
`cp/g++.1', just contains a `.so' reference to `gcc.1', but all the
other man pages are generated from Texinfo manuals.)

   Because many systems may not have the necessary tools installed to
generate the man pages, they are only generated if the `configure'
script detects that recent enough tools are installed, and the
Makefiles allow generating man pages to fail without aborting the
build.  Man pages are also included in release distributions.  They are
generated in the source directory.

   Magic comments in Texinfo files starting `@c man' control what parts
of a Texinfo file go into a man page.  Only a subset of Texinfo is
supported by `texi2pod.pl', and it may be necessary to add support for
more Texinfo features to this script when generating new man pages.  To
improve the man page output, some special Texinfo macros are provided
in `doc/include/gcc-common.texi' which `texi2pod.pl' understands:

`@gcctabopt'
     Use in the form `@table @gcctabopt' for tables of options, where
     for printed output the effect of `@code' is better than that of
     `@option' but for man page output a different effect is wanted.

`@gccoptlist'
     Use for summary lists of options in manuals.

`@gol'
     Use at the end of each line inside `@gccoptlist'.  This is
     necessary to avoid problems with differences in how the
     `@gccoptlist' macro is handled by different Texinfo formatters.

   FIXME: describe the `texi2pod.pl' input language and magic comments
in more detail.


File: gccint.info,  Node: Miscellaneous Docs,  Prev: Man Page Generation,  Up: Documentation

Miscellaneous Documentation
...........................

   In addition to the formal documentation that is installed by GCC,
there are several other text files with miscellaneous documentation:

`ABOUT-GCC-NLS'
     Notes on GCC's Native Language Support.  FIXME: this should be
     part of this manual rather than a separate file.

`ABOUT-NLS'
     Notes on the Free Translation Project.

`COPYING'
     The GNU General Public License.

`COPYING.LIB'
     The GNU Lesser General Public License.

`*ChangeLog*'
`*/ChangeLog*'
     Change log files for various parts of GCC.

`LANGUAGES'
     Details of a few changes to the GCC front-end interface.  FIXME:
     the information in this file should be part of general
     documentation of the front-end interface in this manual.

`ONEWS'
     Information about new features in old versions of GCC.  (For recent
     versions, the information is on the GCC web site.)

`README.Portability'
     Information about portability issues when writing code in GCC.
     FIXME: why isn't this part of this manual or of the GCC Coding
     Conventions?

`SERVICE'
     A pointer to the GNU Service Directory.

   FIXME: document such files in subdirectories, at least `config',
`cp', `objc', `testsuite'.


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).  Some hooks are
     defined by using a double-colon rule for `HOOK', rather than by
     using a target of form `LANG.HOOK'.  These hooks are called
     "double-colon hooks" below.

    `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.
          This hook is a double-colon hook.

    `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.  This hook is a double-colon hook.

    `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.  This hook is a
          double-colon hook.

    `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.  This target should have
          dependencies on info files that should be installed.  This
          hook is a double-colon hook.

    `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.
* Ada Tests::       The Ada language test suites.
* 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: Ada 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: Ada Tests,  Next: C Tests,  Prev: Test Idioms,  Up: Test Suites

Ada Language Test Suites
------------------------

   The Ada test suite includes executable tests from the ACATS 2.5 test
suite, publicly available at `http://www.adaic.org/compilers/acats/2.5'

   These tests are integrated in the GCC test suite in the
`gcc/testsuite/ada/acats' directory, and enabled automatically when
running `make check', assuming the Ada language has been enabled when
configuring GCC.

   You can also run the Ada test suite independently, using `make
check-ada', or run a subset of the tests by specifying which chapter to
run, e.g:

     $ make check-ada CHAPTERS="c3 c9"

   The tests are organized by directory, each directory corresponding to
a chapter of the Ada Reference Manual. So for example, c9 corresponds
to chapter 9, which deals with tasking features of the language.

   There is also an extra chapter called `gcc' containing a template for
creating new executable tests.

   The tests are run using two 'sh' scripts: run_acats and run_all.sh
To run the tests using a simulator or a cross target, see the small
customization section at the top of run_all.sh

   These tests are run using the build tree: they can be run without
doing a `make install'.


File: gccint.info,  Node: C Tests,  Next: libgcj Tests,  Prev: Ada Tests,  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.

