dg-final ¶The GCC testsuite defines the following directives to be used withindg-final.
gcov testsscan-filefilenameregexp [{ target/xfailselector }]Passes ifregexp matches text infilename.
scan-file-notfilenameregexp [{ target/xfailselector }]Passes ifregexp does not match text infilename.
scan-modulemoduleregexp [{ target/xfailselector }]Passes ifregexp matches in Fortran modulemodule.
dg-check-dotfilenamePasses iffilename is a valid.dot file (by runningdot -Tpng on it, and verifying the exit code is 0).
scan-sarif-fileregexp [{ target/xfailselector }]Passes ifregexp matches text in the file generated by-fdiagnostics-format=sarif-file.
scan-sarif-file-notregexp [{ target/xfailselector }]Passes ifregexp does not match text in the file generated by-fdiagnostics-format=sarif-file.
scan-assemblerregex [{ target/xfailselector }]Passes ifregex matches text in the test’s assembler output,excluding LTO sections.
scan-raw-assemblerregex [{ target/xfailselector }]Passes ifregex matches text in the test’s assembler output,including LTO sections.
scan-assembler-notregex [{ target/xfailselector }]Passes ifregex does not match text in the test’s assembler output,excluding LTO sections.
scan-assembler-timesregexnum [{ target/xfailselector }]Passes ifregex is matched exactlynum times in the test’sassembler output, excluding LTO sections.
scan-assembler-boundregexcmpnum [{ target/xfailselector }]Passes ifregex is matchedcmpnum times in the test’sassembler output, excluding LTO sections.cmp is a comparitor.
scan-assembler-demregex [{ target/xfailselector }]Passes ifregex matches text in the test’s demangled assembler output,excluding LTO sections.
scan-assembler-dem-notregex [{ target/xfailselector }]Passes ifregex does not match text in the test’s demangled assembleroutput, excluding LTO sections.
scan-assembler-symbol-sectionfunctionssection [{ target/xfailselector }]Passes iffunctions are all insection. The caller needs toallow forUSER_LABEL_PREFIX and different section name conventions.
scan-symbol-sectionfilenamefunctionssection [{ target/xfailselector }]Passes iffunctions are all insectioninfilename.The same caveats as forscan-assembler-symbol-section apply.
scan-hiddensymbol [{ target/xfailselector }]Passes ifsymbol is defined as a hidden symbol in the test’sassembly output.
scan-not-hiddensymbol [{ target/xfailselector }]Passes ifsymbol is not defined as a hidden symbol in the test’sassembly output.
check-function-bodiesprefixterminator [options [{ target/xfailselector } [matched]]]Looks through the source file for comments that give the expected assemblyoutput for selected functions. Each line of expected output starts with theprefix stringprefix and the expected output for a function as a wholeis followed by a line that starts with the stringterminator.Specifying an empty terminator is equivalent to specifying ‘"*/"’.
options, if specified, is a list of regular expressions, each ofwhich matches a full command-line option. A non-empty list preventsthe test from running unless all of the given options are present on thecommand line. This can help if a source file is compiled both withand without optimization, since it is rarely useful to check the fullfunction body for unoptimized code.
The first line of the expected output for a functionfn has the form:
prefixfn: [{ target/xfailselector }]Subsequent lines of the expected output also start withprefix.In both cases, whitespace afterprefix is not significant.
Depending on the configuration (seeconfigure_check-function-bodies ingcc/testsuite/lib/scanasm.exp), the test may discard from thecompiler’s assembly output directives such as.cfi_startproc,local label definitions such as.LFB0, and more. This behaviorcan be overridden using the optionalmatched argument, whichspecifies a regexp for lines that should not be discarded in this way.
The test then matches the result against the expectedoutput for a function as a single regular expression. This means thatlater 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**addz0\.b, p0/m, z0\.b, \1**ret*/svint8_t add_w0_s8_m (…) { … }…/*** add_b0_s8_m:**mov(z[0-9]+\.b), b0**addz1\.b, p0/m, z1\.b, \1**ret*/svint8_t add_b0_s8_m (…) { … }checks whether the implementations ofadd_w0_s8_m andadd_b0_s8_m match the regular expressions given. The test onlyruns when ‘-DCHECK_ASM’ is passed on the command line.
It is possible to create non-capturing multi-line regular expressiongroups of the form ‘(a|b|…)’ by putting the‘(’, ‘|’ and ‘)’ on separate lines (each still usingprefix). For example:
/*** cmple_f16_tied:** (**fcmgep0\.h, p0/z, z1\.h, z0\.h** |**fcmlep0\.h, p0/z, z0\.h, z1\.h** )**ret*/svbool_t cmple_f16_tied (…) { … }checks whethercmple_f16_tied is implemented by thefcmge instruction followed byret or by thefcmle instruction followed byret. The test isstill a single regular rexpression.
A line containing just:
prefix ...
stands for zero or more unmatched lines; the whitespace afterprefix is again not significant.
These commands are available forkind oftree,ltrans-tree,offload-tree,rtl,ltrans-rtl,offload-rtl,ipa,offload-ipa, andwpa-ipa.
scan-kind-dumpregexsuffix [{ target/xfailselector }]Passes ifregex matches text in the dump file with suffixsuffix.
scan-kind-dump-notregexsuffix [{ target/xfailselector }]Passes ifregex does not match text in the dump file with suffixsuffix.
scan-kind-dump-timesregexnumsuffix [{ target/xfailselector }]Passes ifregex is found exactlynum times in the dump filewith suffixsuffix.
scan-kind-dump-demregexsuffix [{ target/xfailselector }]Passes ifregex matches demangled text in the dump file withsuffixsuffix.
scan-kind-dump-dem-notregexsuffix [{ target/xfailselector }]Passes ifregex does not match demangled text in the dump file withsuffixsuffix.
Thesuffix argument which describes the dump file to be scannedmay contain a glob pattern that must expand to exactly one filename. This is useful if, e.g., different pass instances are executeddepending on torture testing command-line flags, producing dump fileswhose names differ only in their pass instance number suffix. Forexample, to scan instances 1, 2, 3 of a tree pass “mypass” foroccurrences 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\]" } } */Theoffload-… ones by default separately scan the dumpfile of each enabled offload target.You may use theonly_for_offload_target wrapper to restrict thescanning to one specific offload target:
/* { dg-do link { target offload_target_amdgcn } } *//* { dg-additional-options -foffload-options=-fdump-ipa-simdclone-details } *//* { dg-final { only_for_offload_target amdgcn-amdhsa scan-offload-ipa-dumpregex_amdgcn simdclone } } */This test case is active if GCN offload compilation is enabled (butpotentially also additional offload targets).Thesimdclone IPA dump file is (potentially) produced for alloffload targets, but only the GCN offload one is scanned.
If a test case doesn’t have a ‘{ targetselector }’, andyou need to scan, for example, for differentregexes for each ofhost and potentially several offload targets, use a pattern like this:
/* { dg-final { scan-tree-dumpregex_host optimized } } { dg-final { only_for_offload_target amdgcn-amdhsa scan-offload-tree-dumpregex_amdgcn optimized { target offload_target_amdgcn } } } { dg-final { only_for_offload_target nvptx-none scan-offload-tree-dumpregex_nvptx optimized { target offload_target_nvptx } } } */Here, unconditionallyregex_host is scanned for in the host dumpfile.If GCN offloading compilation is actually enabled,regex_amdgcnis scanned for in the GCN offload compilation dump file.If nvptx offloading compilation is actually enabled,regex_nvptxis scanned for in the nvptx offload compilation dump file.
output-exists [{ target/xfailselector }]Passes if compiler output file exists.
output-exists-not [{ target/xfailselector }]Passes if compiler output file does not exist.
scan-symbolregexp [{ target/xfailselector }]Passes if the pattern is present in the final executable.
scan-symbol-notregexp [{ target/xfailselector }]Passes if the pattern is absent from the final executable.
gcov tests ¶run-gcovsourcefileCheck line counts ingcov tests.
run-gcov [branches] [calls] {optssourcefile }Check branch and/or call counts, in addition to line counts, ingcov tests.
run-gcov-pytest {sourcefilepytest_file }Check output ofgcov intermediate format with a pytestscript.
Usually the test-framework removes files that were generated duringtesting. If a testcase, for example, uses any dumping mechanism toinspect a passes dump file, the testsuite recognized the dump optionpassed to the tool and schedules a final cleanup to remove these files.
There are, however, following additional cleanup directives that can beused to annotate a testcase "manually".
cleanup-coverage-filesRemoves coverage data files generated for this test.
cleanup-modules "list-of-extra-modules"Removes Fortran module files generated for this test, excluding themodule names listed in keep-modules.Cleaning up module files is usually done automatically by the testsuiteby looking at the source files and removing the modules after the testhas been executed.
module MoD1end module MoD1module Mod2end module Mod2module moD3end module moD3module mod4end 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 bycleanup-modules.If the list of modules is empty, all modules defined in this file are kept.
module maybe_unneededend module maybe_unneededmodule keep1end module keep1module keep2end module keep2! { dg-final { keep-modules "keep1 keep2" } } ! just keep these two! { dg-final { keep-modules "" } } ! keep alldg-keep-saved-temps "list-of-suffixes-not-to-delete"Whitespace separated list of suffixes that should not be deletedautomatically 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 .ocleanup-profile-fileRemoves profiling files generated for this test.