[gcc] GCC 4.5.0=>4.5.1

gcc/gcc/doc/sourcebuild.texi

Index: gcc/gcc/doc/sourcebuild.texi
diff --git a/gcc/gcc/doc/sourcebuild.texi b/gcc/gcc/doc/sourcebuild.texi
index fb639826f319d0572fad9b98e34cf607cd95efbd..7ff799019cfca2fd2a2200e1fe2ee61b689cd320 100644
--- a/gcc/gcc/doc/sourcebuild.texi
+++ b/gcc/gcc/doc/sourcebuild.texi
@@ -1,4 +1,4 @@
-@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009
+@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.
@@ -15,7 +15,6 @@ which it is presumed that you are familiar.
 * 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
@@ -33,15 +32,14 @@ subdirectories that contain parts of GCC and its runtime libraries:
 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
@@ -55,12 +53,15 @@ including optimizers, support for different target architectures,
 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 libc.
+include it in @code{libc}.
 
 @item libada
 The Ada runtime library.
@@ -68,12 +69,21 @@ 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 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, ,
@@ -90,15 +100,22 @@ dereferencing operations.
 @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
@@ -137,11 +154,12 @@ The @file{gcc} directory contains the following subdirectories:
 @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
@@ -308,7 +326,7 @@ GCC can also install @code{<tgmath.h>}.  It will do this when
 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
+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
@@ -347,7 +365,7 @@ 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
+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)},
@@ -367,7 +385,7 @@ 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 SVN, even if they are generated files, for the
+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
@@ -421,7 +439,8 @@ comments in more detail.
 @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
@@ -430,9 +449,11 @@ this manual rather than a separate file.
 @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@.
@@ -499,6 +520,10 @@ directory.  FIXME: document this further.
 @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 source repository, the
@@ -544,6 +569,7 @@ updated accordingly.
 @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
@@ -552,7 +578,7 @@ updated accordingly.
 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:
 
@@ -562,7 +588,84 @@ 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
+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
@@ -612,10 +715,12 @@ 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.
@@ -636,84 +741,13 @@ 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@.
+all generated files in the source directory that are not version-controlled,
+but should not delete anything that is.
 @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.
 
-@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 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}.
-
-@end table
-
 @node Back End
 @subsection Anatomy of a Target Back End
 
@@ -777,7 +811,7 @@ 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
+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
@@ -803,7 +837,7 @@ a maintainer when support is added.
 @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
@@ -816,6 +850,7 @@ here; FIXME: document the others.
 * 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.
@@ -823,7 +858,7 @@ here; FIXME: document the others.
 @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
 with @file{-1.c}, in case other testcases with similar names are added
@@ -902,7 +937,19 @@ unfortunately, the mechanisms for this differ by directory.
 FIXME: discuss non-C testsuites here.
 
 @node Test Directives
-@subsection Directives used within DejaGnu tests
+@section Directives used within DejaGnu tests
+
+@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
+
+@node Directives
+@subsection Syntax and Descriptions of test directives
 
 Test directives appear within comments in a test source file and begin
 with @code{dg-}.  Some of these are defined within DejaGnu and others
@@ -913,27 +960,10 @@ 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:
+Several test directives include selectors (@pxref{Selectors, , })
+which are usually preceded by the keyword @code{target} or @code{xfail}.
 
-@smallexample
-@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
-@{ target @{ powerpc*-*-* && lp64 @} @}
-@{ xfail @{ lp64 || vect_no_align @} @}
-@end smallexample
+@subsubsection Specify how to build the test
 
 @table @code
 @item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
@@ -959,15 +989,19 @@ 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.
+then the test is skipped unless the target system matches the
+@var{selector}.
 
-If @samp{do-what-keyword} is @code{run} and the directive includes
+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 @samp{do-what-keyword}; those tests can use
+for other values of @var{do-what-keyword}; those tests can use
 directive @code{dg-xfail-if}.
+@end table
+
+@subsubsection Specify additional compiler options
 
+@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
@@ -978,25 +1012,13 @@ 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.
-
-The supported values of @var{feature} are:
-@table @code
-@item c99_runtime
-The target's C99 runtime (both headers and libraries).
-
-@item mips16_attribute
-@code{mips16} function attributes.  Only MIPS targets support this feature,
-and only then in certain modes.
+For supported values of @var{feature} see @ref{Add Options, ,}.
 @end table
 
-@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.
+@subsubsection Modify the test timeout value
 
-@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.  The normal timeout limit, in
-seconds, is found by searching the following in order:
+The normal timeout limit, in seconds, is found by searching the
+following in order:
 
 @itemize @bullet
 @item the value defined by an earlier @code{dg-timeout} directive in
