-@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c Copyright (C) 2002, 2003 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@item config
Configuration files for supported architectures and operating
systems. @xref{Back End, , Anatomy of a Target Back End}, for
-details of the files in thie directory.
+details of the files in this directory.
@item doc
Texinfo documentation for GCC, together with automatically generated
contains @file{gcc.pot}, the template for these message catalogues,
@file{exgettext}, a wrapper around @command{gettext} to extract the
messages from the GCC sources and create @file{gcc.pot}, which is run
-by @command{make gcc.pot}, and @file{EXCLUDES}, a list of files from
+by @samp{make gcc.pot}, and @file{EXCLUDES}, a list of files from
which messages should not be extracted.
@item testsuite
headers to work with GCC, some other headers may also be installed in
@file{@var{libsubdir}/include}. @file{config.gcc} may set
@code{extra_headers}; this specifies additional headers under
-@file{config} to be installed on some systems. GCC normally installs
-a @code{<float.h>} file; these are kept as
-@file{config/float-@var{format}.h}, where @var{format} is specified by
-a @code{float_format} setting in @file{config.gcc}, and a setting
-@samp{float_format=none} disables installation of this header. GCC
-also installs its own version of @code{<limits.h>}; this is generated
+@file{config} to be installed on some systems.
+
+GCC installs its own version of @code{<float.h>}, from @file{ginclude/float.h}.
+This is done to cope with command-line options that change the
+representation of floating point numbers.
+
+GCC also installs its own version of @code{<limits.h>}; this is generated
from @file{glimits.h}, together with @file{limitx.h} and
@file{limity.h} if the system also has its own version of
@code{<limits.h>}. (GCC provides its own header because it is
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 @command{make dvi}. In addition, some man pages are
+generated by @samp{make dvi}. 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
A copy of @file{texinfo.tex} known to work with the GCC manuals.
@end table
-DVI formatted manuals are generated by @command{make dvi}, which uses
+DVI formatted manuals are generated by @samp{make dvi}, which uses
@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}). Info
-manuals are generated by @command{make info} (which is run as part of
+manuals are generated by @samp{make info} (which is run as part of
a bootstrap); this generates the manuals in the source directory,
using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
and they are included in release distributions.
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
-@command{makeinfo --html} and PostScript manuals by @command{texi2dvi}
+@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
generation of online manuals to work.
@itemize @bullet
@item
-At least one GNATS category for bugs in that front end and runtime
+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}, and in @file{gnats.html} on the GCC web site, as
-well as being added to the GNATS database.
+@file{gcc/gccbug.in}, as well as being added to the Bugzilla database.
@item
Normally, one or more maintainers of that front end listed in
@file{MAINTAINERS}.
@itemx start.encap
@itemx rest.encap
FIXME: exactly what goes in each of these targets?
+@item tags
+Build an @command{etags} @file{TAGS} file in the language subdirectory
+in the source tree.
@item info
Build info documentation for the front end, in the source directory.
-This target is only called by @command{make bootstrap} if a suitable
+This target is only called by @samp{make bootstrap} if a suitable
version of @command{makeinfo} is available, so does not need to check
for this, and should fail if an error occurs.
@item dvi
@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-options.h
-This file provides entries for @code{documented_lang_options} in
-@file{toplev.c} describing command-line options the front end accepts
-for @option{--help} output.
+@item lang.opt
+This file registers the set of switches that the front end accepts on
+the command line, and their --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
here; FIXME: document the others.
@menu
-* Test Idioms:: Idioms used in test suite code.
-* C Tests:: The C language test suites.
+* Test Idioms:: Idioms used in test suite code.
+* C Tests:: The C language test suites.
+* libgcj Tests:: The Java library test suites.
+* gcov Testing:: Support for testing gcov.
+* profopt Testing:: Support for testing profile-directed optimizations.
+* compat Testing:: Support for testing binary compatibility.
@end menu
@node Test Idioms
@code{static} to call @code{abort ()} (although redeclaring a function
as static may not work on all targets).
+All testcases must be portable. Target-specific testcases must have
+appropriate code to avoid causing failures on unsupported systems;
+unfortunately, the mechanisms for this differ by directory.
+
FIXME: discuss non-C test suites here.
@node C Tests
@file{gcc/testsuite} directory:
@table @file
+@item gcc.dg
+This contains tests of particular features of the C compiler, using the
+more modern @samp{dg} harness. Correctness tests for various compiler
+features should go here if possible.
+
+Magic comments determine whether the file
+is preprocessed, compiled, linked or run. In these tests, error and warning
+message texts are compared against expected texts or regular expressions
+given in comments. These tests are run with the options @samp{-ansi -pedantic}
+unless other options are given in the test. Except as noted below they
+are not run with multiple optimization options.
+@item gcc.dg/compat
+This subdirectory contains tests for binary compatibility using
+@file{compat.exp}, which in turn uses the language-independent support
+(@pxref{compat Testing, , Support for testing binary compatibility}).
+@item gcc.dg/cpp
+This subdirectory contains tests of the preprocessor.
+@item gcc.dg/debug
+This subdirectory contains tests for debug formats. Tests in this
+subdirectory are run for each debug format that the compiler supports.
+@item gcc.dg/format
+This subdirectory contains tests of the @option{-Wformat} format
+checking. Tests in this directory are run with and without
+@option{-DWIDE}.
+@item gcc.dg/noncompile
+This subdirectory contains tests of code that should not compile and
+does not need any special compilation options. They are run with
+multiple optimization options, since sometimes invalid code crashes
+the compiler with optimization.
+@item gcc.dg/special
+FIXME: describe this.
+
+@item gcc.c-torture
+This contains particular code fragments which have historically broken easily.
+These tests are run with multiple optimization options, so tests for features
+which only break at some optimization levels belong here. This also contains
+tests to check that certain optimizations occur. It might be worthwhile to
+separate the correctness tests cleanly from the code quality tests, but
+it hasn't been done yet.
+
@item gcc.c-torture/compat
FIXME: describe this.
@item gcc.c-torture/execute
This test suite 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.dg
-This test suite contains tests using the more modern @samp{dg} harness.
-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/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/misc-tests
-FIXME: describe this, when it should be used for new tests and when it
-shouldn't.
+This directory contains C tests that require special handling. Some
+of these tests have individual expect files, and others share
+special-purpose expect files:
+
+@table @file
+@item @code{bprob*.c}
+Test @option{-fbranch-probabilities} using @file{bprob.exp}, which
+in turn uses the generic, language-independent framework
+(@pxref{profopt Testing, , Support for testing profile-directed
+optimizations}).
+
+@item @code{dg-*.c}
+Test the testsuite itself using @file{dg-test.exp}.
+
+@item @code{gcov*.c}
+Test @command{gcov} output using @file{gcov.exp}, which in turn uses the
+language-independent support (@pxref{gcov Testing, , Support for testing gcov}).
+
+@item @code{i386-pf-*.c}
+Test i386-specific support for data prefetch using @file{i386-prefetch.exp}.
+@end table
+
@end table
FIXME: merge in @file{testsuite/README.gcc} and discuss the format of
test cases and magic comments more.
+
+@node libgcj Tests
+@subsection The Java library test suites.
+
+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 test suite. The @uref{http://sources.redhat.com/mauve/,,Mauve Project}
+develops tests for the Java Class Libraries. These tests are run as part
+of libgcj testing by placing the Mauve tree within the libjava testsuite
+sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
+the location of that tree when invoking @samp{make}, as in
+@samp{make MAUVEDIR=~/mauve check}.
+
+To detect regressions, a mechanism in @file{mauve.exp} compares the
+failures for a test run against the list of expected failures in
+@file{libjava/testsuite/libjava.mauve/xfails} from the source hierarchy.
+Update this file when adding new failing tests to Mauve, or when fixing
+bugs in libgcj that had caused Mauve test failures.
+
+The @uref{http://oss.software.ibm.com/developerworks/opensource/jacks/,,
+Jacks} project provides a test suite for Java compilers that can be used
+to test changes that affect the GCJ front end. This test suite 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 and Jacks.
+
+@node gcov Testing
+@subsection Support for testing @command{gcov}
+
+Language-independent support for testing @command{gcov}, and for checking
+that branch profiling produces expected values, is provided by the
+expect file @file{gcov.exp}. @command{gcov} tests also rely on procedures
+in @file{gcc.dg.exp} to compile and run the test program. A typical
+@command{gcov} test contains the following DejaGNU commands within comments:
+
+@smallexample
+@{ dg-options "-fprofile-arcs -ftest-coverage" @}
+@{ dg-do run @{ target native @} @}
+@{ dg-final @{ run-gcov sourcefile @} @}
+@end smallexample
+
+Checks of @command{gcov} output can include line counts, branch percentages,
+and call return percentages. All of these checks are requested via
+commands that appear in comments in the test's source file.
+Commands to check line counts are processed by default.
+Commands to check branch percentages and call return percentages are
+processed if the @command{run-gcov} command has arguments @code{branches}
+or @code{calls}, respectively. For example, the following specifies
+checking both, as well as passing @code{-b} to @command{gcov}:
+
+@smallexample
+@{ dg-final @{ run-gcov branches calls @{ -b sourcefile @} @} @}
+@end smallexample
+
+A line count command appears within a comment on the source line
+that is expected to get the specified count and has the form
+@code{count(@var{cnt})}. A test should only check line counts for
+lines that will get the same count for any architecture.
+
+Commands to check branch percentages (@code{branch}) and call
+return percentages (@code{returns}) are very similar to each other.
+A beginning command appears on or before the first of a range of
+lines that will report the percentage, and the ending command
+follows that range of lines. The beginning command can include a
+list of percentages, all of which are expected to be found within
+the range. A range is terminated by the next command of the same
+kind. A command @code{branch(end)} or @code{returns(end)} marks
+the end of a range without starting a new one. For example:
+
+@smallexample
+if (i > 10 && j > i && j < 20) /* branch(27 50 75) */
+ /* branch(end) */
+ foo (i, j);
+@end smallexample
+
+For a call return percentage, the value specified is the
+percentage of calls reported to return. For a branch percentage,
+the value is either the expected percentage or 100 minus that
+value, since the direction of a branch can differ depending on the
+target or the optimization level.
+
+Not all branches and calls need to be checked. A test should not
+check for branches that might be optimized away or replaced with
+predicated instructions. Don't check for calls inserted by the
+compiler or ones that might be inlined or optimized away.
+
+A single test can check for combinations of line counts, branch
+percentages, and call return percentages. The command to check a
+line count must appear on the line that will report that count, but
+commands to check branch percentages and call return percentages can
+bracket the lines that report them.
+
+@node profopt Testing
+@subsection Support for testing profile-directed optimizations
+
+The file @file{profopt.exp} provides language-independent support for
+checking correct execution of a test built with profile-directed
+optimization. This testing requires that a test program be built and
+executed twice. The first time it is compiled to generate profile
+data, and the second time it is compiled to use the data that was
+generated during the first execution. The second execution is to
+verify that the test produces the expected results.
+
+To check that the optimization actually generated better code, a
+test can be built and run a third time with normal optimizations to
+verify that the performance is better with the profile-directed
+optimizations. @file{profopt.exp} has the beginnings of this kind
+of support.
+
+@file{profopt.exp} provides generic support for profile-directed
+optimizations. Each set of tests that uses it provides information
+about a specific optimization:
+
+@table @code
+@item tool
+tool being tested, e.g., gcc
+
+@item profile_option
+options used to generate profile data
+
+@item feedback_option
+options used to optimize using that profile data
+
+@item prof_ext
+suffix of profile data files
+
+@item PROFOPT_OPTIONS
+list of options with which to run each test, similar to the lists for
+torture tests
+@end table
+
+@node compat Testing
+@subsection Support for testing binary compatibility
+
+The file @file{compat.exp} provides language-independent support for
+binary compatibility testing. It supports testing interoperability
+of two compilers that follow the same ABI, or of multiple sets of
+compiler options that should not affect binary compatibility.
+It is intended to be used for test suites that complement ABI test
+suites.
+
+A test supported by this framework has three parts, each in a
+separate source file: a main program and two pieces that interact
+with each other to split up the functionality being tested.
+
+@table @file
+@item @var{testname}_main.@var{suffix}
+Contains the main program, which calls a function in file
+@file{@var{testname}_x.@var{suffix}}.
+
+@item @var{testname}_x.@var{suffix}
+Contains at least one call to a function in
+@file{@var{testname}_y.@var{suffix}}.
+
+@item @var{testname}_y.@var{suffix}
+Shares data with, or gets arguments from,
+@file{@var{testname}_x.@var{suffix}}.
+@end table
+
+Within each test, the main program and one functional piece are
+compiled by the GCC under test. The other piece can be compiled by
+an alternate compiler. If no alternate compiler is specified,
+then all three source files are all compiled by the GCC under test.
+It's also possible to specify a pair of lists of compiler options,
+one list for each compiler, so that each test will be compiled with
+each pair of options.
+
+@file{compat.exp} defines default pairs of compiler options.
+These can be overridden by defining the environment variable
+@env{COMPAT_OPTIONS} as:
+
+@smallexample
+COMPAT_OPTIONS="[list [list @{@var{tst1}@} @{@var{alt1}@}]
+ ...[list @{@var{tstn}@} @{@var{altn}@}]]"
+@end smallexample
+
+where @var{tsti} and @var{alti} are lists of options, with @var{tsti}
+used by the compiler under test and @var{alti} used by the alternate
+compiler. For example, with
+@code{[list [list @{-g -O0@} @{-O3@}] [list @{-fpic@} @{-fPIC -O2@}]]},
+the test is first built with @code{-g -O0} by the compiler under
+test and with @code{-O3} by the alternate compiler. The test is
+built a second time using @code{-fpic} by the compiler under test
+and @code{-fPIC -O2} by the alternate compiler.
+
+An alternate compiler is specified by defining an environment
+variable; for C++ define @env{ALT_CXX_UNDER_TEST} to be the full
+pathname of an installed compiler. That will be written to the
+@file{site.exp} file used by DejaGNU. The default is to build each
+test with the compiler under test using the first of each pair of
+compiler options from @env{COMPAT_OPTIONS}. When
+@env{ALT_CXX_UNDER_TEST} is @code{same}, each test is built using
+the compiler under test but with combinations of the options from
+@env{COMPAT_OPTIONS}.
+
+To run only the C++ compatibility suite using the compiler under test
+and another version of GCC using specific compiler options, do the
+following from @file{@var{objdir}/gcc}:
+
+@smallexample
+rm site.exp
+make -k \
+ ALT_CXX_UNDER_TEST=$@{alt_prefix@}/bin/g++ \
+ COMPAT_OPTIONS="lists as shown above" \
+ check-c++ \
+ RUNTESTFLAGS="compat.exp"
+@end smallexample
+
+A test that fails when the source files are compiled with different
+compilers, but passes when the files are compiled with the same
+compiler, demonstrates incompatibility of the generated code or
+runtime support. A test that fails for the alternate compiler but
+passes for the compiler under test probably tests for a bug that was
+fixed in the compiler under test but is present in the alternate
+compiler.
OSDN Git Service
