-@c Copyright (C) 2002, 2003, 2004, 2005, 2007 Free Software Foundation, Inc.
+@c Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009
+@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
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),
including optimizers, support for different target architectures,
@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.
+
@item libada
The Ada runtime library.
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
@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.
@item
Details of the directories of any runtime libraries in
@file{gcc/doc/sourcebuild.texi}.
+@item
+Check targets in Makefile.def for the top-level 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
CVS, but should not delete anything checked into CVS@.
@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}.
* 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
if the target system matches @var{selector}, that replace the default
options used for this set of tests.
-@item @{ dg-add-options @var{feature} ... @}
+@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
and only then in certain modes.
@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.
+
+@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:
+
+@itemize @bullet
+@item the value defined by an earlier @code{dg-timeout} directive in
+the test
+
+@item variable @var{tool_timeout} defined by the set of tests
+
+@item @var{gcc},@var{timeout} set in the target board
+
+@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
@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.
+@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}) and @code{dg-xfail-if}) are met.
@item @{ dg-require-@var{support} args @}
Skip the test if the target does not provide the required support;
@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}
compilation is expected to fail for particular options on particular
targets.
@end table
+
+@node Torture Tests
+@subsection 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
+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