diff options
Diffstat (limited to 'share/doc/gccint/Final-Actions.html')
| -rw-r--r-- | share/doc/gccint/Final-Actions.html | 409 |
1 files changed, 409 insertions, 0 deletions
diff --git a/share/doc/gccint/Final-Actions.html b/share/doc/gccint/Final-Actions.html new file mode 100644 index 0000000..f0649a8 --- /dev/null +++ b/share/doc/gccint/Final-Actions.html @@ -0,0 +1,409 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>GNU Compiler Collection (GCC) Internals: Final Actions</title> + +<meta name="description" content="GNU Compiler Collection (GCC) Internals: Final Actions"> +<meta name="keywords" content="GNU Compiler Collection (GCC) Internals: Final Actions"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Test-Directives.html#Test-Directives" rel="up" title="Test Directives"> +<link href="Ada-Tests.html#Ada-Tests" rel="next" title="Ada Tests"> +<link href="Require-Support.html#Require-Support" rel="previous" title="Require Support"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Final-Actions"></a> +<div class="header"> +<p> +Previous: <a href="Require-Support.html#Require-Support" accesskey="p" rel="previous">Require Support</a>, Up: <a href="Test-Directives.html#Test-Directives" accesskey="u" rel="up">Test Directives</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Commands-for-use-in-dg_002dfinal"></a> +<h4 class="subsection">7.2.6 Commands for use in <code>dg-final</code></h4> + +<p>The GCC testsuite defines the following directives to be used within +<code>dg-final</code>. +</p> +<a name="Scan-a-particular-file"></a> +<h4 class="subsubsection">7.2.6.1 Scan a particular file</h4> + +<dl compact="compact"> +<dt><code>scan-file <var>filename</var> <var>regexp</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regexp</var> matches text in <var>filename</var>. +</p></dd> +<dt><code>scan-file-not <var>filename</var> <var>regexp</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regexp</var> does not match text in <var>filename</var>. +</p></dd> +<dt><code>scan-module <var>module</var> <var>regexp</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regexp</var> matches in Fortran module <var>module</var>. +</p></dd> +<dt><code>dg-check-dot <var>filename</var></code></dt> +<dd><p>Passes if <var>filename</var> is a valid <samp>.dot</samp> file (by running +<code>dot -Tpng</code> on it, and verifying the exit code is 0). +</p></dd> +<dt><code>scan-sarif-file <var>regexp</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regexp</var> matches text in the file generated by +<samp>-fdiagnostics-format=sarif-file</samp>. +</p></dd> +<dt><code>scan-sarif-file-not <var>regexp</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regexp</var> does not match text in the file generated by +<samp>-fdiagnostics-format=sarif-file</samp>. +</p></dd> +</dl> + +<a name="Scan-the-assembly-output"></a> +<h4 class="subsubsection">7.2.6.2 Scan the assembly output</h4> + +<dl compact="compact"> +<dt><code>scan-assembler <var>regex</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> matches text in the test’s assembler output. +</p> +</dd> +<dt><code>scan-assembler-not <var>regex</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> does not match text in the test’s assembler output. +</p> +</dd> +<dt><code>scan-assembler-times <var>regex</var> <var>num</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> is matched exactly <var>num</var> times in the test’s +assembler output. +</p> +</dd> +<dt><code>scan-assembler-dem <var>regex</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> matches text in the test’s demangled assembler output. +</p> +</dd> +<dt><code>scan-assembler-dem-not <var>regex</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> does not match text in the test’s demangled assembler +output. +</p> +</dd> +<dt><code>scan-assembler-symbol-section <var>functions</var> <var>section</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>functions</var> are all in <var>section</var>. The caller needs to +allow for <code>USER_LABEL_PREFIX</code> and different section name conventions. +</p> +</dd> +<dt><code>scan-symbol-section <var>filename</var> <var>functions</var> <var>section</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>functions</var> are all in <var>section</var>in <var>filename</var>. +The same caveats as for <code>scan-assembler-symbol-section</code> apply. +</p> +</dd> +<dt><code>scan-hidden <var>symbol</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>symbol</var> is defined as a hidden symbol in the test’s +assembly output. +</p> +</dd> +<dt><code>scan-not-hidden <var>symbol</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>symbol</var> is not defined as a hidden symbol in the test’s +assembly output. +</p> +</dd> +<dt><code>check-function-bodies <var>prefix</var> <var>terminator</var> [<var>options</var> [{ target/xfail <var>selector</var> }]]</code></dt> +<dd><p>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 <var>prefix</var> and the expected output for a function as a whole +is followed by a line that starts with the string <var>terminator</var>. +Specifying an empty terminator is equivalent to specifying ‘<samp>"*/"</samp>’. +</p> +<p><var>options</var>, 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. +</p> +<p>The first line of the expected output for a function <var>fn</var> has the form: +</p> +<div class="smallexample"> +<pre class="smallexample"><var>prefix</var> <var>fn</var>: [{ target/xfail <var>selector</var> }] +</pre></div> + +<p>Subsequent lines of the expected output also start with <var>prefix</var>. +In both cases, whitespace after <var>prefix</var> is not significant. +</p> +<p>The test discards assembly directives such as <code>.cfi_startproc</code> +and local label definitions such as <code>.LFB0</code> 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 ‘<samp>(…)</samp>’ +captures on earlier lines. For example: +</p> +<div class="smallexample"> +<pre class="smallexample">/* { 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 (…) { … } +</pre></div> + +<p>checks whether the implementations of <code>add_w0_s8_m</code> and +<code>add_b0_s8_m</code> match the regular expressions given. The test only +runs when ‘<samp>-DCHECK_ASM</samp>’ is passed on the command line. +</p> +<p>It is possible to create non-capturing multi-line regular expression +groups of the form ‘<samp>(<var>a</var>|<var>b</var>|…)</samp>’ by putting the +‘<samp>(</samp>’, ‘<samp>|</samp>’ and ‘<samp>)</samp>’ on separate lines (each still using +<var>prefix</var>). For example: +</p> +<div class="smallexample"> +<pre class="smallexample">/* +** 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 (…) { … } +</pre></div> + +<p>checks whether <code>cmple_f16_tied</code> is implemented by the +<code>fcmge</code> instruction followed by <code>ret</code> or by the +<code>fcmle</code> instruction followed by <code>ret</code>. The test is +still a single regular rexpression. +</p> +<p>A line containing just: +</p> +<div class="smallexample"> +<pre class="smallexample"><var>prefix</var> ... +</pre></div> + +<p>stands for zero or more unmatched lines; the whitespace after +<var>prefix</var> is again not significant. +</p> +</dd> +</dl> + +<a name="Scan-optimization-dump-files"></a> +<h4 class="subsubsection">7.2.6.3 Scan optimization dump files</h4> + +<p>These commands are available for <var>kind</var> of <code>tree</code>, <code>ltrans-tree</code>, +<code>offload-tree</code>, <code>rtl</code>, <code>offload-rtl</code>, <code>ipa</code>, and +<code>wpa-ipa</code>. +</p> +<dl compact="compact"> +<dt><code>scan-<var>kind</var>-dump <var>regex</var> <var>suffix</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> matches text in the dump file with suffix <var>suffix</var>. +</p> +</dd> +<dt><code>scan-<var>kind</var>-dump-not <var>regex</var> <var>suffix</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> does not match text in the dump file with suffix +<var>suffix</var>. +</p> +</dd> +<dt><code>scan-<var>kind</var>-dump-times <var>regex</var> <var>num</var> <var>suffix</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> is found exactly <var>num</var> times in the dump file +with suffix <var>suffix</var>. +</p> +</dd> +<dt><code>scan-<var>kind</var>-dump-dem <var>regex</var> <var>suffix</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> matches demangled text in the dump file with +suffix <var>suffix</var>. +</p> +</dd> +<dt><code>scan-<var>kind</var>-dump-dem-not <var>regex</var> <var>suffix</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if <var>regex</var> does not match demangled text in the dump file with +suffix <var>suffix</var>. +</p></dd> +</dl> + +<p>The <var>suffix</var> 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: +</p><div class="smallexample"> +<pre class="smallexample">/* { dg-options "-fdump-tree-mypass" } */ +/* { dg-final { scan-tree-dump "code has been optimized" "mypass\[1-3\]" } } */ +</pre></div> + + +<a name="Check-for-output-files"></a> +<h4 class="subsubsection">7.2.6.4 Check for output files</h4> + +<dl compact="compact"> +<dt><code>output-exists [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if compiler output file exists. +</p> +</dd> +<dt><code>output-exists-not [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if compiler output file does not exist. +</p> +</dd> +<dt><code>scan-symbol <var>regexp</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if the pattern is present in the final executable. +</p> +</dd> +<dt><code>scan-symbol-not <var>regexp</var> [{ target/xfail <var>selector</var> }]</code></dt> +<dd><p>Passes if the pattern is absent from the final executable. +</p></dd> +</dl> + +<a name="Checks-for-gcov-tests"></a> +<h4 class="subsubsection">7.2.6.5 Checks for <code>gcov</code> tests</h4> + +<dl compact="compact"> +<dt><code>run-gcov <var>sourcefile</var></code></dt> +<dd><p>Check line counts in <code>gcov</code> tests. +</p> +</dd> +<dt><code>run-gcov [branches] [calls] { <var>opts</var> <var>sourcefile</var> }</code></dt> +<dd><p>Check branch and/or call counts, in addition to line counts, in +<code>gcov</code> tests. +</p> +</dd> +<dt><code>run-gcov-pytest { <var>sourcefile</var> <var>pytest_file</var> }</code></dt> +<dd><p>Check output of <code>gcov</code> intermediate format with a pytest +script. +</p></dd> +</dl> + +<a name="Clean-up-generated-test-files"></a> +<h4 class="subsubsection">7.2.6.6 Clean up generated test files</h4> + +<p>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. +</p> +<p>There are, however, following additional cleanup directives that can be +used to annotate a testcase "manually". +</p><dl compact="compact"> +<dt><code>cleanup-coverage-files</code></dt> +<dd><p>Removes coverage data files generated for this test. +</p> +</dd> +<dt><code>cleanup-modules "<var>list-of-extra-modules</var>"</code></dt> +<dd><p>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. +</p><div class="smallexample"> +<pre class="smallexample">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" } } +</pre></div> + +</dd> +<dt><code>keep-modules "<var>list-of-modules-not-to-delete</var>"</code></dt> +<dd><p>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. +</p><div class="smallexample"> +<pre class="smallexample">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 +</pre></div> + +</dd> +<dt><code>dg-keep-saved-temps "<var>list-of-suffixes-not-to-delete</var>"</code></dt> +<dd><p>Whitespace separated list of suffixes that should not be deleted +automatically in a testcase that uses <samp>-save-temps</samp>. +</p><div class="smallexample"> +<pre class="smallexample">// { 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 +</pre></div> + +</dd> +<dt><code>cleanup-profile-file</code></dt> +<dd><p>Removes profiling files generated for this test. +</p> +</dd> +</dl> + +<hr> +<div class="header"> +<p> +Previous: <a href="Require-Support.html#Require-Support" accesskey="p" rel="previous">Require Support</a>, Up: <a href="Test-Directives.html#Test-Directives" accesskey="u" rel="up">Test Directives</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |