This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [doc patch] describe test directives in internals manual


On Tue, Jan 11, 2005 at 04:05:36PM -0800, Janis Johnson wrote:
> This patch adds a new section to the GCC Internals Manual to describe
> directives used within DejaGnu tests in the GCC testsuite.

Here's the info version, for people who don't read .texi files.

Directives used within DejaGnu tests
------------------------------------

 Test directives appear within comments in a test source file and begin
with `dg-'.  Some of these are defined within DegaGnu 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 which are usually preceded by
the keyword `target' or `xfail'.  A selector is one or more target
triplets, possibly including wildcard characters, or else a single
effective-target keyword.  Depending on the context, the selector
specifies whether a test is skipped and reported as unsupported or is
expected to fail.  Use `*-*-*' to match any target.

 Effective-target keywords are defined in `target-supports.exp' in the
GCC testsuite or, in the case of unusual effective targets that are
used only for a limited number of tests, in local `.exp' files.  There
is no mechanism to combine or negate effective-target keywords.

`{ dg-do DO-WHAT-KEYWORD [{ target/xfail SELECTOR }] }'
     This DejaGnu directive must appear before test directives that are
     defined within the GCC test framework.

     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.

    `assemble'
          Compile with `-S' to produce an assembly code file.

    `compile'
          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, expected to exit with 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 is included in the
     list of target triplets or matches the effective-target keyword.

     If the directive includes the optional `{ xfail SELECTOR }' and
     the selector is met then the test is expected to fail.  For `dg-do
     run', execution is expected to fail but compilation is expected to
     pass.

`{ 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-skip-if COMMENT { SELECTOR } { INCLUDE-OPTS } { EXCLUDE-OPTS } }'
     Skip the test if the test system is included in SELECTOR and each
     of the options in INCLUDE-OPTS will be used to compile the test
     and none of the options in EXCLUDE-OPTS will be used to compile
     the test.

     Use `"*"' for an empty INCLUDE-OPTS list and `""' for an empty
     EXCLUDE-OPTS list.

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

`{ dg-require-SUPPORT args }'
     Skip the test if the target does not provide the required support;
     see `gcc-dg.exp' in the GCC testsuite for the actual directives.
     These directives must appear after any `dg-do' directive in the
     test.  They require at least one argument, which can be an empty
     string if the specific procedure does not examine the argument.

`{ dg-require-effective-target 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 `dg-do' directive in the test.

`{ 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-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 error messages not specified
     by other directives are expected somewhere in the test.

`{ 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-prune-output REGEXP }'
     Prune messages matching REGEXP from test output.

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

     The GCC testsuite defines the following directives to be used
     within `dg-final'.

    `scan-file FILENAME REGEXP [{ target/xfail SELECTOR }]'
          Passes if REGEXP matches text in FILENAME.

    `scan-file-not FILENAME REGEXP [{ target/xfail SELECTOR }]'
          Passes if REGEXP does not match text in FILENAME.

    `scan-hidden SYMBOL [{ target/xfail SELECTOR }]'
          Passes if SYMBOL is defined as a hidden symbol in the test's
          assembly output.

    `scan-not-hidden SYMBOL [{ target/xfail SELECTOR }]'
          Passes if SYMBOL is not defined as a hidden symbol in the
          test's assembly output.

    `scan-assembler-times REGEX NUM [{ target/xfail SELECTOR }]'
          Passes if REGEX is matched exactly NUM times in the test's
          assembler output.

    `scan-assembler REGEX [{ target/xfail SELECTOR }]'
          Passes if REGEX matches text in the test's assembler output.

    `scan-assembler-not REGEX [{ target/xfail SELECTOR }]'
          Passes if REGEX does not match text in the test's assembler
          output.

    `scan-assembler-dem REGEX [{ target/xfail SELECTOR }]'
          Passes if REGEX matches text in the test's demangled
          assembler output.

    `scan-assembler-dem-not REGEX [{ target/xfail SELECTOR }]'
          Passes if REGEX does not match text in the test's demangled
          assembler output.

    `scan-tree-dump-times REGEX NUM SUFFIX [{ target/xfail SELECTOR }]'
          Passes if REGEX is found exactly NUM times in the dump file
          with suffix SUFFIX.

    `scan-tree-dump REGEX SUFFIX [{ target/xfail SELECTOR }]'
          Passes if REGEX matches text in the dump file with suffix
          SUFFIX.

    `scan-tree-dump-not REGEX SUFFIX [{ target/xfail SELECTOR }]'
          Passes if REGEX does not match text in the dump file with
          suffix SUFFIX.

    `scan-tree-dump-dem REGEX SUFFIX [{ target/xfail SELECTOR }]'
          Passes if REGEX matches demangled text in the dump file with
          suffix SUFFIX.

    `scan-tree-dump-dem-not REGEX SUFFIX [{ target/xfail SELECTOR }]'
          Passes if REGEX does not match demangled text in the dump
          file with suffix SUFFIX.

    `run-gcov SOURCEFILE'
          Check line counts in `gcov' tests.

    `run-gcov [branches] [calls] { OPTS SOURCEFILE }'
          Check branch and/or call counts, in addition to line counts,
          in `gcov' tests.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]