sourcebuild.texi

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

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:

@smallexample
@{ target @{ ! "hppa*-*-* ia64*-*-*" @} @}
@{ target @{ powerpc*-*-* && lp64 @} @}
@{ xfail @{ lp64 || vect_no_align @} @}
@end smallexample

@table @code
@item @{ dg-do @var{do-what-keyword} [@{ target/xfail @var{selector} @}] @}
@var{do-what-keyword} specifies how the test is compiled and whether
it is executed.  It is one of:

@table @code
@item preprocess
Compile with @option{-E} to run only the preprocessor.
@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.
@item run
Produce and run an executable file, which is expected to return
an exit code of 0.
@end table

The default is @code{compile}.  That can be overridden for a set of
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.

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

Use @samp{"*"} for an empty @var{include-opts} list and @samp{""} for
an empty @var{exclude-opts} list.

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

@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
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
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
conditions (which are the same as for @code{dg-skip-if}) are met.

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

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

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

@item @{ dg-bogus @var{regexp} [@var{comment} [@{ target/xfail @var{selector} @} [@var{line}] @}]] @}
This DejaGnu directive appears on a source line that should not get a
message matching @var{regexp}, or else specifies the source line
associated with the bogus message.  It is usually used with @samp{xfail}
to indicate that the message is a known problem for a particular set of
targets.

@item @{ dg-excess-errors @var{comment} [@{ target/xfail @var{selector} @}] @}
This DejaGnu directive indicates that the test is expected to fail due
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-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}.

@item @{ dg-prune-output @var{regexp} @}
Prune messages matching @var{regexp} from test output.

@item @{ dg-additional-files "@var{filelist}" @}
Specify additional files, other than source files, that must be copied
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.

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

The GCC testsuite defines the following directives to be used within
@code{dg-final}.

@table @code
@item cleanup-coverage-files
Removes coverage data 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-tree-dump @var{suffix}
Removes tree dump files matching @var{suffix} which were generated for
this test.

@item cleanup-saved-temps
Removes files for the current test which were kept for @option{--save-temps}.

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

@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-dem @var{regex} [@{ target/xfail @var{selector} @}]
Passes if @var{regex} matches text in the test's demangled assembler output.

@item scan-assembler-dem-not @var{regex} [@{ target/xfail @var{selector} @}]
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-tree-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} @}]
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} @}]
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} @}]
Passes if @var{regex} does not match demangled text in the dump file with
suffix @var{suffix}.

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

@item run-gcov @var{sourcefile}
Check line counts in @command{gcov} tests.

@item run-gcov [branches] [calls] @{ @var{opts} @var{sourcefile} @}
Check branch and/or call counts, in addition to line counts, in
@command{gcov} tests.
@end table
@end table

@node Ada Tests
@subsection 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}

These tests are integrated in the GCC testsuite in the
@file{gcc/testsuite/ada/acats} directory, and
enabled automatically when running @code{make check}, assuming
the Ada language has been enabled when configuring GCC@.

You can also run the Ada testsuite independently, using
@code{make check-ada}, or run a subset of the tests by specifying which
chapter to run, e.g.:

@smallexample
$ 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
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.

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
target, see the small
customization section at the top of @file{run_all.sh}.

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

GCC contains the following C language testsuites, in the
@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