-@c Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc.
+@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2010
+@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
* 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
The Boehm conservative garbage collector, used as part of the Java
runtime library.
+@item config
+Autoconf macros and Makefile fragments used throughout the tree.
+
@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 fixincludes
+The support for fixing system headers to work with GCC@. See
+@file{fixincludes/README} for more information. The headers fixed by
+this mechanism are installed in @file{@var{libsubdir}/include-fixed}.
+Along with those headers, @file{README-fixinc} is also installed, as
+@file{@var{libsubdir}/include-fixed/README}.
@item gcc
The main sources of GCC itself (except for runtime libraries),
language front ends, and testsuites. @xref{gcc Directory, , The
@file{gcc} Subdirectory}, for details.
+@item gnattools
+Support tools for GNAT.
+
@item include
Headers for the @code{libiberty} library.
+@item intl
+GNU @code{libintl}, from GNU @code{gettext}, for systems which do not
+include it in @code{libc}.
+
@item libada
The Ada runtime library.
@item libcpp
The C preprocessor library.
-@item libgfortran
-The Fortran runtime library.
+@item libdecnumber
+The Decimal Float support library.
@item libffi
The @code{libffi} library, used as part of the Java runtime library.
+@item libgcc
+The GCC runtime library.
+
+@item libgfortran
+The Fortran runtime library.
+
+@item libgo
+The Go runtime library. The bulk of this library is mirrored from the
+@uref{http://code.google.com/@/p/@/go/, master Go repository}.
+
+@item libgomp
+The GNU OpenMP runtime library.
+
@item libiberty
The @code{libiberty} library, used for portability and for some
generally useful data structures and algorithms. @xref{Top, ,
@item libobjc
The Objective-C and Objective-C++ runtime library.
+@item libssp
+The Stack protector runtime library.
+
@item libstdc++-v3
The C++ runtime library.
+@item lto-plugin
+Plugin used by @command{gold} if link-time optimizations are enabled.
+
@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.
+The @code{zlib} compression library, used by the Java front end, as
+part of the Java runtime library, and for compressing and uncompressing
+GCC's intermediate language in LTO object files.
@end table
The build system in the top level directory, including how recursion
@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.
+the subdirectories @file{cp} (for C++), @file{lto} (for LTO),
+@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
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
@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?
+files, kept in the top level directory, are used.
@item The file @file{config.gcc} is used to handle configuration
specific to the particular target machine. The file
@file{gsyslimits.h} if it does not need fixing to work with GCC; if it
needs fixing, @file{syslimits.h} is the fixed copy.
+GCC can also install @code{<tgmath.h>}. It will do this when
+@file{config.gcc} sets @code{use_gcc_tgmath} to @code{yes}.
+
@node Documentation
@subsection 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 @samp{make dvi}. In addition, some man pages are
+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 @samp{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
@item gcc-common.texi
Common definitions for manuals.
@item gpl.texi
+@itemx gpl_v3.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)}). Info
+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 @samp{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)},
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
+@file{maintainer-scripts/update_web_docs_svn}. 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
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} and PostScript manuals by @command{texi2dvi}
-and @command{dvips}. All Texinfo files that are parts of manuals must
-be checked into CVS, even if they are generated files, for the
+@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 version-controlled, 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
@subsubsection Miscellaneous Documentation
In addition to the formal documentation that is installed by GCC,
-there are several other text files with miscellaneous documentation:
+there are several other text files in the @file{gcc} subdirectory
+with miscellaneous documentation:
@table @file
@item ABOUT-GCC-NLS
@item ABOUT-NLS
Notes on the Free Translation Project.
@item COPYING
-The GNU General Public License.
+@itemx COPYING3
+The GNU General Public License, Versions 2 and 3.
@item COPYING.LIB
-The GNU Lesser General Public License.
+@itemx COPYING3.LIB
+The GNU Lesser General Public License, Versions 2.1 and 3.
@item *ChangeLog*
@itemx */ChangeLog*
Change log files for various parts of GCC@.
@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},
@item
Details of the directories of any runtime libraries in
@file{gcc/doc/sourcebuild.texi}.
+@item
+Check targets in @file{Makefile.def} for the top-level @file{Makefile}
+to check just the compiler or the compiler and runtime library for the
+language.
@end itemize
-If the front end is added to the official GCC CVS repository, the
+If the front end is added to the official GCC source 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.
+libraries. This category needs to be added to the Bugzilla database.
@item
Normally, one or more maintainers of that front end listed in
@file{MAINTAINERS}.
@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})
+@file{maintainer-scripts/update_web_docs_svn} (@pxref{Texinfo Manuals})
and the online manuals should be linked to from
@file{onlinedocs/index.html}.
@item
@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.
+* Front End Makefile:: The front end @file{Make-lang.in} file.
@end menu
@node Front End 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.
+possibly some subsidiary programs built alongside the front end.
Certain files are special and other parts of the compiler depend on
their names:
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
+This file is required in all language subdirectories. @xref{Front End
+Makefile, , The Front End @file{Make-lang.in} File}, for details of its
+contents.
+@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 stage1 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 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
+@file{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}.
+
+@end table
+
+@node Front End Makefile
+@subsubsection The Front End @file{Make-lang.in} File
+
+Each language subdirectory contains a @file{Make-lang.in} file. 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). Some hooks are defined by using a double-colon rule for
-@code{@var{hook}}, rather than by using a target of form
-@code{@var{lang}.@var{hook}}. These hooks are called ``double-colon
-hooks'' below. It also adds any testsuite targets that can use the
+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
-@item all.build
@itemx all.cross
@itemx start.encap
@itemx rest.encap
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.
-This hook is a double-colon hook.
+@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-normal
-FIXME: what is this target for?
@item install-common
Install everything that is part of the front end, apart from the
compiler executables listed in @code{compilers} 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. This hook is a double-colon hook.
+that should be installed.
@item install-man
Install man pages for the front end. This target should ignore
errors.
+@item install-plugin
+Install headers needed for plugins.
@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
+version-controlled, 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.
@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. The file format is
-documented in the file @file{c.opt}. These files are processed by the
-script @file{opts.sh}.
-@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.
+all generated files in the source directory that are not version-controlled,
+but should not delete anything that is.
@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 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
+@file{Make-lang.in} must also define a variable @code{@var{lang}_OBJS}
+to a list of host object files that are used by that language.
@node Back End
@subsection Anatomy of a Target Back End
@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.
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
+libraries. FIXME: reference docs for this. The @code{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
+If the back end is added to the official GCC source repository, the
following are also necessary:
@itemize @bullet
@end itemize
@node Testsuites
-@section Testsuites
+@chapter Testsuites
GCC contains several testsuites to help maintain compiler quality.
Most of the runtime libraries and language front ends in GCC have
@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.
+* LTO Testing:: Support for testing link-time optimizations.
* gcov Testing:: Support for testing gcov.
* profopt Testing:: Support for testing profile-directed optimizations.
* compat Testing:: Support for testing binary compatibility.
+* Torture Tests:: Support for torture testing using multiple options.
@end menu
@node Test Idioms
-@subsection Idioms Used in Testsuite Code
+@section Idioms Used in Testsuite Code
-In general C testcases have a trailing @file{-@var{n}.c}, starting
+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
FIXME: discuss non-C testsuites here.
-@node Ada Tests
-@subsection Ada Language Testsuites
+@node Test Directives
+@section Directives used within DejaGnu tests
-The Ada testsuite includes executable tests from the ACATS 2.5
-testsuite, publicly available at
-@uref{http://www.adaic.org/compilers/acats/2.5}
+@menu
+* Directives:: Syntax and descriptions of test directives.
+* Selectors:: Selecting targets to which a test applies.
+* Effective-Target Keywords:: Keywords describing target attributes.
+* Add Options:: Features for @code{dg-add-options}
+* Require Support:: Variants of @code{dg-require-@var{support}}
+* Final Actions:: Commands for use in @code{dg-final}
+@end menu
-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@.
+@node Directives
+@subsection Syntax and Descriptions of test directives
-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.:
+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.
-@smallexample
-$ make check-ada CHAPTERS="c3 c9"
-@end smallexample
+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.
-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.
+Several test directives include selectors (@pxref{Selectors, , })
+which are usually preceded by the keyword @code{target} or @code{xfail}.
-There is also an extra chapter called @file{gcc} containing a template for
-creating new executable tests.
+@subsubsection Specify how to build the test
-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}.
+@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:
-These tests are run using the build tree: they can be run without doing
-a @code{make install}.
+@table @code
+@item preprocess
+Compile with @option{-E} to run only the preprocessor.
+@item compile
+Compile with @option{-S} to produce an assembly code file.
+@item assemble
+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
-@node C Tests
-@subsection C Language Testsuites
+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.
-GCC contains the following C language testsuites, in the
-@file{gcc/testsuite} directory:
+If the directive includes the optional @samp{@{ target @var{selector} @}}
+then the test is skipped unless the target system matches the
+@var{selector}.
-@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.
+If @var{do-what-keyword} is @code{run} and the directive includes
+the optional @samp{@{ xfail @var{selector} @}} and the selector is met
+then the test is expected to fail. The @code{xfail} clause is ignored
+for other values of @var{do-what-keyword}; those tests can use
+directive @code{dg-xfail-if}.
+@end table
-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.
+@subsubsection Specify additional compiler options
-@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.
+@table @code
+@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-add-options @var{feature} @dots{} @}
+Add any compiler options that are needed to access certain features.
+This directive does nothing on targets that enable the features by
+default, or that don't provide them at all. It must come after
+all @code{dg-options} directives.
+For supported values of @var{feature} see @ref{Add Options, ,}.
+@end table
-@item gcc.c-torture/compat
-FIXME: describe this.
+@subsubsection Modify the test timeout value
-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.
+The normal timeout limit, in seconds, is found by searching the
+following in order:
-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:
+@itemize @bullet
+@item the value defined by an earlier @code{dg-timeout} directive in
+the test
-@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 variable @var{tool_timeout} defined by the set of tests
-@item @code{dg-*.c}
-Test the testsuite itself using @file{dg-test.exp}.
+@item @var{gcc},@var{timeout} set in the target board
-@item @code{gcov*.c}
+@item 300
+@end itemize
+
+@table @code
+@item @{ dg-timeout @var{n} [@{target @var{selector} @}] @}
+Set the time limit for the compilation and for the execution of the test
+to the specified number of seconds.
+
+@item @{ dg-timeout-factor @var{x} [@{ target @var{selector} @}] @}
+Multiply the normal time limit for compilation and execution of the test
+by the specified floating-point factor.
+@end table
+
+@subsubsection Skip a test for some targets
+
+@table @code
+@item @{ dg-skip-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
+Arguments @var{include-opts} and @var{exclude-opts} are lists in which
+each element is a string of zero or more GCC options.
+Skip the test if all of the following conditions are met:
+@itemize @bullet
+@item the test system is included in @var{selector}
+
+@item for at least one of the option strings in @var{include-opts},
+every option from that string is in the set of options with which
+the test would be compiled; use @samp{"*"} for an @var{include-opts} list
+that matches any options; that is the default if @var{include-opts} is
+not specified
+
+@item for each of the option strings in @var{exclude-opts}, at least one
+option from that string is not in the set of options with which the test
+would be compiled; use @samp{""} for an empty @var{exclude-opts} list;
+that is the default if @var{exclude-opts} is not specified
+@end itemize
+
+For example, to skip a test if option @code{-Os} is present:
+
+@smallexample
+/* @{ dg-skip-if "" @{ *-*-* @} @{ "-Os" @} @{ "" @} @} */
+@end smallexample
+
+To skip a test if both options @code{-O2} and @code{-g} are present:
+
+@smallexample
+/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" @} @{ "" @} @} */
+@end smallexample
+
+To skip a test if either @code{-O2} or @code{-O3} is present:
+
+@smallexample
+/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2" "-O3" @} @{ "" @} @} */
+@end smallexample
+
+To skip a test unless option @code{-Os} is present:
+
+@smallexample
+/* @{ dg-skip-if "" @{ *-*-* @} @{ "*" @} @{ "-Os" @} @} */
+@end smallexample
+
+To skip a test if either @code{-O2} or @code{-O3} is used with @code{-g}
+but not if @code{-fpic} is also present:
+
+@smallexample
+/* @{ dg-skip-if "" @{ *-*-* @} @{ "-O2 -g" "-O3 -g" @} @{ "-fpic" @} @} */
+@end smallexample
+
+@item @{ dg-require-effective-target @var{keyword} [@{ @var{selector} @}] @}
+Skip the test if the test target, including current multilib flags,
+is not covered by the effective-target keyword.
+If the directive includes the optional @samp{@{ @var{selector} @}}
+then the effective-target test is only performed if the target system
+matches the @var{selector}.
+This directive must appear after any @code{dg-do} directive in the test
+and before any @code{dg-additional-sources} directive.
+@xref{Effective-Target Keywords, , }.
+
+@item @{ dg-require-@var{support} args @}
+Skip the test if the target does not provide the required support.
+These directives must appear after any @code{dg-do} directive in the test
+and before any @code{dg-additional-sources} directive.
+They require at least one argument, which can be an empty string if the
+specific procedure does not examine the argument.
+@xref{Require Support, , }, for a complete list of these directives.
+@end table
+
+@subsubsection Expect a test to fail for some targets
+
+@table @code
+@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. This does not affect the execute step.
+
+@item @{ dg-xfail-run-if @var{comment} @{ @var{selector} @} [@{ @var{include-opts} @} [@{ @var{exclude-opts} @}]] @}
+Expect the execute step of a test to fail if the conditions (which are
+the same as for @code{dg-skip-if}) are met.
+@end table
+
+@subsubsection Expect the test executable to fail
+
+@table @code
+@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.
+@end table
+
+@subsubsection Verify compiler messages
+
+@table @code
+@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-message @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
+The line is expected to get a message other than an error or warning.
+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.
+
+@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}. For this directive @samp{xfail}
+has the same effect as @samp{target}.
+
+@item @{ dg-prune-output @var{regexp} @}
+Prune messages matching @var{regexp} from the test output.
+@end table
+
+@subsubsection Verify output of the test executable
+
+@table @code
+@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}.
+@end table
+
+@subsubsection Specify additional files for a test
+
+@table @code
+@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.
+@end table
+
+@subsubsection Add checks at the end of a test
+
+@table @code
+@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. @xref{Final Actions, , }, for a list
+of directives that can be used within @code{dg-final}.
+@end table
+
+@node Selectors
+@subsection Selecting targets to which a test applies
+
+Several test directives include @var{selector}s to limit the targets
+for which a test is run or to declare that a test is expected to fail
+on particular targets.
+
+A selector is:
+@itemize @bullet
+@item one or more target triplets, possibly including wildcard characters
+@item a single effective-target keyword (@pxref{Effective-Target Keywords})
+@item a logical expression
+@end itemize
+
+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.
+
+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
+
+@node Effective-Target Keywords
+@subsection Keywords describing target attributes
+
+Effective-target keywords identify sets of targets that support
+particular functionality. They are used to limit tests to be run only
+for particular targets, or to specify that particular sets of targets
+are expected to fail some tests.
+
+Effective-target keywords are defined in @file{lib/target-supports.exp} in
+the GCC testsuite, with the exception of those that are documented as
+being local to a particular test directory.
+
+The @samp{effective target} takes into account all of the compiler options
+with which the test will be compiled, including the multilib options.
+By convention, keywords ending in @code{_nocache} can also include options
+specified for the particular test in an earlier @code{dg-options} or
+@code{dg-add-options} directive.
+
+@subsubsection Data type sizes
+
+@table @code
+@item ilp32
+Target has 32-bit @code{int}, @code{long}, and pointers.
+
+@item lp64
+Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
+
+@item llp64
+Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
+and pointers.
+
+@item double64
+Target has 64-bit @code{double}.
+
+@item double64plus
+Target has @code{double} that is 64 bits or longer.
+
+@item int32plus
+Target has @code{int} that is at 32 bits or longer.
+
+@item int16
+Target has @code{int} that is 16 bits or shorter.
+
+@item large_double
+Target supports @code{double} that is longer than @code{float}.
+
+@item large_long_double
+Target supports @code{long double} that is longer than @code{double}.
+
+@item ptr32plus
+Target has pointers that are 32 bits or longer.
+
+@item size32plus
+Target supports array and structure sizes that are 32 bits or longer.
+
+@item 4byte_wchar_t
+Target has @code{wchar_t} that is at least 4 bytes.
+@end table
+
+@subsubsection Fortran-specific attributes
+
+@table @code
+@item fortran_integer_16
+Target supports Fortran @code{integer} that is 16 bytes or longer.
+
+@item fortran_large_int
+Target supports Fortran @code{integer} kinds larger than @code{integer(8)}.
+
+@item fortran_large_real
+Target supports Fortran @code{real} kinds larger than @code{real(8)}.
+@end table
+
+@subsubsection Vector-specific attributes
+
+@table @code
+@item vect_condition
+Target supports vector conditional operations.
+
+@item vect_double
+Target supports hardware vectors of @code{double}.
+
+@item vect_float
+Target supports hardware vectors of @code{float}.
+
+@item vect_int
+Target supports hardware vectors of @code{int}.
+
+@item vect_long
+Target supports hardware vectors of @code{long}.
+
+@item vect_long_long
+Target supports hardware vectors of @code{long long}.
+
+@item vect_aligned_arrays
+Target aligns arrays to vector alignment boundary.
+
+@item vect_hw_misalign
+Target supports a vector misalign access.
+
+@item vect_no_align
+Target does not support a vector alignment mechanism.
+
+@item vect_no_int_max
+Target does not support a vector max instruction on @code{int}.
+
+@item vect_no_int_add
+Target does not support a vector add instruction on @code{int}.
+
+@item vect_no_bitwise
+Target does not support vector bitwise instructions.
+
+@item vect_char_mult
+Target supports @code{vector char} multiplication.
+
+@item vect_short_mult
+Target supports @code{vector short} multiplication.
+
+@item vect_int_mult
+Target supports @code{vector int} multiplication.
+
+@item vect_extract_even_odd
+Target supports vector even/odd element extraction.
+
+@item vect_extract_even_odd_wide
+Target supports vector even/odd element extraction of vectors with elements
+@code{SImode} or larger.
+
+@item vect_interleave
+Target supports vector interleaving.
+
+@item vect_strided
+Target supports vector interleaving and extract even/odd.
+
+@item vect_strided_wide
+Target supports vector interleaving and extract even/odd for wide
+element types.
+
+@item vect_perm
+Target supports vector permutation.
+
+@item vect_shift
+Target supports a hardware vector shift operation.
+
+@item vect_widen_sum_hi_to_si
+Target supports a vector widening summation of @code{short} operands
+into @code{int} results, or can promote (unpack) from @code{short}
+to @code{int}.
+
+@item vect_widen_sum_qi_to_hi
+Target supports a vector widening summation of @code{char} operands
+into @code{short} results, or can promote (unpack) from @code{char}
+to @code{short}.
+
+@item vect_widen_sum_qi_to_si
+Target supports a vector widening summation of @code{char} operands
+into @code{int} results.
+
+@item vect_widen_mult_qi_to_hi
+Target supports a vector widening multiplication of @code{char} operands
+into @code{short} results, or can promote (unpack) from @code{char} to
+@code{short} and perform non-widening multiplication of @code{short}.
+
+@item vect_widen_mult_hi_to_si
+Target supports a vector widening multiplication of @code{short} operands
+into @code{int} results, or can promote (unpack) from @code{short} to
+@code{int} and perform non-widening multiplication of @code{int}.
+
+@item vect_sdot_qi
+Target supports a vector dot-product of @code{signed char}.
+
+@item vect_udot_qi
+Target supports a vector dot-product of @code{unsigned char}.
+
+@item vect_sdot_hi
+Target supports a vector dot-product of @code{signed short}.
+
+@item vect_udot_hi
+Target supports a vector dot-product of @code{unsigned short}.
+
+@item vect_pack_trunc
+Target supports a vector demotion (packing) of @code{short} to @code{char}
+and from @code{int} to @code{short} using modulo arithmetic.
+
+@item vect_unpack
+Target supports a vector promotion (unpacking) of @code{char} to @code{short}
+and from @code{char} to @code{int}.
+
+@item vect_intfloat_cvt
+Target supports conversion from @code{signed int} to @code{float}.
+
+@item vect_uintfloat_cvt
+Target supports conversion from @code{unsigned int} to @code{float}.
+
+@item vect_floatint_cvt
+Target supports conversion from @code{float} to @code{signed int}.
+
+@item vect_floatuint_cvt
+Target supports conversion from @code{float} to @code{unsigned int}.
+@end table
+
+@subsubsection Thread Local Storage attributes
+
+@table @code
+@item tls
+Target supports thread-local storage.
+
+@item tls_native
+Target supports native (rather than emulated) thread-local storage.
+
+@item tls_runtime
+Test system supports executing TLS executables.
+@end table
+
+@subsubsection Decimal floating point attributes
+
+@table @code
+@item dfp
+Targets supports compiling decimal floating point extension to C.
+
+@item dfp_nocache
+Including the options used to compile this particular test, the
+target supports compiling decimal floating point extension to C.
+
+@item dfprt
+Test system can execute decimal floating point tests.
+
+@item dfprt_nocache
+Including the options used to compile this particular test, the
+test system can execute decimal floating point tests.
+
+@item hard_dfp
+Target generates decimal floating point instructions with current options.
+@end table
+
+@subsubsection ARM-specific attributes
+
+@table @code
+@item arm32
+ARM target generates 32-bit code.
+
+@item arm_eabi
+ARM target adheres to the ABI for the ARM Architecture.
+
+@item arm_hard_vfp_ok
+ARM target supports @code{-mfpu=vfp -mfloat-abi=hard}.
+Some multilibs may be incompatible with these options.
+
+@item arm_iwmmxt_ok
+ARM target supports @code{-mcpu=iwmmxt}.
+Some multilibs may be incompatible with this option.
+
+@item arm_neon
+ARM target supports generating NEON instructions.
+
+@item arm_neon_hw
+Test system supports executing NEON instructions.
+
+@item arm_neon_ok
+@anchor{arm_neon_ok}
+ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp} or compatible
+options. Some multilibs may be incompatible with these options.
+
+@item arm_neon_fp16_ok
+@anchor{arm_neon_fp16_ok}
+ARM Target supports @code{-mfpu=neon-fp16 -mfloat-abi=softfp} or compatible
+options. Some multilibs may be incompatible with these options.
+
+@item arm_thumb1_ok
+ARM target generates Thumb-1 code for @code{-mthumb}.
+
+@item arm_thumb2_ok
+ARM target generates Thumb-2 code for @code{-mthumb}.
+
+@item arm_vfp_ok
+ARM target supports @code{-mfpu=vfp -mfloat-abi=softfp}.
+Some multilibs may be incompatible with these options.
+@end table
+
+@subsubsection MIPS-specific attributes
+
+@table @code
+@item mips64
+MIPS target supports 64-bit instructions.
+
+@item nomips16
+MIPS target does not produce MIPS16 code.
+
+@item mips16_attribute
+MIPS target can generate MIPS16 code.
+
+@item mips_loongson
+MIPS target is a Loongson-2E or -2F target using an ABI that supports
+the Loongson vector modes.
+
+@item mips_newabi_large_long_double
+MIPS target supports @code{long double} larger than @code{double}
+when using the new ABI.
+
+@item mpaired_single
+MIPS target supports @code{-mpaired-single}.
+@end table
+
+@subsubsection PowerPC-specific attributes
+
+@table @code
+@item powerpc64
+Test system supports executing 64-bit instructions.
+
+@item powerpc_altivec
+PowerPC target supports AltiVec.
+
+@item powerpc_altivec_ok
+PowerPC target supports @code{-maltivec}.
+
+@item powerpc_fprs
+PowerPC target supports floating-point registers.
+
+@item powerpc_hard_double
+PowerPC target supports hardware double-precision floating-point.
+
+@item powerpc_ppu_ok
+PowerPC target supports @code{-mcpu=cell}.
+
+@item powerpc_spe
+PowerPC target supports PowerPC SPE.
+
+@item powerpc_spe_nocache
+Including the options used to compile this particular test, the
+PowerPC target supports PowerPC SPE.
+
+@item powerpc_spu
+PowerPC target supports PowerPC SPU.
+
+@item spu_auto_overlay
+SPU target has toolchain that supports automatic overlay generation.
+
+@item powerpc_vsx_ok
+PowerPC target supports @code{-mvsx}.
+
+@item powerpc_405_nocache
+Including the options used to compile this particular test, the
+PowerPC target supports PowerPC 405.
+
+@item vmx_hw
+PowerPC target supports executing AltiVec instructions.
+@end table
+
+@subsubsection Other hardware attributes
+
+@table @code
+@item avx
+Target supports compiling AVX instructions.
+
+@item cell_hw
+Test system can execute AltiVec and Cell PPU instructions.
+
+@item coldfire_fpu
+Target uses a ColdFire FPU.
+
+@item hard_float
+Target supports FPU instructions.
+
+@item sse
+Target supports compiling @code{sse} instructions.
+
+@item sse_runtime
+Target supports the execution of @code{sse} instructions.
+
+@item sse2
+Target supports compiling @code{sse2} instructions.
+
+@item sse2_runtime
+Target supports the execution of @code{sse2} instructions.
+
+@item sync_char_short
+Target supports atomic operations on @code{char} and @code{short}.
+
+@item sync_int_long
+Target supports atomic operations on @code{int} and @code{long}.
+
+@item ultrasparc_hw
+Test environment appears to run executables on a simulator that
+accepts only @code{EM_SPARC} executables and chokes on @code{EM_SPARC32PLUS}
+or @code{EM_SPARCV9} executables.
+
+@item vect_cmdline_needed
+Target requires a command line argument to enable a SIMD instruction set.
+@end table
+
+@subsubsection Environment attributes
+
+@table @code
+@item c
+The language for the compiler under test is C.
+
+@item c++
+The language for the compiler under test is C++.
+
+@item c99_runtime
+Target provides a full C99 runtime.
+
+@item correct_iso_cpp_string_wchar_protos
+Target @code{string.h} and @code{wchar.h} headers provide C++ required
+overloads for @code{strchr} etc. functions.
+
+@item dummy_wcsftime
+Target uses a dummy @code{wcsftime} function that always returns zero.
+
+@item fd_truncate
+Target can truncate a file from a file descriptor, as used by
+@file{libgfortran/io/unix.c:fd_truncate}; i.e. @code{ftruncate} or
+@code{chsize}.
+
+@item freestanding
+Target is @samp{freestanding} as defined in section 4 of the C99 standard.
+Effectively, it is a target which supports no extra headers or libraries
+other than what is considered essential.
+
+@item init_priority
+Target supports constructors with initialization priority arguments.
+
+@item inttypes_types
+Target has the basic signed and unsigned types in @code{inttypes.h}.
+This is for tests that GCC's notions of these types agree with those
+in the header, as some systems have only @code{inttypes.h}.
+
+@item lax_strtofp
+Target might have errors of a few ULP in string to floating-point
+conversion functions and overflow is not always detected correctly by
+those functions.
+
+@item newlib
+Target supports Newlib.
+
+@item pow10
+Target provides @code{pow10} function.
+
+@item pthread
+Target can compile using @code{pthread.h} with no errors or warnings.
+
+@item pthread_h
+Target has @code{pthread.h}.
+
+@item run_expensive_tests
+Expensive testcases (usually those that consume excessive amounts of CPU
+time) should be run on this target. This can be enabled by setting the
+@env{GCC_TEST_RUN_EXPENSIVE} environment variable to a non-empty string.
+
+@item simulator
+Test system runs executables on a simulator (i.e. slowly) rather than
+hardware (i.e. fast).
+
+@item stdint_types
+Target has the basic signed and unsigned C types in @code{stdint.h}.
+This will be obsolete when GCC ensures a working @code{stdint.h} for
+all targets.
+
+@item trampolines
+Target supports trampolines.
+
+@item uclibc
+Target supports uClibc.
+
+@item unwrapped
+Target does not use a status wrapper.
+
+@item vxworks_kernel
+Target is a VxWorks kernel.
+
+@item vxworks_rtp
+Target is a VxWorks RTP.
+
+@item wchar
+Target supports wide characters.
+@end table
+
+@subsubsection Other attributes
+
+@table @code
+@item automatic_stack_alignment
+Target supports automatic stack alignment.
+
+@item cxa_atexit
+Target uses @code{__cxa_atexit}.
+
+@item default_packed
+Target has packed layout of structure members by default.
+
+@item fgraphite
+Target supports Graphite optimizations.
+
+@item fixed_point
+Target supports fixed-point extension to C.
+
+@item fopenmp
+Target supports OpenMP via @option{-fopenmp}.
+
+@item fpic
+Target supports @option{-fpic} and @option{-fPIC}.
+
+@item freorder
+Target supports @option{-freorder-blocks-and-partition}.
+
+@item fstack_protector
+Target supports @option{-fstack-protector}.
+
+@item gas
+Target uses GNU @command{as}.
+
+@item gc_sections
+Target supports @option{--gc-sections}.
+
+@item keeps_null_pointer_checks
+Target keeps null pointer checks, either due to the use of
+@option{-fno-delete-null-pointer-checks} or hardwired into the target.
+
+@item lto
+Compiler has been configured to support link-time optimization (LTO).
+
+@item named_sections
+Target supports named sections.
+
+@item natural_alignment_32
+Target uses natural alignment (aligned to type size) for types of
+32 bits or less.
+
+@item target_natural_alignment_64
+Target uses natural alignment (aligned to type size) for types of
+64 bits or less.
+
+@item nonpic
+Target does not generate PIC by default.
+
+@item pcc_bitfield_type_matters
+Target defines @code{PCC_BITFIELD_TYPE_MATTERS}.
+
+@item pe_aligned_commons
+Target supports @option{-mpe-aligned-commons}.
+
+@item section_anchors
+Target supports section anchors.
+
+@item short_enums
+Target defaults to short enums.
+
+@item static
+Target supports @option{-static}.
+
+@item static_libgfortran
+Target supports statically linking @samp{libgfortran}.
+
+@item string_merging
+Target supports merging string constants at link time.
+
+@item ucn
+Target supports compiling and assembling UCN.
+
+@item ucn_nocache
+Including the options used to compile this particular test, the
+target supports compiling and assembling UCN.
+
+@item unaligned_stack
+Target does not guarantee that its @code{STACK_BOUNDARY} is greater than
+or equal to the required vector alignment.
+
+@item vector_alignment_reachable
+Vector alignment is reachable for types of 32 bits or less.
+
+@item vector_alignment_reachable_for_64bit
+Vector alignment is reachable for types of 64 bits or less.
+
+@item wchar_t_char16_t_compatible
+Target supports @code{wchar_t} that is compatible with @code{char16_t}.
+
+@item wchar_t_char32_t_compatible
+Target supports @code{wchar_t} that is compatible with @code{char32_t}.
+@end table
+
+@subsubsection Local to tests in @code{gcc.target/i386}
+
+@table @code
+@item 3dnow
+Target supports compiling @code{3dnow} instructions.
+
+@item aes
+Target supports compiling @code{aes} instructions.
+
+@item fma4
+Target supports compiling @code{fma4} instructions.
+
+@item ms_hook_prologue
+Target supports attribute @code{ms_hook_prologue}.
+
+@item pclmul
+Target supports compiling @code{pclmul} instructions.
+
+@item sse3
+Target supports compiling @code{sse3} instructions.
+
+@item sse4
+Target supports compiling @code{sse4} instructions.
+
+@item sse4a
+Target supports compiling @code{sse4a} instructions.
+
+@item ssse3
+Target supports compiling @code{ssse3} instructions.
+
+@item vaes
+Target supports compiling @code{vaes} instructions.
+
+@item vpclmul
+Target supports compiling @code{vpclmul} instructions.
+
+@item xop
+Target supports compiling @code{xop} instructions.
+@end table
+
+@subsubsection Local to tests in @code{gcc.target/spu/ea}
+
+@table @code
+@item ealib
+Target @code{__ea} library functions are available.
+@end table
+
+@subsubsection Local to tests in @code{gcc.test-framework}
+
+@table @code
+@item no
+Always returns 0.
+
+@item yes
+Always returns 1.
+@end table
+
+@node Add Options
+@subsection Features for @code{dg-add-options}
+
+The supported values of @var{feature} for directive @code{dg-add-options}
+are:
+
+@table @code
+@item arm_neon
+NEON support. Only ARM targets support this feature, and only then
+in certain modes; see the @ref{arm_neon_ok,,arm_neon_ok effective target
+keyword}.
+
+@item arm_neon_fp16
+NEON and half-precision floating point support. Only ARM targets
+support this feature, and only then in certain modes; see
+the @ref{arm_neon_ok,,arm_neon_fp16_ok effective target keyword}.
+
+@item bind_pic_locally
+Add the target-specific flags needed to enable functions to bind
+locally when using pic/PIC passes in the testsuite.
+
+@item c99_runtime
+Add the target-specific flags needed to access the C99 runtime.
+
+@item ieee
+Add the target-specific flags needed to enable full IEEE
+compliance mode.
+
+@item mips16_attribute
+@code{mips16} function attributes.
+Only MIPS targets support this feature, and only then in certain modes.
+
+@item tls
+Add the target-specific flags needed to use thread-local storage.
+@end table
+
+@node Require Support
+@subsection Variants of @code{dg-require-@var{support}}
+
+A few of the @code{dg-require} directives take arguments.
+
+@table @code
+@item dg-require-iconv @var{codeset}
+Skip the test if the target does not support iconv. @var{codeset} is
+the codeset to convert to.
+
+@item dg-require-profiling @var{profopt}
+Skip the test if the target does not support profiling with option
+@var{profopt}.
+
+@item dg-require-visibility @var{vis}
+Skip the test if the target does not support the @code{visibility} attribute.
+If @var{vis} is @code{""}, support for @code{visibility("hidden")} is
+checked, for @code{visibility("@var{vis}")} otherwise.
+@end table
+
+The original @code{dg-require} directives were defined before there
+was support for effective-target keywords. The directives that do not
+take arguments could be replaced with effective-target keywords.
+
+@table @code
+@item dg-require-alias ""
+Skip the test if the target does not support the @samp{alias} attribute.
+
+@item dg-require-compat-dfp ""
+Skip this test unless both compilers in a @file{compat} testsuite
+support decimal floating point.
+
+@item dg-require-cxa-atexit ""
+Skip the test if the target does not support @code{__cxa_atexit}.
+This is equivalent to @code{dg-require-effective-target cxa_atexit}.
+
+@item dg-require-dll ""
+Skip the test if the target does not support DLL attributes.
+
+@item dg-require-fork ""
+Skip the test if the target does not support @code{fork}.
+
+@item dg-require-gc-sections ""
+Skip the test if the target's linker does not support the
+@code{--gc-sections} flags.
+This is equivalent to @code{dg-require-effective-target gc-sections}.
+
+@item dg-require-host-local ""
+Skip the test if the host is remote, rather than the same as the build
+system. Some tests are incompatible with DejaGnu's handling of remote
+hosts, which involves copying the source file to the host and compiling
+it with a relative path and "@code{-o a.out}".
+
+@item dg-require-mkfifo ""
+Skip the test if the target does not support @code{mkfifo}.
+
+@item dg-require-named-sections ""
+Skip the test is the target does not support named sections.
+This is equivalent to @code{dg-require-effective-target named_sections}.
+
+@item dg-require-weak ""
+Skip the test if the target does not support weak symbols.
+
+@item dg-require-weak-override ""
+Skip the test if the target does not support overriding weak symbols.
+@end table
+
+@node Final Actions
+@subsection Commands for use in @code{dg-final}
+
+The GCC testsuite defines the following directives to be used within
+@code{dg-final}.
+
+@subsubsection Scan a particular file
+
+@table @code
+@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-module @var{module} @var{regexp} [@{ target/xfail @var{selector} @}]
+Passes if @var{regexp} matches in Fortran module @var{module}.
+@end table
+
+@subsubsection Scan the assembly output
+
+@table @code
+@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-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-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-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.
+@end table
+
+@subsubsection Scan optimization dump files
+
+These commands are available for @var{kind} of @code{tree}, @code{rtl},
+and @code{ipa}.
+
+@table @code
+@item scan-@var{kind}-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-@var{kind}-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-@var{kind}-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-@var{kind}-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-@var{kind}-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}.
+@end table
+
+@subsubsection Verify that an output files exists or not
+
+@table @code
+@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.
+@end table
+
+@subsubsection Check for LTO tests
+
+@table @code
+@item scan-symbol @var{regexp} [@{ target/xfail @var{selector} @}]
+Passes if the pattern is present in the final executable.
+@end table
+
+@subsubsection Checks for @command{gcov} tests
+
+@table @code
+@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
+
+@subsubsection Clean up generated test files
+
+@table @code
+@item cleanup-coverage-files
+Removes coverage data files generated for this test.
+
+@item cleanup-ipa-dump @var{suffix}
+Removes IPA dump files generated for this test.
+
+@item cleanup-modules
+Removes Fortran module files generated for this test.
+
+@item cleanup-profile-file
+Removes profiling 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-saved-temps
+Removes files for the current test which were kept for @option{-save-temps}.
+
+@item cleanup-tree-dump @var{suffix}
+Removes tree dump files matching @var{suffix} which were generated for
+this test.
+@end table
+
+@node Ada Tests
+@section 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{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, @file{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, although this is deprecated in favor of
+the @file{gnat.dg} testsuite.
+
+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
+@section 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{lib/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.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{gcc.misc-tests/bprob.exp}, which
+in turn uses the generic, language-independent framework
+(@pxref{profopt Testing, , Support for testing profile-directed
+optimizations}).
+
+@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}).
Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
@end table
+@item gcc.test-framework
+@table @file
+@item @code{dg-*.c}
+Test the testsuite itself using @file{gcc.test-framework/test-framework.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.
+@section 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://sources.redhat.com/mauve/,,Mauve Project}
+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
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://oss.software.ibm.com/developerworks/opensource/jacks/,,
-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 the libjava
-testsuite sources at @file{libjava/testsuite/libjava.jacks/jacks}.
+We encourage developers to contribute test cases to Mauve.
+
+@node LTO Testing
+@section Support for testing link-time optimizations
+
+Tests for link-time optimizations usually require multiple source files
+that are compiled separately, perhaps with different sets of options.
+There are several special-purpose test directives used for these tests.
+
+@table @code
+@item @{ dg-lto-do @var{do-what-keyword} @}
+@var{do-what-keyword} specifies how the test is compiled and whether
+it is executed. It is one of:
+
+@table @code
+@item assemble
+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{assemble}. That can be overridden for a set of
+tests by redefining @code{dg-do-what-default} within the @code{.exp}
+file for those tests.
+
+Unlike @code{dg-do}, @code{dg-lto-do} does not support an optional
+@samp{target} or @samp{xfail} list. Use @code{dg-skip-if},
+@code{dg-xfail-if}, or @code{dg-xfail-run-if}.
+
+@item @{ dg-lto-options @{ @{ @var{options} @} [@{ @var{options} @}] @} [@{ target @var{selector} @}]@}
+This directive provides a list of one or more sets of compiler options
+to override @var{LTO_OPTIONS}. Each test will be compiled and run with
+each of these sets of options.
-We encourage developers to contribute test cases to Mauve and Jacks.
+@item @{ dg-extra-ld-options @var{options} [@{ target @var{selector} @}]@}
+This directive adds @var{options} to the linker options used.
+
+@item @{ dg-suppress-ld-options @var{options} [@{ target @var{selector} @}]@}
+This directive removes @var{options} from the set of linker options used.
+@end table
@node gcov Testing
-@subsection Support for testing @command{gcov}
+@section 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
+expect file @file{lib/gcov.exp}. @command{gcov} tests also rely on procedures
+in @file{lib/gcc-dg.exp} to compile and run the test program. A typical
@command{gcov} test contains the following DejaGnu commands within comments:
@smallexample
the end of a range without starting a new one. For example:
@smallexample
-if (i > 10 && j > i && j < 20) /* branch(27 50 75) */
- /* branch(end) */
+if (i > 10 && j > i && j < 20) /* @r{branch(27 50 75)} */
+ /* @r{branch(end)} */
foo (i, j);
@end smallexample
bracket the lines that report them.
@node profopt Testing
-@subsection Support for testing profile-directed optimizations
+@section 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
@item PROFOPT_OPTIONS
list of options with which to run each test, similar to the lists for
torture tests
+
+@item @{ dg-final-generate @{ @var{local-directive} @} @}
+This directive is similar to @code{dg-final}, but the
+@var{local-directive} is run after the generation of profile data.
+
+@item @{ dg-final-use @{ @var{local-directive} @} @}
+The @var{local-directive} is run after the profile data have been
+used.
@end table
@node compat Testing
-@subsection Support for testing binary compatibility
+@section Support for testing binary compatibility
The file @file{compat.exp} provides language-independent support for
binary compatibility testing. It supports testing interoperability of
@smallexample
COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
- ...[list @{@var{tstn}@} @{@var{altn}@}]]"
+ @dots{}[list @{@var{tstn}@} @{@var{altn}@}]]"
@end smallexample
where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
rm site.exp
make -k \
ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
- COMPAT_OPTIONS="lists as shown above" \
+ COMPAT_OPTIONS="@var{lists as shown above}" \
check-c++ \
RUNTESTFLAGS="compat.exp"
@end smallexample
compilation is expected to fail for particular options on particular
targets.
@end table
+
+@node Torture Tests
+@section Support for torture testing using multiple options
+
+Throughout the compiler testsuite there are several directories whose
+tests are run multiple times, each with a different set of options.
+These are known as torture tests.
+@file{lib/torture-options.exp} defines procedures to
+set up these lists:
+
+@table @code
+@item torture-init
+Initialize use of torture lists.
+@item set-torture-options
+Set lists of torture options to use for tests with and without loops.
+Optionally combine a set of torture options with a set of other
+options, as is done with Objective-C runtime options.
+@item torture-finish
+Finalize use of torture lists.
+@end table
+
+The @file{.exp} file for a set of tests that use torture options must
+include calls to these three procedures if:
+
+@itemize @bullet
+@item It calls @code{gcc-dg-runtest} and overrides @var{DG_TORTURE_OPTIONS}.
+
+@item It calls @var{$@{tool@}}@code{-torture} or
+@var{$@{tool@}}@code{-torture-execute}, where @var{tool} is @code{c},
+@code{fortran}, or @code{objc}.
+
+@item It calls @code{dg-pch}.
+@end itemize
+
+It is not necessary for a @file{.exp} file that calls @code{gcc-dg-runtest}
+to call the torture procedures if the tests should use the list in
+@var{DG_TORTURE_OPTIONS} defined in @file{gcc-dg.exp}.
+
+Most uses of torture options can override the default lists by defining
+@var{TORTURE_OPTIONS} or add to the default list by defining
+@var{ADDITIONAL_TORTURE_OPTIONS}. Define these in a @file{.dejagnurc}
+file or add them to the @file{site.exp} file; for example
+
+@smallexample
+set ADDITIONAL_TORTURE_OPTIONS [list \
+ @{ -O2 -ftree-loop-linear @} \
+ @{ -O2 -fpeel-loops @} ]
+@end smallexample