Final Actions (GNU Compiler Collection (GCC) Internals)

#### 6.2.7 Commands for use in `dg-final` ¶

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

#### 6.2.7.1 Scan a particular file ¶

`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-module module regexp [{ 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`.

#### 6.2.7.2 Scan the assembly output ¶

`scan-assembler regex [{ target/xfail selector }]`

  Passes if regex matches text in the test’s assembler output, excluding LTO sections.

`scan-raw-assembler regex [{ target/xfail selector }]`

  Passes if regex matches text in the test’s assembler output, including LTO sections.

`scan-assembler-not regex [{ target/xfail selector }]`

  Passes if regex does not match text in the test’s assembler output, excluding LTO sections.

`scan-assembler-times regex num [{ target/xfail selector }]`

  Passes if regex is matched exactly num times in the test’s assembler output, excluding LTO sections.

`scan-assembler-bound regex cmp num [{ target/xfail selector }]`

  Passes if regex is matched cmp num times in the test’s assembler output, excluding LTO sections. cmp is a comparator.

`scan-assembler-dem regex [{ target/xfail selector }]`

  Passes if regex matches text in the test’s demangled assembler output, excluding LTO sections.

`scan-assembler-dem-not regex [{ target/xfail selector }]`

  Passes if regex does not match text in the test’s demangled assembler output, excluding LTO sections.

`scan-assembler-symbol-section functions section [{ 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 filename functions section [{ target/xfail selector }]`

  Passes if functions are all in sectionin 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 prefix terminator [options [{ target/xfail selector } [matched]]]`

  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.

  Depending on the configuration (see `configure_check-function-bodies` in `gcc/testsuite/lib/scanasm.exp`), the test may discard from the compiler’s assembly output directives such as `.cfi_startproc`, local label definitions such as `.LFB0`, and more. This behavior can be overridden using the optional matched argument, which specifies a regexp for lines that should not be discarded in this way.

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

  `check-function-bodies` automatically adds the same options as:

      /* { dg-add-options check_function_bodies } */

  For this reason, `check-function-bodies` must come after the final `dg-options` directive.

#### 6.2.7.3 Scan object metadata with readelf ¶

These commands inspect the linked test output file with `readelf`. They are mainly intended for LTO tests.

These commands take a single regex and test whether it is present in (or absent from, for ‘`-not`’) the corresponding `readelf` output.

`object-readelf-attributes regex [{ target/xfail selector }]`

  Runs `readelf -A` and checks that regex matches.

`object-readelf-attributes-not regex [{ target/xfail selector }]`

  Runs `readelf -A` and checks that regex does not match.

`object-readelf-notes regex [{ target/xfail selector }]`

  Runs `readelf -n` and checks that regex matches.

`object-readelf-notes-not regex [{ target/xfail selector }]`

  Runs `readelf -n` and checks that regex does not match.

#### 6.2.7.4 Scan optimization dump files ¶

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

`scan-kind-dump regex suffix [{ target/xfail selector }]`

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

`scan-kind-dump-not regex suffix [{ target/xfail selector }]`

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

`scan-kind-dump-times regex num suffix [{ target/xfail selector }]`

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

`scan-kind-dump-dem regex suffix [{ target/xfail selector }]`

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

`scan-kind-dump-dem-not regex suffix [{ 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\]" } } */

The `offload-…` ones by default separately scan the dump file of each enabled offload target. You may use the `only_for_offload_target` wrapper to restrict the scanning 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-dump regex_amdgcn simdclone } } */

This test case is active if GCN offload compilation is enabled (but potentially also additional offload targets). The `simdclone` IPA dump file is (potentially) produced for all offload targets, but only the GCN offload one is scanned.

If a test case doesn’t have a ‘`{ target selector }`’, and you need to scan, for example, for different regexes for each of host and potentially several offload targets, use a pattern like this:

    /* { dg-final { scan-tree-dump regex_host optimized } }
       { dg-final { only_for_offload_target amdgcn-amdhsa scan-offload-tree-dump regex_amdgcn optimized { target offload_target_amdgcn } } }
       { dg-final { only_for_offload_target nvptx-none scan-offload-tree-dump regex_nvptx optimized { target offload_target_nvptx } } } */

Here, unconditionally regex_host is scanned for in the host dump file. If GCN offloading compilation is actually enabled, regex_amdgcn is scanned for in the GCN offload compilation dump file. If nvptx offloading compilation is actually enabled, regex_nvptx is scanned for in the nvptx offload compilation dump file.

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

#### 6.2.7.6 Checks for `gcov` tests ¶

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

`run-gcov-pytest { sourcefile pytest_file }`

  Check output of `gcov` intermediate format with a pytest script.

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