-@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.
@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
@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.
@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
and @command{dvips}, and PDF manuals by @command{texi2pdf}.
All Texinfo files that are parts of manuals must
-be checked into CVS, even if they are generated files, for the
+be checked into SVN, 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
@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 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 CVS repository, the
+If the front end is added to the official GCC source repository, the
following are also necessary:
@itemize @bullet
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
@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
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}.
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
* 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
@table @code
@item preprocess
Compile with @option{-E} to run only the preprocessor.
-@item assemble
-Compile with @option{-S} to produce an assembly code file.
@item compile
+Compile with @option{-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.
then the test is skipped unless the target system is included in the
list of target triplets or matches the effective-target keyword.
-If the directive includes the optional @samp{@{ xfail @var{selector} @}}
-and the selector is met then the test is expected to fail. For
-@code{dg-do run}, execution is expected to fail but compilation
-is expected to pass.
+If @samp{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
+directive @code{dg-xfail-if}.
@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.
+
+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.
+@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;
see @file{gcc-dg.exp} in the GCC testsuite for the actual directives.
-These directives must appear after any @code{dg-do} directive in the test.
+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.
@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.
+This directive must appear after any @code{dg-do} directive in the test
+and before any @code{dg-additional-sources} directive.
@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
We encourage developers to contribute test cases to Mauve.
+@node LTO Testing
+@subsection 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.
+@end table
+
@node gcov Testing
@subsection Support for testing @command{gcov}
@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
OSDN Git Service
