Initial checkin of unmodified gcc-5666.3.tar.gz

This is the source to build gcc-4.2 for MacOSX

   gcc version 4.2.1 (Apple Inc. build 5666) (dot 3)

http://opensource.apple.com/tarballs/gcc/gcc-5666.3.tar.gz

Change-Id: I69540223f018e9d07f861fca04bd3833fc138f8b

1 files changed, 1524 insertions, 0 deletions

diff --git a/gcc-4.2.1-5666.3/gcc/doc/sourcebuild.texi b/gcc-4.2.1-5666.3/gcc/doc/sourcebuild.texi
new file mode 100644
index 000000000..2db9d10f7
--- /dev/null
+++ b/gcc-4.2.1-5666.3/gcc/doc/sourcebuild.texi
@@ -0,0 +1,1524 @@
+@c Copyright (C) 2002, 2003, 2004, 2005, 2007 Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@node Source Tree
+@chapter Source Tree Structure and Build System
+
+This chapter describes the structure of the GCC source tree, and how
+GCC is built.  The user documentation for building and installing GCC
+is in a separate manual (@uref{http://gcc.gnu.org/install/}), with
+which it is presumed that you are familiar.
+
+@menu
+* Configure Terms:: Configuration terminology and history.
+* Top Level::       The top level source directory.
+* gcc Directory::   The @file{gcc} subdirectory.
+* Testsuites::      The GCC testsuites.
+@end menu
+
+@include configterms.texi
+
+@node Top Level
+@section Top Level Source Directory
+
+The top level source directory in a GCC distribution contains several
+files and directories that are shared with other software
+distributions such as that of GNU Binutils.  It also contains several
+subdirectories that contain parts of GCC and its runtime libraries:
+
+@table @file
+@item boehm-gc
+The Boehm conservative garbage collector, used as part of the Java
+runtime library.
+
+@item contrib
+Contributed scripts that may be found useful in conjunction with GCC@.
+One of these, @file{contrib/texi2pod.pl}, is used to generate man
+pages from Texinfo manuals as part of the GCC build process.
+
+@item fastjar
+An implementation of the @command{jar} command, used with the Java
+front end.
+
+@item gcc
+The main sources of GCC itself (except for runtime libraries),
+including optimizers, support for different target architectures,
+language front ends, and testsuites.  @xref{gcc Directory, , The
+@file{gcc} Subdirectory}, for details.
+
+@item include
+Headers for the @code{libiberty} library.
+
+@item libada
+The Ada runtime library.
+
+@item libcpp
+The C preprocessor library.
+
+@item libgfortran
+The Fortran runtime library.
+
+@item libffi
+The @code{libffi} library, used as part of the Java runtime library.
+
+@item libiberty
+The @code{libiberty} library, used for portability and for some
+generally useful data structures and algorithms.  @xref{Top, ,
+Introduction, libiberty, @sc{gnu} libiberty}, for more information
+about this library.
+
+@item libjava
+The Java runtime library.
+
+@item libmudflap
+The @code{libmudflap} library, used for instrumenting pointer and array
+dereferencing operations.
+
+@item libobjc
+The Objective-C and Objective-C++ runtime library.
+
+@item libstdc++-v3
+The C++ runtime library.
+
+@item maintainer-scripts
+Scripts used by the @code{gccadmin} account on @code{gcc.gnu.org}.
+
+@item zlib
+The @code{zlib} compression library, used by the Java front end and as
+part of the Java runtime library.
+@end table
+
+The build system in the top level directory, including how recursion
+into subdirectories works and how building runtime libraries for
+multilibs is handled, is documented in a separate manual, included
+with GNU Binutils.  @xref{Top, , GNU configure and build system,
+configure, The GNU configure and build system}, for details.
+
+@node gcc Directory
+@section The @file{gcc} Subdirectory
+
+The @file{gcc} directory contains many files that are part of the C
+sources of GCC, other files used as part of the configuration and
+build process, and subdirectories including documentation and a
+testsuite.  The files that are sources of GCC are documented in a
+separate chapter.  @xref{Passes, , Passes and Files of the Compiler}.
+
+@menu
+* Subdirectories:: Subdirectories of @file{gcc}.
+* Configuration::  The configuration process, and the files it uses.
+* Build::          The build system in the @file{gcc} directory.
+* Makefile::       Targets in @file{gcc/Makefile}.
+* Library Files::  Library source files and headers under @file{gcc/}.
+* Headers::        Headers installed by GCC.
+* Documentation::  Building documentation in GCC.
+* Front End::      Anatomy of a language front end.
+* Back End::       Anatomy of a target back end.
+@end menu
+
+@node Subdirectories
+@subsection Subdirectories of @file{gcc}
+
+The @file{gcc} directory contains the following subdirectories:
+
+@table @file
+@item @var{language}
+Subdirectories for various languages.  Directories containing a file
+@file{config-lang.in} are language subdirectories.  The contents of
+the subdirectories @file{cp} (for C++), @file{objc} (for Objective-C)
+and @file{objcp} (for Objective-C++) are documented in this manual
+(@pxref{Passes, , Passes and Files of the Compiler}); those for other
+languages are not.  @xref{Front End, , Anatomy of a Language Front End},
+for details of the files in these directories.
+
+@item config
+Configuration files for supported architectures and operating
+systems.  @xref{Back End, , Anatomy of a Target Back End}, for
+details of the files in this directory.
+
+@item doc
+Texinfo documentation for GCC, together with automatically generated
+man pages and support for converting the installation manual to
+HTML@.  @xref{Documentation}.
+
+@item fixinc
+The support for fixing system headers to work with GCC@.  See
+@file{fixinc/README} for more information.  The headers fixed by this
+mechanism are installed in @file{@var{libsubdir}/include}.  Along with
+those headers, @file{README-fixinc} is also installed, as
+@file{@var{libsubdir}/include/README}.
+
+@item ginclude
+System headers installed by GCC, mainly those required by the C
+standard of freestanding implementations.  @xref{Headers, , Headers
+Installed by GCC}, for details of when these and other headers are
+installed.
+
+@item intl
+GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
+include it in libc.  Properly, this directory should be at top level,
+parallel to the @file{gcc} directory.
+
+@item po
+Message catalogs with translations of messages produced by GCC into
+various languages, @file{@var{language}.po}.  This directory also
+contains @file{gcc.pot}, the template for these message catalogues,
+@file{exgettext}, a wrapper around @command{gettext} to extract the
+messages from the GCC sources and create @file{gcc.pot}, which is run
+by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
+which messages should not be extracted.
+
+@item testsuite
+The GCC testsuites (except for those for runtime libraries).
+@xref{Testsuites}.
+@end table
+
+@node Configuration
+@subsection Configuration in the @file{gcc} Directory
+
+The @file{gcc} directory is configured with an Autoconf-generated
+script @file{configure}.  The @file{configure} script is generated
+from @file{configure.ac} and @file{aclocal.m4}.  From the files
+@file{configure.ac} and @file{acconfig.h}, Autoheader generates the
+file @file{config.in}.  The file @file{cstamp-h.in} is used as a
+timestamp.
+
+@menu
+* Config Fragments::     Scripts used by @file{configure}.
+* System Config::        The @file{config.build}, @file{config.host}, and
+                         @file{config.gcc} files.
+* Configuration Files::  Files created by running @file{configure}.
+@end menu
+
+@node Config Fragments
+@subsubsection Scripts Used by @file{configure}
+
+@file{configure} uses some other scripts to help in its work:
+
+@itemize @bullet
+@item The standard GNU @file{config.sub} and @file{config.guess}
+files, kept in the top level directory, are used.  FIXME: when is the
+@file{config.guess} file in the @file{gcc} directory (that just calls
+the top level one) used?
+
+@item The file @file{config.gcc} is used to handle configuration
+specific to the particular target machine.  The file
+@file{config.build} is used to handle configuration specific to the
+particular build machine.  The file @file{config.host} is used to handle
+configuration specific to the particular host machine.  (In general,
+these should only be used for features that cannot reasonably be tested in
+Autoconf feature tests.)
+@xref{System Config, , The @file{config.build}; @file{config.host};
+and @file{config.gcc} Files}, for details of the contents of these files.
+
+@item Each language subdirectory has a file
+@file{@var{language}/config-lang.in} that is used for
+front-end-specific configuration.  @xref{Front End Config, , The Front
+End @file{config-lang.in} File}, for details of this file.
+
+@item A helper script @file{configure.frag} is used as part of
+creating the output of @file{configure}.
+@end itemize
+
+@node System Config
+@subsubsection The @file{config.build}; @file{config.host}; and @file{config.gcc} Files
+
+The @file{config.build} file contains specific rules for particular systems
+which GCC is built on.  This should be used as rarely as possible, as the
+behavior of the build system can always be detected by autoconf.
+
+The @file{config.host} file contains specific rules for particular systems
+which GCC will run on.  This is rarely needed.
+
+The @file{config.gcc} file contains specific rules for particular systems
+which GCC will generate code for.  This is usually needed.
+
+Each file has a list of the shell variables it sets, with descriptions, at the
+top of the file.
+
+FIXME: document the contents of these files, and what variables should
+be set to control build, host and target configuration.
+
+@include configfiles.texi
+
+@node Build
+@subsection Build System in the @file{gcc} Directory
+
+FIXME: describe the build system, including what is built in what
+stages.  Also list the various source files that are used in the build
+process but aren't source files of GCC itself and so aren't documented
+below (@pxref{Passes}).
+
+@include makefile.texi
+
+@node Library Files
+@subsection Library Source Files and Headers under the @file{gcc} Directory
+
+FIXME: list here, with explanation, all the C source files and headers
+under the @file{gcc} directory that aren't built into the GCC
+executable but rather are part of runtime libraries and object files,
+such as @file{crtstuff.c} and @file{unwind-dw2.c}.  @xref{Headers, ,
+Headers Installed by GCC}, for more information about the
+@file{ginclude} directory.
+
+@node Headers
+@subsection 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 @file{@var{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 @file{ginclude}
+directory.  These headers, @file{iso646.h},
+@file{stdarg.h}, @file{stdbool.h}, and @file{stddef.h},
+are installed in @file{@var{libsubdir}/include},
+unless the target Makefile fragment (@pxref{Target Fragment})
+overrides this by setting @code{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
+@file{@var{libsubdir}/include}.  @file{config.gcc} may set
+@code{extra_headers}; this specifies additional headers under
+@file{config} to be installed on some systems.
+
+GCC installs its own version of @code{<float.h>}, from @file{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 @code{<limits.h>}; this is generated
+from @file{glimits.h}, together with @file{limitx.h} and
+@file{limity.h} if the system also has its own version of
+@code{<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
+@code{<limits.h>}.)  The system's @code{<limits.h>} header is used via
+@file{@var{libsubdir}/include/syslimits.h}, which is copied from
+@file{gsyslimits.h} if it does not need fixing to work with GCC; if it
+needs fixing, @file{syslimits.h} is the fixed copy.
+
+@node Documentation
+@subsection Building Documentation
+
+The main GCC documentation is in the form of manuals in Texinfo
+format.  These are installed in Info format; DVI versions may be
+generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
+HTML versions by @command{make html}.  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 @file{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.
+@end menu
+
+@node Texinfo Manuals
+@subsubsection Texinfo Manuals
+
+The manuals for GCC as a whole, and the C and C++ front ends, are in
+files @file{doc/*.texi}.  Other front ends have their own manuals in
+files @file{@var{language}/*.texi}.  Common files
+@file{doc/include/*.texi} are provided which may be included in
+multiple manuals; the following files are in @file{doc/include}:
+
+@table @file
+@item fdl.texi
+The GNU Free Documentation License.
+@item funding.texi
+The section ``Funding Free Software''.
+@item gcc-common.texi
+Common definitions for manuals.
+@item gpl.texi
+The GNU General Public License.
+@item texinfo.tex
+A copy of @file{texinfo.tex} known to work with the GCC manuals.
+@end table
+
+DVI-formatted manuals are generated by @samp{make dvi}, which uses
+@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).  
+PDF-formatted manuals are generated by @samp{make pdf}, which uses
+@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}).  HTML
+formatted manuals are generated by @command{make html}.  Info
+manuals are generated by @samp{make info} (which is run as part of
+a bootstrap); this generates the manuals in the source directory,
+using @command{makeinfo} via the Makefile macro @code{$(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
+@file{maintainer-scripts/update_web_docs}.  Each manual to be
+provided online must be listed in the definition of @code{MANUALS} in
+that file; a file @file{@var{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
+@file{@var{name}.texi} should only include other files in its own
+directory or in @file{doc/include}.  HTML manuals will be generated by
+@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
+and @command{dvips}, and PDF manuals by @command{texi2pdf}.
+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, @file{doc/install.texi}, is also provided on
+the GCC web site.  The HTML version is generated by the script
+@file{doc/install.texi2html}.
+
+@node Man Page Generation
+@subsubsection 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
+@file{contrib/texi2pod.pl} and @command{pod2man}.  (The man page for
+@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
+to @file{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
+@file{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 @samp{@@c man} control what
+parts of a Texinfo file go into a man page.  Only a subset of Texinfo
+is supported by @file{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 @file{doc/include/gcc-common.texi} which
+@file{texi2pod.pl} understands:
+
+@table @code
+@item @@gcctabopt
+Use in the form @samp{@@table @@gcctabopt} for tables of options,
+where for printed output the effect of @samp{@@code} is better than
+that of @samp{@@option} but for man page output a different effect is
+wanted.
+@item @@gccoptlist
+Use for summary lists of options in manuals.
+@item @@gol
+Use at the end of each line inside @samp{@@gccoptlist}.  This is
+necessary to avoid problems with differences in how the
+@samp{@@gccoptlist} macro is handled by different Texinfo formatters.
+@end table
+
+FIXME: describe the @file{texi2pod.pl} input language and magic
+comments in more detail.
+
+@node Miscellaneous Docs
+@subsubsection Miscellaneous Documentation
+
+In addition to the formal documentation that is installed by GCC,
+there are several other text files with miscellaneous documentation:
+
+@table @file
+@item ABOUT-GCC-NLS
+Notes on GCC's Native Language Support.  FIXME: this should be part of
+this manual rather than a separate file.
+@item ABOUT-NLS
+Notes on the Free Translation Project.
+@item COPYING
+The GNU General Public License.
+@item COPYING.LIB
+The GNU Lesser General Public License.
+@item *ChangeLog*
+@itemx */ChangeLog*
+Change log files for various parts of GCC@.
+@item 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.
+@item ONEWS
+Information about new features in old versions of GCC@.  (For recent
+versions, the information is on the GCC web site.)
+@item 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?
+@item SERVICE
+A pointer to the GNU Service Directory.
+@end table
+
+FIXME: document such files in subdirectories, at least @file{config},
+@file{cp}, @file{objc}, @file{testsuite}.
+
+@node Front End
+@subsection Anatomy of a Language Front End
+
+A front end for a language in GCC has the following parts:
+
+@itemize @bullet
+@item
+A directory @file{@var{language}} under @file{gcc} containing source
+files for that front end.  @xref{Front End Directory, , The Front End
+@file{@var{language}} Directory}, for details.
+@item
+A mention of the language in the list of supported languages in
+@file{gcc/doc/install.texi}.
+@item
+A mention of the name under which the language's runtime library is
+recognized by @option{--enable-shared=@var{package}} in the
+documentation of that option in @file{gcc/doc/install.texi}.
+@item
+A mention of any special prerequisites for building the front end in
+the documentation of prerequisites in @file{gcc/doc/install.texi}.
+@item
+Details of contributors to that front end in
+@file{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
+@file{contrib.texi}.
+@item
+Information about support for that language in
+@file{gcc/doc/frontends.texi}.
+@item
+Information about standards for that language, and the front end's
+support for them, in @file{gcc/doc/standards.texi}.  This may be a
+link to such information in the front end's own manual.
+@item
+Details of source file suffixes for that language and @option{-x
+@var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
+@item
+Entries in @code{default_compilers} in @file{gcc.c} for source file
+suffixes for that language.
+@item
+Preferably testsuites, which may be under @file{gcc/testsuite} or
+runtime library directories.  FIXME: document somewhere how to write
+testsuite harnesses.
+@item
+Probably a runtime library for the language, outside the @file{gcc}
+directory.  FIXME: document this further.
+@item
+Details of the directories of any runtime libraries in
+@file{gcc/doc/sourcebuild.texi}.
+@end itemize
+
+If the front end is added to the official GCC CVS repository, the
+following are also necessary:
+
+@itemize @bullet
+@item
+At least one Bugzilla component for bugs in that front end and runtime
+libraries.  This category needs to be mentioned in
+@file{gcc/gccbug.in}, as well as being added to the Bugzilla database.
+@item
+Normally, one or more maintainers of that front end listed in
+@file{MAINTAINERS}.
+@item
+Mentions on the GCC web site in @file{index.html} and
+@file{frontends.html}, with any relevant links on
+@file{readings.html}.  (Front ends that are not an official part of
+GCC may also be listed on @file{frontends.html}, with relevant links.)
+@item
+A news item on @file{index.html}, and possibly an announcement on the
+@email{gcc-announce@@gcc.gnu.org} mailing list.
+@item
+The front end's manuals should be mentioned in
+@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
+and the online manuals should be linked to from
+@file{onlinedocs/index.html}.
+@item
+Any old releases or CVS repositories of the front end, before its
+inclusion in GCC, should be made available on the GCC FTP site
+@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
+@item
+The release and snapshot script @file{maintainer-scripts/gcc_release}
+should be updated to generate appropriate tarballs for this front end.
+The associated @file{maintainer-scripts/snapshot-README} and
+@file{maintainer-scripts/snapshot-index.html} files should be updated
+to list the tarballs and diffs for this front end.
+@item
+If this front end includes its own version files that include the
+current date, @file{maintainer-scripts/update_version} should be
+updated accordingly.
+@item
+@file{CVSROOT/modules} in the GCC CVS repository should be updated.
+@end itemize
+
+@menu
+* Front End Directory::  The front end @file{@var{language}} directory.
+* Front End Config::     The front end @file{config-lang.in} file.
+@end menu
+
+@node Front End Directory
+@subsubsection The Front End @file{@var{language}} Directory
+
+A front end @file{@var{language}} directory contains the source files
+of that front end (but not of any runtime libraries, which should be
+outside the @file{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:
+
+@table @file
+@item config-lang.in
+This file is required in all language subdirectories.  @xref{Front End
+Config, , The Front End @file{config-lang.in} File}, for details of
+its contents
+@item Make-lang.in
+This file is required in all language subdirectories.  It contains
+targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
+setting of @code{language} in @file{config-lang.in}) for the following
+values of @code{@var{hook}}, and any other Makefile rules required to
+build those targets (which may if necessary use other Makefiles
+specified in @code{outputs} in @file{config-lang.in}, although this is
+deprecated).  It also adds any testsuite targets that can use the
+standard rule in @file{gcc/Makefile.in} to the variable
+@code{lang_checks}.
+
+@table @code
+@itemx all.cross
+@itemx start.encap
+@itemx rest.encap
+FIXME: exactly what goes in each of these targets?
+@item tags
+Build an @command{etags} @file{TAGS} file in the language subdirectory
+in the source tree.
+@item info
+Build info documentation for the front end, in the build directory.
+This target is only called by @samp{make bootstrap} if a suitable
+version of @command{makeinfo} is available, so does not need to check
+for this, and should fail if an error occurs.
+@item dvi
+Build DVI documentation for the front end, in the build directory.
+This should be done using @code{$(TEXI2DVI)}, with appropriate
+@option{-I} arguments pointing to directories of included files.
+@item pdf
+Build PDF documentation for the front end, in the build directory.
+This should be done using @code{$(TEXI2PDF)}, with appropriate
+@option{-I} arguments pointing to directories of included files.
+@item html
+Build HTML documentation for the front end, in the build directory.
+@item man
+Build generated man pages for the front end from Texinfo manuals
+(@pxref{Man Page Generation}), in the build 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.
+@item install-common
+Install everything that is part of the front end, apart from the
+compiler executables listed in @code{compilers} in
+@file{config-lang.in}.
+@item 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.
+@item install-man
+Install man pages for the front end.  This target should ignore
+errors.
+@item srcextra
+Copies its dependencies into the source directory.  This generally should
+be used for generated files such as Bison output files which are not
+present in CVS, but should be included in any release tarballs.  This
+target will be executed during a bootstrap if
+@samp{--enable-generated-files-in-srcdir} was specified as a
+@file{configure} option.
+@item srcinfo
+@itemx srcman
+Copies its dependencies into the source directory.  These targets will be
+executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
+was specified as a @file{configure} option.
+@item uninstall
+Uninstall files installed by installing the compiler.  This is
+currently documented not to be supported, so the hook need not do
+anything.
+@item mostlyclean
+@itemx clean
+@itemx distclean
+@itemx maintainer-clean
+The language parts of the standard GNU
+@samp{*clean} targets.  @xref{Standard Targets, , Standard Targets for
+Users, standards, GNU Coding Standards}, for details of the standard
+targets.  For GCC, @code{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@.
+@item stage1
+@itemx stage2
+@itemx stage3
+@itemx stage4
+@itemx stageprofile
+@itemx stagefeedback
+Move to the stage directory files not included in @code{stagestuff} in
+@file{config-lang.in} or otherwise moved by the main @file{Makefile}.
+@end table
+
+@item lang.opt
+This file registers the set of switches that the front end accepts on
+the command line, and their @option{--help} text.  @xref{Options}.
+@item lang-specs.h
+This file provides entries for @code{default_compilers} in
+@file{gcc.c} which override the default of giving an error that a
+compiler for that language is not installed.
+@item @var{language}-tree.def
+This file, which need not exist, defines any language-specific tree
+codes.
+@end table
+
+@node Front End Config
+@subsubsection The Front End @file{config-lang.in} File
+
+Each language subdirectory contains a @file{config-lang.in} file.  In
+addition the main directory contains @file{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:
+
+@table @code
+@item language
+This definition must be present, and gives the name of the language
+for some purposes such as arguments to @option{--enable-languages}.
+@item 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 @code{language} settings).  For example, the
+Java front end depends on the C++ front end, so sets
+@samp{lang_requires=c++}.
+@item subdir_requires
+If defined, this variable lists (space-separated) front end directories
+other than C that this front end requires to be present.  For example,
+the Objective-C++ front end uses source files from the C++ and
+Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
+@item target_libs
+If defined, this variable lists (space-separated) targets in the top
+level @file{Makefile} to build the runtime libraries for this
+language, such as @code{target-libobjc}.
+@item lang_dirs
+If defined, this variable lists (space-separated) top level
+directories (parallel to @file{gcc}), apart from the runtime libraries,
+that should not be configured if this front end is not built.
+@item build_by_default
+If defined to @samp{no}, this language front end is not built unless
+enabled in a @option{--enable-languages} argument.  Otherwise, front
+ends are built by default, subject to any special logic in
+@file{configure.ac} (as is present to disable the Ada front end if the
+Ada compiler is not already installed).
+@item boot_language
+If defined to @samp{yes}, this front end is built in stage 1 of the
+bootstrap.  This is only relevant to front ends written in their own
+languages.
+@item compilers
+If defined, a space-separated list of compiler executables that will
+be run by the driver.  The names here will each end
+with @samp{\$(exeext)}.
+@item stagestuff
+If defined, a space-separated list of files that should be moved to
+the @file{stage@var{n}} directories in each stage of bootstrap.
+@item outputs
+If defined, a space-separated list of files that should be generated
+by @file{configure} substituting values in them.  This mechanism can
+be used to create a file @file{@var{language}/Makefile} from
+@file{@var{language}/Makefile.in}, but this is deprecated, building
+everything from the single @file{gcc/Makefile} is preferred.
+@item 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.  @xref{Type Information}.
+@item need_gmp
+If defined  to @samp{yes}, this frontend requires the GMP library.
+Enables configure tests for GMP, which set @code{GMPLIBS} and
+@code{GMPINC} appropriately.
+
+@end table
+
+@node Back End
+@subsection Anatomy of a Target Back End
+
+A back end for a target architecture in GCC has the following parts:
+
+@itemize @bullet
+@item
+A directory @file{@var{machine}} under @file{gcc/config}, containing a
+machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
+, Machine Descriptions}), header files @file{@var{machine}.h} and
+@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
+(@pxref{Target Macros, , Target Description Macros and Functions}),
+possibly a target Makefile fragment @file{t-@var{machine}}
+(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
+some other files.  The names of these files may be changed from the
+defaults given by explicit specifications in @file{config.gcc}.
+@item
+If necessary, a file @file{@var{machine}-modes.def} in the
+@file{@var{machine}} directory, containing additional machine modes to
+represent condition codes.  @xref{Condition Code}, for further details.
+@item
+An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
+directory, containing a list of target-specific options.  You can also
+add other option files using the @code{extra_options} variable in
+@file{config.gcc}.  @xref{Options}.
+@item
+Entries in @file{config.gcc} (@pxref{System Config, , The
+@file{config.gcc} File}) for the systems with this target
+architecture.
+@item
+Documentation in @file{gcc/doc/invoke.texi} for any command-line
+options supported by this target (@pxref{Run-time Target, , Run-time
+Target Specification}).  This means both entries in the summary table
+of options and details of the individual options.
+@item
+Documentation in @file{gcc/doc/extend.texi} for any target-specific
+attributes supported (@pxref{Target Attributes, , Defining
+target-specific uses of @code{__attribute__}}), including where the
+same attribute is already supported on some targets, which are
+enumerated in the manual.
+@item
+Documentation in @file{gcc/doc/extend.texi} for any target-specific
+pragmas supported.
+@item
+Documentation in @file{gcc/doc/extend.texi} of any target-specific
+built-in functions supported.
+@item
+Documentation in @file{gcc/doc/extend.texi} of any target-specific
+format checking styles supported.
+@item
+Documentation in @file{gcc/doc/md.texi} of any target-specific
+constraint letters (@pxref{Machine Constraints, , Constraints for
+Particular Machines}).
+@item
+A note in @file{gcc/doc/contrib.texi} under the person or people who
+contributed the target support.
+@item
+Entries in @file{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.
+@item
+Possibly other support outside the @file{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.
+@end itemize
+
+If the back end is added to the official GCC CVS repository, the
+following are also necessary:
+
+@itemize @bullet
+@item
+An entry for the target architecture in @file{readings.html} on the
+GCC web site, with any relevant links.
+@item
+Details of the properties of the back end and target architecture in
+@file{backends.html} on the GCC web site.
+@item
+A news item about the contribution of support for that target
+architecture, in @file{index.html} on the GCC web site.
+@item
+Normally, one or more maintainers of that target listed in
+@file{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.
+@end itemize
+
+@node Testsuites
+@section Testsuites
+
+GCC contains several testsuites to help maintain compiler quality.
+Most of the runtime libraries and language front ends in GCC have
+testsuites.  Currently only the C language testsuites are documented
+here; FIXME: document the others.
+
+@menu
+* Test Idioms::     Idioms used in testsuite code.
+* Test Directives:: Directives used within DejaGnu tests.
+* Ada Tests::       The Ada language testsuites.
+* C Tests::         The C language testsuites.
+* libgcj Tests::    The Java library testsuites.
+* gcov Testing::    Support for testing gcov.
+* profopt Testing:: Support for testing profile-directed optimizations.
+* compat Testing::  Support for testing binary compatibility.
+@end menu
+
+@node Test Idioms
+@subsection Idioms Used in Testsuite Code
+
+In general, C testcases have a trailing @file{-@var{n}.c}, starting
+with @file{-1.c}, in case other testcases with similar names are added
+later.  If the test is a test of some well-defined feature, it should
+have a name referring to that feature such as
+@file{@var{feature}-1.c}.  If it does not test a well-defined feature
+but just happens to exercise a bug somewhere in the compiler, and a
+bug report has been filed for this bug in the GCC bug database,
+@file{pr@var{bug-number}-1.c} is the appropriate form of name.
+Otherwise (for miscellaneous bugs not filed in the GCC bug database),
+and previously more generally, test cases are 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, but does not give any
+other information about the bug or where discussion of it may be
+found.  Some other language testsuites follow similar conventions.
+
+In the @file{gcc.dg} testsuite, 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 @option{-pedantic-errors}.  The following idiom,
+where the first line shown is line @var{line} of the file and the line
+that generates the error, is used for this:
+
+@smallexample
+/* @{ dg-bogus "warning" "warning in place of error" @} */
+/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
+@end smallexample
+
+It may be necessary to check that an expression is an integer constant
+expression and has a certain value.  To check that @code{@var{E}} has
+value @code{@var{V}}, an idiom similar to the following is used:
+
+@smallexample
+char x[((E) == (V) ? 1 : -1)];
+@end smallexample
+
+In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
+assertions about the types of expressions.  See, for example,
+@file{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, @file{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
+@file{gcc.c-torture/execute}.  Where code should be optimized away, a
+call to a nonexistent function such as @code{link_failure ()} may be
+inserted; a definition
+
+@smallexample
+#ifndef __OPTIMIZE__
+void
+link_failure (void)
+@{
+  abort ();
+@}
+#endif
+@end smallexample
+
+@noindent
+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
+@code{static} to call @code{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 testsuites here.
+
+@node Test Directives
+@subsection Directives used within DejaGnu tests
+
+Test directives appear within comments in a test source file and begin
+with @code{dg-}.  Some of these are defined within DejaGnu and others
+are local to the GCC testsuite.
+
+The order in which test directives appear in a test can be important:
+directives local to GCC sometimes override information used by the
+DejaGnu directives, which know nothing about the GCC directives, so the
+DejaGnu directives must precede GCC directives.
+
+Several test directives include selectors which are usually preceded by
+the keyword @code{target} or @code{xfail}.  A selector is: one or more
+target triplets, possibly including wildcard characters; a single
+effective-target keyword; or a logical expression.  Depending on the
+context, the selector specifies whether a test is skipped and reported
+as unsupported or is expected to fail.  Use @samp{*-*-*} to match any
+target.
+Effective-target keywords are defined in @file{target-supports.exp} in
+the GCC testsuite.
+
+A selector expression appears within curly braces and uses a single
+logical operator: one of @samp{!}, @samp{&&}, or @samp{||}.  An
+operand is another selector expression, an effective-target keyword,
+a single target triplet, or a list of target triplets within quotes or
+curly braces.  For example:
+
+@smallexample
+@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
+@{ target @{ powerpc*-*-* && lp64 @} @}
+@{ xfail @{ lp64 || vect_no_align @} @}
+@end smallexample
+
+@table @code
+@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
+@var{do-what-keyword} specifies how the test is compiled and whether
+it is executed.  It is one of:
+
+@table @code
+@item preprocess
+Compile with @option{-E} to run only the preprocessor.
+@item assemble
+Compile with @option{-S} to produce an assembly code file.
+@item compile
+Compile with @option{-c} to produce a relocatable object file.
+@item link
+Compile, assemble, and link to produce an executable file.
+@item run
+Produce and run an executable file, which is expected to return
+an exit code of 0.
+@end table
+
+The default is @code{compile}.  That can be overridden for a set of
+tests by redefining @code{dg-do-what-default} within the @code{.exp}
+file for those tests.
+
+If the directive includes the optional @samp{@{ target @var{selector} @}}
+then the test is skipped unless the target system is included in the
+list of target triplets or matches the effective-target keyword.
+
+If the directive includes the optional @samp{@{ xfail @var{selector} @}}
+and the selector is met then the test is expected to fail.  For
+@code{dg-do run}, execution is expected to fail but compilation
+is expected to pass.
+
+@item @{ dg-options @var{options} [@{ target @var{selector} @}] @}
+This DejaGnu directive provides a list of compiler options, to be used
+if the target system matches @var{selector}, that replace the default
+options used for this set of tests.
+
+@item @{ dg-skip-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
+Skip the test if the test system is included in @var{selector} and if
+each of the options in @var{include-opts} is in the set of options with
+which the test would be compiled and if none of the options in
+@var{exclude-opts} is in the set of options with which the test would be
+compiled.
+
+Use @samp{"*"} for an empty @var{include-opts} list and @samp{""} for
+an empty @var{exclude-opts} list.
+
+@item  @{ dg-xfail-if @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
+Expect the test to fail if the conditions (which are the same as for
+@code{dg-skip-if}) are met.
+
+@item @{ dg-require-@var{support} args @}
+Skip the test if the target does not provide the required support;
+see @file{gcc-dg.exp} in the GCC testsuite for the actual directives.
+These directives must appear after any @code{dg-do} directive in the test.
+They require at least one argument, which can be an empty string if the
+specific procedure does not examine the argument.
+
+@item @{ dg-require-effective-target @var{keyword} @}
+Skip the test if the test target, including current multilib flags,
+is not covered by the effective-target keyword.
+This directive must appear after any @code{dg-do} directive in the test.
+
+@item  @{ dg-shouldfail @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
+Expect the test executable to return a nonzero exit status if the
+conditions (which are the same as for @code{dg-skip-if}) are met.
+
+@item @{ dg-error @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
+This DejaGnu directive appears on a source line that is expected to get
+an error message, or else specifies the source line associated with the
+message.  If there is no message for that line or if the text of that
+message is not matched by @var{regexp} then the check fails and
+@var{comment} is included in the @code{FAIL} message.  The check does
+not look for the string @samp{"error"} unless it is part of @var{regexp}.
+
+@item @{ dg-warning @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
+This DejaGnu directive appears on a source line that is expected to get
+a warning message, or else specifies the source line associated with the
+message.  If there is no message for that line or if the text of that
+message is not matched by @var{regexp} then the check fails and
+@var{comment} is included in the @code{FAIL} message.  The check does
+not look for the string @samp{"warning"} unless it is part of @var{regexp}.
+
+@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
+This DejaGnu directive appears on a source line that should not get a
+message matching @var{regexp}, or else specifies the source line
+associated with the bogus message.  It is usually used with @samp{xfail}
+to indicate that the message is a known problem for a particular set of
+targets.
+
+@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
+This DejaGnu directive indicates that the test is expected to fail due
+to compiler messages that are not handled by @samp{dg-error},
+@samp{dg-warning} or @samp{dg-bogus}.
+
+@item @{ dg-output @var{regexp} [@{ target/xfail @var{selector} @}] @}
+This DejaGnu directive compares @var{regexp} to the combined output
+that the test executable writes to @file{stdout} and @file{stderr}.
+
+@item @{ dg-prune-output @var{regexp} @}
+Prune messages matching @var{regexp} from test output.
+
+@item @{ dg-additional-files "@var{filelist}" @}
+Specify additional files, other than source files, that must be copied
+to the system where the compiler runs.
+
+@item @{ dg-additional-sources "@var{filelist}" @}
+Specify additional source files to appear in the compile line
+following the main test file.
+
+@item @{ dg-final @{ @var{local-directive} @} @}
+This DejaGnu directive is placed within a comment anywhere in the
+source file and is processed after the test has been compiled and run.
+Multiple @samp{dg-final} commands are processed in the order in which
+they appear in the source file.
+
+The GCC testsuite defines the following directives to be used within
+@code{dg-final}.
+
+@table @code
+@item cleanup-coverage-files
+Removes coverage data files generated for this test.
+
+@item cleanup-repo-files
+Removes files generated for this test for @option{-frepo}.
+
+@item cleanup-rtl-dump @var{suffix}
+Removes RTL dump files generated for this test.
+
+@item cleanup-tree-dump @var{suffix}
+Removes tree dump files matching @var{suffix} which were generated for
+this test.
+
+@item cleanup-saved-temps
+Removes files for the current test which were kept for @option{--save-temps}.
+
+@item scan-file @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
+Passes if @var{regexp} matches text in @var{filename}.
+
+@item scan-file-not @var{filename} @var{regexp} [@{ target/xfail @var{selector} @}]
+Passes if @var{regexp} does not match text in @var{filename}.
+
+@item scan-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
+Passes if @var{symbol} is defined as a hidden symbol in the test's
+assembly output.
+
+@item scan-not-hidden @var{symbol} [@{ target/xfail @var{selector} @}]
+Passes if @var{symbol} is not defined as a hidden symbol in the test's
+assembly output.
+
+@item scan-assembler-times @var{regex} @var{num} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} is matched exactly @var{num} times in the test's
+assembler output.
+
+@item scan-assembler @var{regex} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} matches text in the test's assembler output.
+
+@item scan-assembler-not @var{regex} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} does not match text in the test's assembler output.
+
+@item scan-assembler-dem @var{regex} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} matches text in the test's demangled assembler output.
+
+@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} does not match text in the test's demangled assembler
+output.
+
+@item scan-tree-dump-times @var{regex} @var{num} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} is found exactly @var{num} times in the dump file
+with suffix @var{suffix}.
+
+@item scan-tree-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} matches text in the dump file with suffix @var{suffix}.
+
+@item scan-tree-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} does not match text in the dump file with suffix
+@var{suffix}.
+
+@item scan-tree-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} matches demangled text in the dump file with
+suffix @var{suffix}.
+
+@item scan-tree-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+Passes if @var{regex} does not match demangled text in the dump file with
+suffix @var{suffix}.
+
+@item output-exists [@{ target/xfail @var{selector} @}]
+Passes if compiler output file exists.
+
+@item output-exists-not [@{ target/xfail @var{selector} @}]
+Passes if compiler output file does not exist.
+
+@item run-gcov @var{sourcefile}
+Check line counts in @command{gcov} tests.
+
+@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
+Check branch and/or call counts, in addition to line counts, in
+@command{gcov} tests.
+@end table
+@end table
+
+@node Ada Tests
+@subsection Ada Language Testsuites
+
+The Ada testsuite includes executable tests from the ACATS 2.5
+testsuite, publicly available at
+@uref{http://www.adaic.org/compilers/acats/2.5}
+
+These tests are integrated in the GCC testsuite in the
+@file{gcc/testsuite/ada/acats} directory, and
+enabled automatically when running @code{make check}, assuming
+the Ada language has been enabled when configuring GCC@.
+
+You can also run the Ada testsuite independently, using
+@code{make check-ada}, or run a subset of the tests by specifying which
+chapter to run, e.g.:
+
+@smallexample
+$ make check-ada CHAPTERS="c3 c9"
+@end smallexample
+
+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 @file{gcc} containing a template for
+creating new executable tests.
+
+The tests are run using two @command{sh} scripts: @file{run_acats} and
+@file{run_all.sh}.  To run the tests using a simulator or a cross
+target, see the small
+customization section at the top of @file{run_all.sh}.
+
+These tests are run using the build tree: they can be run without doing
+a @code{make install}.
+
+@node C Tests
+@subsection C Language Testsuites
+
+GCC contains the following C language testsuites, in the
+@file{gcc/testsuite} directory:
+
+@table @file
+@item gcc.dg
+This contains tests of particular features of the C compiler, using the
+more modern @samp{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 @samp{-ansi -pedantic}
+unless other options are given in the test.  Except as noted below they
+are not run with multiple optimization options.
+@item gcc.dg/compat
+This subdirectory contains tests for binary compatibility using
+@file{compat.exp}, which in turn uses the language-independent support
+(@pxref{compat Testing, , Support for testing binary compatibility}).
+@item gcc.dg/cpp
+This subdirectory contains tests of the preprocessor.
+@item gcc.dg/debug
+This subdirectory contains tests for debug formats.  Tests in this
+subdirectory are run for each debug format that the compiler supports.
+@item gcc.dg/format
+This subdirectory contains tests of the @option{-Wformat} format
+checking.  Tests in this directory are run with and without
+@option{-DWIDE}.
+@item 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.
+@item gcc.dg/special
+FIXME: describe this.
+
+@item 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.
+
+@item gcc.c-torture/compat
+FIXME: describe this.
+
+This directory should probably not be used for new tests.
+@item gcc.c-torture/compile
+This testsuite 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 @file{.x} files, mostly these test cases
+should not contain platform dependencies.  FIXME: discuss how defines
+such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
+@item gcc.c-torture/execute
+This testsuite contains test cases that should compile, link and run;
+otherwise the same comments as for @file{gcc.c-torture/compile} apply.
+@item gcc.c-torture/execute/ieee
+This contains tests which are specific to IEEE floating point.
+@item gcc.c-torture/unsorted
+FIXME: describe this.
+
+This directory should probably not be used for new tests.
+@item 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:
+
+@table @file
+@item @code{bprob*.c}
+Test @option{-fbranch-probabilities} using @file{bprob.exp}, which
+in turn uses the generic, language-independent framework
+(@pxref{profopt Testing, , Support for testing profile-directed
+optimizations}).
+
+@item @code{dg-*.c}
+Test the testsuite itself using @file{dg-test.exp}.
+
+@item @code{gcov*.c}
+Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
+language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
+
+@item @code{i386-pf-*.c}
+Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
+@end table
+
+@end table
+
+FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
+test cases and magic comments more.
+
+@node libgcj Tests
+@subsection The Java library testsuites.
+
+Runtime tests are executed via @samp{make check} in the
+@file{@var{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 testsuite.  The @uref{http://sourceware.org/mauve/,,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 @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
+the location of that tree when invoking @samp{make}, as in
+@samp{make MAUVEDIR=~/mauve check}.
+
+To detect regressions, a mechanism in @file{mauve.exp} compares the
+failures for a test run against the list of expected failures in
+@file{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 @uref{http://sourceware.org/mauve/jacks.html,,
+Jacks} project provides a testsuite for Java compilers that can be used
+to test changes that affect the GCJ front end.  This testsuite is run as
+part of Java testing by placing the Jacks tree within the libjava
+testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}.
+
+We encourage developers to contribute test cases to Mauve and Jacks.
+
+@node gcov Testing
+@subsection Support for testing @command{gcov}
+
+Language-independent support for testing @command{gcov}, and for checking
+that branch profiling produces expected values, is provided by the
+expect file @file{gcov.exp}.  @command{gcov} tests also rely on procedures
+in @file{gcc.dg.exp} to compile and run the test program.  A typical
+@command{gcov} test contains the following DejaGnu commands within comments:
+
+@smallexample
+@{ dg-options "-fprofile-arcs -ftest-coverage" @}
+@{ dg-do run @{ target native @} @}
+@{ dg-final @{ run-gcov sourcefile @} @}
+@end smallexample
+
+Checks of @command{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 @command{run-gcov} command has arguments @code{branches}
+or @code{calls}, respectively.  For example, the following specifies
+checking both, as well as passing @option{-b} to @command{gcov}:
+
+@smallexample
+@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
+@end smallexample
+
+A line count command appears within a comment on the source line
+that is expected to get the specified count and has the form
+@code{count(@var{cnt})}.  A test should only check line counts for
+lines that will get the same count for any architecture.
+
+Commands to check branch percentages (@code{branch}) and call
+return percentages (@code{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 @code{branch(end)} or @code{returns(end)} marks
+the end of a range without starting a new one.  For example:
+
+@smallexample
+if (i > 10 && j > i && j < 20)  /* @r{branch(27 50 75)} */
+                                /* @r{branch(end)} */
+  foo (i, j);
+@end smallexample
+
+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.
+
+@node profopt Testing
+@subsection Support for testing profile-directed optimizations
+
+The file @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.  @file{profopt.exp} has the beginnings of this kind
+of support.
+
+@file{profopt.exp} provides generic support for profile-directed
+optimizations.  Each set of tests that uses it provides information
+about a specific optimization:
+
+@table @code
+@item tool
+tool being tested, e.g., @command{gcc}
+
+@item profile_option
+options used to generate profile data
+
+@item feedback_option
+options used to optimize using that profile data
+
+@item prof_ext
+suffix of profile data files
+
+@item PROFOPT_OPTIONS
+list of options with which to run each test, similar to the lists for
+torture tests
+@end table
+
+@node compat Testing
+@subsection Support for testing binary compatibility
+
+The file @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 testsuites that complement ABI testsuites.
+
+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.
+
+@table @file
+@item @var{testname}_main.@var{suffix}
+Contains the main program, which calls a function in file
+@file{@var{testname}_x.@var{suffix}}.
+
+@item @var{testname}_x.@var{suffix}
+Contains at least one call to a function in
+@file{@var{testname}_y.@var{suffix}}.
+
+@item @var{testname}_y.@var{suffix}
+Shares data with, or gets arguments from,
+@file{@var{testname}_x.@var{suffix}}.
+@end table
+
+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.
+You can specify pairs of sets of compiler options.  The first element
+of such a pair specifies options used with the GCC under test, and the
+second element of the pair specifies options used with the alternate
+compiler.  Each test is compiled with each pair of options.
+
+@file{compat.exp} defines default pairs of compiler options.
+These can be overridden by defining the environment variable
+@env{COMPAT_OPTIONS} as:
+
+@smallexample
+COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
+  ...[list @{@var{tstn}@} @{@var{altn}@}]]"
+@end smallexample
+
+where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
+used by the compiler under test and @var{alti} used by the alternate
+compiler.  For example, with
+@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
+the test is first built with @option{-g -O0} by the compiler under
+test and with @option{-O3} by the alternate compiler.  The test is
+built a second time using @option{-fpic} by the compiler under test
+and @option{-fPIC -O2} by the alternate compiler.
+
+An alternate compiler is specified by defining an environment
+variable to be the full pathname of an installed compiler; for C
+define @env{ALT_CC_UNDER_TEST}, and for C++ define
+@env{ALT_CXX_UNDER_TEST}.  These will be written to the
+@file{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 @env{COMPAT_OPTIONS}.  When
+@env{ALT_CC_UNDER_TEST} or
+@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
+the compiler under test but with combinations of the options from
+@env{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 @file{@var{objdir}/gcc}:
+
+@smallexample
+rm site.exp
+make -k \
+  ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
+  COMPAT_OPTIONS="lists as shown above" \
+  check-c++ \
+  RUNTESTFLAGS="compat.exp"
+@end smallexample
+
+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.
+
+The binary compatibility tests support a small number of test framework
+commands that appear within comments in a test file.
+
+@table @code
+@item dg-require-*
+These commands can be used in @file{@var{testname}_main.@var{suffix}}
+to skip the test if specific support is not available on the target.
+
+@item dg-options
+The specified options are used for compiling this particular source
+file, appended to the options from @env{COMPAT_OPTIONS}.  When this
+command appears in @file{@var{testname}_main.@var{suffix}} the options
+are also used to link the test program.
+
+@item dg-xfail-if
+This command can be used in a secondary source file to specify that
+compilation is expected to fail for particular options on particular
+targets.
+@end table