@@ -1009,49 +1031,118 @@ the test
 @item 300
 @end itemize
 
-@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.
+@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.
 
-Use @samp{"*"} for an empty @var{include-opts} list and @samp{""} for
-an empty @var{exclude-opts} list.
+@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
 
-@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.
+@subsubsection Skip a test for some targets
 
-@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}) and @code{dg-xfail-if}) are met.
+@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;
-see @file{gcc-dg.exp} in the GCC testsuite for the actual directives.
+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
 
-@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
-and before any @code{dg-additional-sources} directive.
+@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
 
-@item  @{ dg-shouldfail @var{comment} @{ @var{selector} @} @{ @var{include-opts} @} @{ @var{exclude-opts} @} @}
+@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}.
+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
@@ -1059,7 +1150,7 @@ 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}.
+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.
@@ -1080,13 +1171,21 @@ 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
 
-@item @{ dg-prune-output @var{regexp} @}
-Prune messages matching @var{regexp} from test output.
+@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.
@@ -1094,57 +1193,799 @@ 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.
+they appear in the source file.  @xref{Final Actions, , }, for a list
+of directives that can be used within @code{dg-final}.
+@end table
 
-The GCC testsuite defines the following directives to be used within
-@code{dg-final}.
+@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 cleanup-coverage-files
-Removes coverage data files generated for this test.
+@item ilp32
+Target has 32-bit @code{int}, @code{long}, and pointers.
 
-@item cleanup-repo-files
-Removes files generated for this test for @option{-frepo}.
+@item lp64
+Target has 32-bit @code{int}, 64-bit @code{long} and pointers.
 
-@item cleanup-rtl-dump @var{suffix}
-Removes RTL dump files generated for this test.
+@item llp64
+Target has 32-bit @code{int} and @code{long}, 64-bit @code{long long}
+and pointers.
 
-@item cleanup-tree-dump @var{suffix}
-Removes tree dump files matching @var{suffix} which were generated for
-this test.
+@item double64
+Target has 64-bit @code{double}.
 
-@item cleanup-saved-temps
-Removes files for the current test which were kept for @option{--save-temps}.
+@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_int_mult
+Target supports a vector widening multiplication of @code{short} operands
+into an @code{int} result, or supports promotion (unpacking) from
+@code{short} to @code{int} and a non-widening multiplication 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
+ARM Target supports @code{-mfpu=neon -mfloat-abi=softfp}.
+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 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 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.
+@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
 
-@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.
+@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.
 
@@ -1152,31 +1993,61 @@ Passes if @var{regex} matches text in the test's demangled assembler output.
 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-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
 
-@item scan-tree-dump @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+@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-tree-dump-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+@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-tree-dump-dem @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+@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-tree-dump-dem-not @var{regex} @var{suffix} [@{ target/xfail @var{selector} @}]
+@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.
 
@@ -1184,17 +2055,45 @@ Check line counts in @command{gcov} tests.
 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
-@subsection Ada Language Testsuites
+@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}
+@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
+@file{ada/acats} directory, and
 enabled automatically when running @code{make check}, assuming
 the Ada language has been enabled when configuring GCC@.
 
@@ -1207,11 +2106,12 @@ $ 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
+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.
+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
@@ -1222,7 +2122,7 @@ 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
+@section C Language Testsuites
 
 GCC contains the following C language testsuites, in the
 @file{gcc/testsuite} directory:
@@ -1241,7 +2141,7 @@ 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
+@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.
@@ -1291,21 +2191,19 @@ This contains tests which are specific to IEEE floating point.
 FIXME: describe this.
 
 This directory should probably not be used for new tests.
-@item gcc.c-torture/misc-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{bprob.exp}, which
+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{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}).
@@ -1314,13 +2212,19 @@ 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
@@ -1342,13 +2246,55 @@ bugs in libgcj that had caused Mauve test failures.
 
 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.
+
+@item @{ dg-extra-ld-options @var{options} @}
+This directive adds @var{options} to the linker options used.
+
+@item @{ dg-suppress-ld-options @var{options} @}
+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
@@ -1409,7 +2355,7 @@ 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
+@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
@@ -1445,10 +2391,18 @@ suffix of profile data files
 @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
@@ -1521,7 +2475,7 @@ following from @file{@var{objdir}/gcc}:
 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
@@ -1555,12 +2509,12 @@ targets.
 @end table
 
 @node Torture Tests
-@subsection Support for torture testing using multiple options
+@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{gcc/testsuite/lib/torture-options.exp} defines procedures to
+@file{lib/torture-options.exp} defines procedures to
 set up these lists:
 
 @table @code