Commands for use in dg-final

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

Scan a particular file

scan-file filenameregexp [ target/xfail {selector }]

Passes if regexp matches text in filename.

scan-file-not filenameregexp [ target/xfail {selector }]

Passes if regexp does not match text in filename.

scan-module moduleregexp [ target/xfail {selector }]

Passes if regexp matches in Fortran module module.

dg-check-dot filename

Passes if filename is a valid .dot file (by running dot -Tpng on it, and verifying the exit code is 0).

scan-sarif-file regexp [ target/xfail {selector }]

Passes if regexp matches text in the file generated by -fdiagnostics-format=sarif-file.

scan-sarif-file-not regexp [ target/xfail {selector }]

Passes if regexp does not match text in the file generated by -fdiagnostics-format=sarif-file.

Scan the assembly 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-times regexnum [ target/xfail {selector }]

Passes if regex is matched exactly num times 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-assembler-symbol-section functionssection [ target/xfail {selector }]

Passes if functions are all in section. The caller needs to allow for USER_LABEL_PREFIX and different section name conventions.

scan-symbol-section filenamefunctionssection [ target/xfail {selector }]

Passes if functions are all in section in filename. The same caveats as for scan-assembler-symbol-section apply.

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.

check-function-bodies prefixterminator [options [ target/xfail {selector }]]

Looks through the source file for comments that give the expected assembly output for selected functions. Each line of expected output starts with the prefix string prefix and the expected output for a function as a whole is followed by a line that starts with the string terminator. Specifying an empty terminator is equivalent to specifying "*/".

options, if specified, is a list of regular expressions, each of which matches a full command-line option. A non-empty list prevents the test from running unless all of the given options are present on the command line. This can help if a source file is compiled both with and without optimization, since it is rarely useful to check the full function body for unoptimized code.

The first line of the expected output for a function fn has the form:

prefix fn:  [{ target/xfail selector }]

Subsequent lines of the expected output also start with prefix. In both cases, whitespace after prefix is not significant.

The test discards assembly directives such as .cfi_startproc and local label definitions such as .LFB0 from the compiler’s assembly output. It then matches the result against the expected output for a function as a single regular expression. This means that later lines can use backslashes to refer back to (...) captures on earlier lines. For example:

/* { dg-final { check-function-bodies "**" "" "-DCHECK_ASM" } } */
...
/*
** add_w0_s8_m:
**  mov     (z[0-9]+\.b), w0
**  add     z0\.b, p0/m, z0\.b, \1
**  ret
*/
svint8_t add_w0_s8_m (...) { ... }
...
/*
** add_b0_s8_m:
**  mov     (z[0-9]+\.b), b0
**  add     z1\.b, p0/m, z1\.b, \1
**  ret
*/
svint8_t add_b0_s8_m (...) { ... }

checks whether the implementations of add_w0_s8_m and add_b0_s8_m match the regular expressions given. The test only runs when -DCHECK_ASM is passed on the command line.

It is possible to create non-capturing multi-line regular expression groups of the form (a|b|...) by putting the (, | and ) on separate lines (each still using prefix). For example:

/*
** cmple_f16_tied:
** (
**  fcmge   p0\.h, p0/z, z1\.h, z0\.h
** |
**  fcmle   p0\.h, p0/z, z0\.h, z1\.h
** )
**  ret
*/
svbool_t cmple_f16_tied (...) { ... }

checks whether cmple_f16_tied is implemented by the fcmge instruction followed by ret or by the fcmle instruction followed by ret. The test is still a single regular rexpression.

A line containing just:

prefix ...

stands for zero or more unmatched lines; the whitespace after prefix is again not significant.

Scan optimization dump files

These commands are available for kind of tree, ltrans-tree, offload-tree, rtl, offload-rtl, ipa, and wpa-ipa.

scan-kind-dump regexsuffix [ target/xfail {selector }]

Passes if regex matches text in the dump file with suffix suffix.

scan-kind-dump-not regexsuffix [ target/xfail {selector }]

Passes if regex does not match text in the dump file with suffix suffix.

scan-kind-dump-times regexnumsuffix [ target/xfail {selector }]

Passes if regex is found exactly num times in the dump file with suffix suffix.

scan-kind-dump-dem regexsuffix [ target/xfail {selector }]

Passes if regex matches demangled text in the dump file with suffix suffix.

scan-kind-dump-dem-not regexsuffix [ target/xfail {selector }]

Passes if regex does not match demangled text in the dump file with suffix suffix.

The suffix argument which describes the dump file to be scanned may contain a glob pattern that must expand to exactly one file name. This is useful if, e.g., different pass instances are executed depending on torture testing command-line flags, producing dump files whose names differ only in their pass instance number suffix. For example, to scan instances 1, 2, 3 of a tree pass ‘mypass’ for occurrences of the string ‘code has been optimized’, use:

/* { dg-options "-fdump-tree-mypass" } */
/* { dg-final { scan-tree-dump "code has been optimized" "mypass\[1-3\]" } } */

Check for output files

output-exists [ target/xfail {selector }]

Passes if compiler output file exists.

output-exists-not [ target/xfail {selector }]

Passes if compiler output file does not exist.

scan-symbol regexp [ target/xfail {selector }]

Passes if the pattern is present in the final executable.

scan-symbol-not regexp [ target/xfail {selector }]

Passes if the pattern is absent from the final executable.

Checks for gcov tests

run-gcov sourcefile

Check line counts in gcov tests.

run-gcov [branches] [calls] {optssourcefile }

Check branch and/or call counts, in addition to line counts, in gcov tests.

run-gcov-pytest {sourcefilepytest_file }

Check output of gcov intermediate format with a pytest script.

Clean up generated test files

Usually the test-framework removes files that were generated during testing. If a testcase, for example, uses any dumping mechanism to inspect a passes dump file, the testsuite recognized the dump option passed to the tool and schedules a final cleanup to remove these files.

There are, however, following additional cleanup directives that can be used to annotate a testcase “manually”.

cleanup-coverage-files

Removes coverage data files generated for this test.

cleanup-modules "list-of-extra-modules"

Removes Fortran module files generated for this test, excluding the module names listed in keep-modules. Cleaning up module files is usually done automatically by the testsuite by looking at the source files and removing the modules after the test has been executed.

module MoD1
end module MoD1
module Mod2
end module Mod2
module moD3
end module moD3
module mod4
end module mod4
! { dg-final { cleanup-modules "mod1 mod2" } } ! redundant
! { dg-final { keep-modules "mod3 mod4" } }

keep-modules "list-of-modules-not-to-delete"

Whitespace separated list of module names that should not be deleted by cleanup-modules. If the list of modules is empty, all modules defined in this file are kept.

module maybe_unneeded
end module maybe_unneeded
module keep1
end module keep1
module keep2
end module keep2
! { dg-final { keep-modules "keep1 keep2" } } ! just keep these two
! { dg-final { keep-modules "" } } ! keep all

dg-keep-saved-temps "list-of-suffixes-not-to-delete"

Whitespace separated list of suffixes that should not be deleted automatically in a testcase that uses -save-temps.

// { dg-options "-save-temps -fpch-preprocess -I." }
int main() { return 0; }
// { dg-keep-saved-temps ".s" } ! just keep assembler file
// { dg-keep-saved-temps ".s" ".i" } ! ... and .i
// { dg-keep-saved-temps ".ii" ".o" } ! or just .ii and .o

cleanup-profile-file

Removes profiling files generated for this test.