| GNU Compiler Collection (GCC) Internals: Directives |
|---|
Next: Selectors, Up: Test Directives [Contents][Index]
Test directives appear within comments in a test source file and begin
with dg-. Some of these are defined within DejaGnu and others
are local to the GCC testsuite.
The order in which test directives appear in a test can be important: directives local to GCC sometimes override information used by the DejaGnu directives, which know nothing about the GCC directives, so the DejaGnu directives must precede GCC directives.
Several test directives include selectors (see Selectors)
which are usually preceded by the keyword target or xfail.
{ dg-do do-what-keyword [{ target/xfail selector }] }
do-what-keyword specifies how the test is compiled and whether it is executed. It is one of:
preprocess
Compile with -E to run only the preprocessor.
compile
Compile with -S to produce an assembly code file.
assemble
Compile with -c to produce a relocatable object file.
link
Compile, assemble, and link to produce an executable file.
run
Produce and run an executable file, which is expected to return an exit code of 0.
The default is compile. That can be overridden for a set of
tests by redefining dg-do-what-default within the .exp
file for those tests.
If the directive includes the optional ‘{ target selector }’ then the test is skipped unless the target system matches the selector.
If do-what-keyword is run and the directive includes
the optional ‘{ xfail selector }’ and the selector is met
then the test is expected to fail. The xfail clause is ignored
for other values of do-what-keyword; those tests can use
directive dg-xfail-if.
{ dg-options options [{ target selector }] }
This DejaGnu directive provides a list of compiler options, to be used if the target system matches selector, that replace the default options used for this set of tests.
{ dg-add-options feature … }
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 dg-options directives.
For supported values of feature see Add Options.
{ dg-additional-options options [{ target selector }] }
This directive provides a list of compiler options, to be used if the target system matches selector, that are added to the default options used for this set of tests.
The normal timeout limit, in seconds, is found by searching the following in order:
dg-timeout directive in
the test
{ dg-timeout n [{target selector }] }
Set the time limit for the compilation and for the execution of the test to the specified number of seconds.
{ dg-timeout-factor x [{ target selector }] }
Multiply the normal time limit for compilation and execution of the test by the specified floating-point factor.
{ dg-skip-if comment { selector } [{ include-opts } [{ exclude-opts }]] }
Arguments include-opts and exclude-opts are lists in which each element is a string of zero or more GCC options. Skip the test if all of the following conditions are met:
For example, to skip a test if option -Os is present:
/* { dg-skip-if "" { *-*-* } { "-Os" } { "" } } */
To skip a test if both options -O2 and -g are present:
/* { dg-skip-if "" { *-*-* } { "-O2 -g" } { "" } } */
To skip a test if either -O2 or -O3 is present:
/* { dg-skip-if "" { *-*-* } { "-O2" "-O3" } { "" } } */
To skip a test unless option -Os is present:
/* { dg-skip-if "" { *-*-* } { "*" } { "-Os" } } */
To skip a test if either -O2 or -O3 is used with -g
but not if -fpic is also present:
/* { dg-skip-if "" { *-*-* } { "-O2 -g" "-O3 -g" } { "-fpic" } } */
{ dg-require-effective-target keyword [{ selector }] }
Skip the test if the test target, including current multilib flags,
is not covered by the effective-target keyword.
If the directive includes the optional ‘{ selector }’
then the effective-target test is only performed if the target system
matches the selector.
This directive must appear after any dg-do directive in the test
and before any dg-additional-sources directive.
See Effective-Target Keywords.
{ dg-require-support args }
Skip the test if the target does not provide the required support.
These directives must appear after any dg-do directive in the test
and before any 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.
See Require Support, for a complete list of these directives.
{ dg-xfail-if comment { selector } [{ include-opts } [{ exclude-opts }]] }
Expect the test to fail if the conditions (which are the same as for
dg-skip-if) are met. This does not affect the execute step.
{ dg-xfail-run-if comment { selector } [{ include-opts } [{ exclude-opts }]] }
Expect the execute step of a test to fail if the conditions (which are
the same as for dg-skip-if) are met.
{ dg-shouldfail comment [{ selector } [{ include-opts } [{ exclude-opts }]]] }
Expect the test executable to return a nonzero exit status if the
conditions (which are the same as for dg-skip-if) are met.
{ dg-error regexp [comment [{ target/xfail selector } [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 regexp then the check fails and
comment is included in the FAIL message. The check does
not look for the string ‘error’ unless it is part of regexp.
{ dg-warning regexp [comment [{ target/xfail selector } [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 regexp then the check fails and
comment is included in the FAIL message. The check does
not look for the string ‘warning’ unless it is part of regexp.
{ dg-message regexp [comment [{ target/xfail selector } [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 regexp then the check fails and comment is
included in the FAIL message.
{ dg-bogus regexp [comment [{ target/xfail selector } [line] ]] }
This DejaGnu directive appears on a source line that should not get a message matching regexp, or else specifies the source line associated with the bogus message. It is usually used with ‘xfail’ to indicate that the message is a known problem for a particular set of targets.
{ dg-excess-errors comment [{ target/xfail selector }] }
This DejaGnu directive indicates that the test is expected to fail due to compiler messages that are not handled by ‘dg-error’, ‘dg-warning’ or ‘dg-bogus’. For this directive ‘xfail’ has the same effect as ‘target’.
{ dg-prune-output regexp }
Prune messages matching regexp from the test output.
{ dg-output regexp [{ target/xfail selector }] }
This DejaGnu directive compares regexp to the combined output that the test executable writes to stdout and stderr.
{ dg-additional-files "filelist" }
Specify additional files, other than source files, that must be copied to the system where the compiler runs.
{ dg-additional-sources "filelist" }
Specify additional source files to appear in the compile line following the main test file.
{ dg-final { 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 ‘dg-final’ commands are processed in the order in which
they appear in the source file. See Final Actions, for a list
of directives that can be used within dg-final.
Next: Selectors, Up: Test Directives [Contents][Index]