sourcebuild.texi

理解和实践操作系统的一本好书

@option{-DWIDE}.
@item gcc.dg/noncompile
This subdirectory contains tests of code that should not compile and
does not need any special compilation options.  They are run with
multiple optimization options, since sometimes invalid code crashes
the compiler with optimization.
@item gcc.dg/special
FIXME: describe this.

@item gcc.c-torture
This contains particular code fragments which have historically broken easily.
These tests are run with multiple optimization options, so tests for features
which only break at some optimization levels belong here.  This also contains
tests to check that certain optimizations occur.  It might be worthwhile to
separate the correctness tests cleanly from the code quality tests, but
it hasn't been done yet.

@item gcc.c-torture/compat
FIXME: describe this.

This directory should probably not be used for new tests.
@item gcc.c-torture/compile
This testsuite contains test cases that should compile, but do not
need to link or run.  These test cases are compiled with several
different combinations of optimization options.  All warnings are
disabled for these test cases, so this directory is not suitable if
you wish to test for the presence or absence of compiler warnings.
While special options can be set, and tests disabled on specific
platforms, by the use of @file{.x} files, mostly these test cases
should not contain platform dependencies.  FIXME: discuss how defines
such as @code{NO_LABEL_VALUES} and @code{STACK_SIZE} are used.
@item gcc.c-torture/execute
This testsuite contains test cases that should compile, link and run;
otherwise the same comments as for @file{gcc.c-torture/compile} apply.
@item gcc.c-torture/execute/ieee
This contains tests which are specific to IEEE floating point.
@item gcc.c-torture/unsorted
FIXME: describe this.

This directory should probably not be used for new tests.
@item gcc.c-torture/misc-tests
This directory contains C tests that require special handling.  Some
of these tests have individual expect files, and others share
special-purpose expect files:

@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 testsuites.

Runtime tests are executed via @samp{make check} in the
@file{@var{target}/libjava/testsuite} directory in the build
tree.  Additional runtime tests can be checked into this testsuite.

Regression testing of the core packages in libgcj is also covered by the
Mauve testsuite.  The @uref{http://sourceware.org/mauve/,,Mauve Project}
develops tests for the Java Class Libraries.  These tests are run as part
of libgcj testing by placing the Mauve tree within the libjava testsuite
sources at @file{libjava/testsuite/libjava.mauve/mauve}, or by specifying
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.

We encourage developers to contribute test cases to Mauve.

@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 @option{-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)  /* @r{branch(27 50 75)} */
                                /* @r{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., @command{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 testsuites that complement ABI testsuites.

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.
You can specify pairs of sets of compiler options.  The first element
of such a pair specifies options used with the GCC under test, and the
second element of the pair specifies options used with the alternate
compiler.  Each test is 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}@}]
  @dots{}[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 @option{-g -O0} by the compiler under
test and with @option{-O3} by the alternate compiler.  The test is
built a second time using @option{-fpic} by the compiler under test
and @option{-fPIC -O2} by the alternate compiler.

An alternate compiler is specified by defining an environment
variable to be the full pathname of an installed compiler; for C
define @env{ALT_CC_UNDER_TEST}, and for C++ define
@env{ALT_CXX_UNDER_TEST}.  These 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_CC_UNDER_TEST} or
@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.

The binary compatibility tests support a small number of test framework
commands that appear within comments in a test file.

@table @code
@item dg-require-*
These commands can be used in @file{@var{testname}_main.@var{suffix}}
to skip the test if specific support is not available on the target.

@item dg-options
The specified options are used for compiling this particular source
file, appended to the options from @env{COMPAT_OPTIONS}.  When this
command appears in @file{@var{testname}_main.@var{suffix}} the options
are also used to link the test program.

@item dg-xfail-if
This command can be used in a secondary source file to specify that
compilation is expected to fail for particular options on particular
targets.
@end table