387 lines
17 KiB
HTML
387 lines
17 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
<html>
|
||
|
<!-- Copyright (C) 1988-2016 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.2, http://www.gnu.org/software/texinfo/ -->
|
||
|
<head>
|
||
|
<title>GNU Compiler Collection (GCC) Internals: Directives</title>
|
||
|
|
||
|
<meta name="description" content="GNU Compiler Collection (GCC) Internals: Directives">
|
||
|
<meta name="keywords" content="GNU Compiler Collection (GCC) Internals: Directives">
|
||
|
<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="Selectors.html#Selectors" rel="next" title="Selectors">
|
||
|
<link href="Test-Directives.html#Test-Directives" rel="prev" title="Test Directives">
|
||
|
<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="Directives"></a>
|
||
|
<div class="header">
|
||
|
<p>
|
||
|
Next: <a href="Selectors.html#Selectors" accesskey="n" rel="next">Selectors</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="Syntax-and-Descriptions-of-test-directives"></a>
|
||
|
<h4 class="subsection">7.2.1 Syntax and Descriptions of test directives</h4>
|
||
|
|
||
|
<p>Test directives appear within comments in a test source file and begin
|
||
|
with <code>dg-</code>. Some of these are defined within DejaGnu and others
|
||
|
are local to the GCC testsuite.
|
||
|
</p>
|
||
|
<p>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.
|
||
|
</p>
|
||
|
<p>Several test directives include selectors (see <a href="Selectors.html#Selectors">Selectors</a>)
|
||
|
which are usually preceded by the keyword <code>target</code> or <code>xfail</code>.
|
||
|
</p>
|
||
|
<a name="Specify-how-to-build-the-test"></a>
|
||
|
<h4 class="subsubsection">7.2.1.1 Specify how to build the test</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-do <var>do-what-keyword</var> [{ target/xfail <var>selector</var> }] }</code></dt>
|
||
|
<dd><p><var>do-what-keyword</var> specifies how the test is compiled and whether
|
||
|
it is executed. It is one of:
|
||
|
</p>
|
||
|
<dl compact="compact">
|
||
|
<dt><code>preprocess</code></dt>
|
||
|
<dd><p>Compile with <samp>-E</samp> to run only the preprocessor.
|
||
|
</p></dd>
|
||
|
<dt><code>compile</code></dt>
|
||
|
<dd><p>Compile with <samp>-S</samp> to produce an assembly code file.
|
||
|
</p></dd>
|
||
|
<dt><code>assemble</code></dt>
|
||
|
<dd><p>Compile with <samp>-c</samp> to produce a relocatable object file.
|
||
|
</p></dd>
|
||
|
<dt><code>link</code></dt>
|
||
|
<dd><p>Compile, assemble, and link to produce an executable file.
|
||
|
</p></dd>
|
||
|
<dt><code>run</code></dt>
|
||
|
<dd><p>Produce and run an executable file, which is expected to return
|
||
|
an exit code of 0.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<p>The default is <code>compile</code>. That can be overridden for a set of
|
||
|
tests by redefining <code>dg-do-what-default</code> within the <code>.exp</code>
|
||
|
file for those tests.
|
||
|
</p>
|
||
|
<p>If the directive includes the optional ‘<samp>{ target <var>selector</var> }</samp>’
|
||
|
then the test is skipped unless the target system matches the
|
||
|
<var>selector</var>.
|
||
|
</p>
|
||
|
<p>If <var>do-what-keyword</var> is <code>run</code> and the directive includes
|
||
|
the optional ‘<samp>{ xfail <var>selector</var> }</samp>’ and the selector is met
|
||
|
then the test is expected to fail. The <code>xfail</code> clause is ignored
|
||
|
for other values of <var>do-what-keyword</var>; those tests can use
|
||
|
directive <code>dg-xfail-if</code>.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Specify-additional-compiler-options"></a>
|
||
|
<h4 class="subsubsection">7.2.1.2 Specify additional compiler options</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-options <var>options</var> [{ target <var>selector</var> }] }</code></dt>
|
||
|
<dd><p>This DejaGnu directive provides a list of compiler options, to be used
|
||
|
if the target system matches <var>selector</var>, that replace the default
|
||
|
options used for this set of tests.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-add-options <var>feature</var> … }</code></dt>
|
||
|
<dd><p>Add any compiler options that are needed to access certain features.
|
||
|
This directive does nothing on targets that enable the features by
|
||
|
default, or that don’t provide them at all. It must come after
|
||
|
all <code>dg-options</code> directives.
|
||
|
For supported values of <var>feature</var> see <a href="Add-Options.html#Add-Options">Add Options</a>.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-additional-options <var>options</var> [{ target <var>selector</var> }] }</code></dt>
|
||
|
<dd><p>This directive provides a list of compiler options, to be used
|
||
|
if the target system matches <var>selector</var>, that are added to the default
|
||
|
options used for this set of tests.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Modify-the-test-timeout-value"></a>
|
||
|
<h4 class="subsubsection">7.2.1.3 Modify the test timeout value</h4>
|
||
|
|
||
|
<p>The normal timeout limit, in seconds, is found by searching the
|
||
|
following in order:
|
||
|
</p>
|
||
|
<ul>
|
||
|
<li> the value defined by an earlier <code>dg-timeout</code> directive in
|
||
|
the test
|
||
|
|
||
|
</li><li> variable <var>tool_timeout</var> defined by the set of tests
|
||
|
|
||
|
</li><li> <var>gcc</var>,<var>timeout</var> set in the target board
|
||
|
|
||
|
</li><li> 300
|
||
|
</li></ul>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-timeout <var>n</var> [{target <var>selector</var> }] }</code></dt>
|
||
|
<dd><p>Set the time limit for the compilation and for the execution of the test
|
||
|
to the specified number of seconds.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-timeout-factor <var>x</var> [{ target <var>selector</var> }] }</code></dt>
|
||
|
<dd><p>Multiply the normal time limit for compilation and execution of the test
|
||
|
by the specified floating-point factor.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Skip-a-test-for-some-targets"></a>
|
||
|
<h4 class="subsubsection">7.2.1.4 Skip a test for some targets</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-skip-if <var>comment</var> { <var>selector</var> } [{ <var>include-opts</var> } [{ <var>exclude-opts</var> }]] }</code></dt>
|
||
|
<dd><p>Arguments <var>include-opts</var> and <var>exclude-opts</var> are lists in which
|
||
|
each element is a string of zero or more GCC options.
|
||
|
Skip the test if all of the following conditions are met:
|
||
|
</p><ul>
|
||
|
<li> the test system is included in <var>selector</var>
|
||
|
|
||
|
</li><li> for at least one of the option strings in <var>include-opts</var>,
|
||
|
every option from that string is in the set of options with which
|
||
|
the test would be compiled; use ‘<samp>"*"</samp>’ for an <var>include-opts</var> list
|
||
|
that matches any options; that is the default if <var>include-opts</var> is
|
||
|
not specified
|
||
|
|
||
|
</li><li> for each of the option strings in <var>exclude-opts</var>, at least one
|
||
|
option from that string is not in the set of options with which the test
|
||
|
would be compiled; use ‘<samp>""</samp>’ for an empty <var>exclude-opts</var> list;
|
||
|
that is the default if <var>exclude-opts</var> is not specified
|
||
|
</li></ul>
|
||
|
|
||
|
<p>For example, to skip a test if option <code>-Os</code> is present:
|
||
|
</p>
|
||
|
<div class="smallexample">
|
||
|
<pre class="smallexample">/* { dg-skip-if "" { *-*-* } { "-Os" } { "" } } */
|
||
|
</pre></div>
|
||
|
|
||
|
<p>To skip a test if both options <code>-O2</code> and <code>-g</code> are present:
|
||
|
</p>
|
||
|
<div class="smallexample">
|
||
|
<pre class="smallexample">/* { dg-skip-if "" { *-*-* } { "-O2 -g" } { "" } } */
|
||
|
</pre></div>
|
||
|
|
||
|
<p>To skip a test if either <code>-O2</code> or <code>-O3</code> is present:
|
||
|
</p>
|
||
|
<div class="smallexample">
|
||
|
<pre class="smallexample">/* { dg-skip-if "" { *-*-* } { "-O2" "-O3" } { "" } } */
|
||
|
</pre></div>
|
||
|
|
||
|
<p>To skip a test unless option <code>-Os</code> is present:
|
||
|
</p>
|
||
|
<div class="smallexample">
|
||
|
<pre class="smallexample">/* { dg-skip-if "" { *-*-* } { "*" } { "-Os" } } */
|
||
|
</pre></div>
|
||
|
|
||
|
<p>To skip a test if either <code>-O2</code> or <code>-O3</code> is used with <code>-g</code>
|
||
|
but not if <code>-fpic</code> is also present:
|
||
|
</p>
|
||
|
<div class="smallexample">
|
||
|
<pre class="smallexample">/* { dg-skip-if "" { *-*-* } { "-O2 -g" "-O3 -g" } { "-fpic" } } */
|
||
|
</pre></div>
|
||
|
|
||
|
</dd>
|
||
|
<dt><code>{ dg-require-effective-target <var>keyword</var> [{ <var>selector</var> }] }</code></dt>
|
||
|
<dd><p>Skip the test if the test target, including current multilib flags,
|
||
|
is not covered by the effective-target keyword.
|
||
|
If the directive includes the optional ‘<samp>{ <var>selector</var> }</samp>’
|
||
|
then the effective-target test is only performed if the target system
|
||
|
matches the <var>selector</var>.
|
||
|
This directive must appear after any <code>dg-do</code> directive in the test
|
||
|
and before any <code>dg-additional-sources</code> directive.
|
||
|
See <a href="Effective_002dTarget-Keywords.html#Effective_002dTarget-Keywords">Effective-Target Keywords</a>.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-require-<var>support</var> args }</code></dt>
|
||
|
<dd><p>Skip the test if the target does not provide the required support.
|
||
|
These directives must appear after any <code>dg-do</code> directive in the test
|
||
|
and before any <code>dg-additional-sources</code> directive.
|
||
|
They require at least one argument, which can be an empty string if the
|
||
|
specific procedure does not examine the argument.
|
||
|
See <a href="Require-Support.html#Require-Support">Require Support</a>, for a complete list of these directives.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Expect-a-test-to-fail-for-some-targets"></a>
|
||
|
<h4 class="subsubsection">7.2.1.5 Expect a test to fail for some targets</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-xfail-if <var>comment</var> { <var>selector</var> } [{ <var>include-opts</var> } [{ <var>exclude-opts</var> }]] }</code></dt>
|
||
|
<dd><p>Expect the test to fail if the conditions (which are the same as for
|
||
|
<code>dg-skip-if</code>) are met. This does not affect the execute step.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-xfail-run-if <var>comment</var> { <var>selector</var> } [{ <var>include-opts</var> } [{ <var>exclude-opts</var> }]] }</code></dt>
|
||
|
<dd><p>Expect the execute step of a test to fail if the conditions (which are
|
||
|
the same as for <code>dg-skip-if</code>) are met.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Expect-the-test-executable-to-fail"></a>
|
||
|
<h4 class="subsubsection">7.2.1.6 Expect the test executable to fail</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-shouldfail <var>comment</var> [{ <var>selector</var> } [{ <var>include-opts</var> } [{ <var>exclude-opts</var> }]]] }</code></dt>
|
||
|
<dd><p>Expect the test executable to return a nonzero exit status if the
|
||
|
conditions (which are the same as for <code>dg-skip-if</code>) are met.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Verify-compiler-messages"></a>
|
||
|
<h4 class="subsubsection">7.2.1.7 Verify compiler messages</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-error <var>regexp</var> [<var>comment</var> [{ target/xfail <var>selector</var> } [<var>line</var>] }]] }</code></dt>
|
||
|
<dd><p>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 <var>regexp</var> then the check fails and
|
||
|
<var>comment</var> is included in the <code>FAIL</code> message. The check does
|
||
|
not look for the string ‘<samp>error</samp>’ unless it is part of <var>regexp</var>.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-warning <var>regexp</var> [<var>comment</var> [{ target/xfail <var>selector</var> } [<var>line</var>] }]] }</code></dt>
|
||
|
<dd><p>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 <var>regexp</var> then the check fails and
|
||
|
<var>comment</var> is included in the <code>FAIL</code> message. The check does
|
||
|
not look for the string ‘<samp>warning</samp>’ unless it is part of <var>regexp</var>.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-message <var>regexp</var> [<var>comment</var> [{ target/xfail <var>selector</var> } [<var>line</var>] }]] }</code></dt>
|
||
|
<dd><p>The line is expected to get a message other than an error or warning.
|
||
|
If there is no message for that line or if the text of that message is
|
||
|
not matched by <var>regexp</var> then the check fails and <var>comment</var> is
|
||
|
included in the <code>FAIL</code> message.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-bogus <var>regexp</var> [<var>comment</var> [{ target/xfail <var>selector</var> } [<var>line</var>] }]] }</code></dt>
|
||
|
<dd><p>This DejaGnu directive appears on a source line that should not get a
|
||
|
message matching <var>regexp</var>, or else specifies the source line
|
||
|
associated with the bogus message. It is usually used with ‘<samp>xfail</samp>’
|
||
|
to indicate that the message is a known problem for a particular set of
|
||
|
targets.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-excess-errors <var>comment</var> [{ target/xfail <var>selector</var> }] }</code></dt>
|
||
|
<dd><p>This DejaGnu directive indicates that the test is expected to fail due
|
||
|
to compiler messages that are not handled by ‘<samp>dg-error</samp>’,
|
||
|
‘<samp>dg-warning</samp>’ or ‘<samp>dg-bogus</samp>’. For this directive ‘<samp>xfail</samp>’
|
||
|
has the same effect as ‘<samp>target</samp>’.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-prune-output <var>regexp</var> }</code></dt>
|
||
|
<dd><p>Prune messages matching <var>regexp</var> from the test output.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Verify-output-of-the-test-executable"></a>
|
||
|
<h4 class="subsubsection">7.2.1.8 Verify output of the test executable</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-output <var>regexp</var> [{ target/xfail <var>selector</var> }] }</code></dt>
|
||
|
<dd><p>This DejaGnu directive compares <var>regexp</var> to the combined output
|
||
|
that the test executable writes to <samp>stdout</samp> and <samp>stderr</samp>.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Specify-additional-files-for-a-test"></a>
|
||
|
<h4 class="subsubsection">7.2.1.9 Specify additional files for a test</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-additional-files "<var>filelist</var>" }</code></dt>
|
||
|
<dd><p>Specify additional files, other than source files, that must be copied
|
||
|
to the system where the compiler runs.
|
||
|
</p>
|
||
|
</dd>
|
||
|
<dt><code>{ dg-additional-sources "<var>filelist</var>" }</code></dt>
|
||
|
<dd><p>Specify additional source files to appear in the compile line
|
||
|
following the main test file.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<a name="Add-checks-at-the-end-of-a-test"></a>
|
||
|
<h4 class="subsubsection">7.2.1.10 Add checks at the end of a test</h4>
|
||
|
|
||
|
<dl compact="compact">
|
||
|
<dt><code>{ dg-final { <var>local-directive</var> } }</code></dt>
|
||
|
<dd><p>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 ‘<samp>dg-final</samp>’ commands are processed in the order in which
|
||
|
they appear in the source file. See <a href="Final-Actions.html#Final-Actions">Final Actions</a>, for a list
|
||
|
of directives that can be used within <code>dg-final</code>.
|
||
|
</p></dd>
|
||
|
</dl>
|
||
|
|
||
|
<hr>
|
||
|
<div class="header">
|
||
|
<p>
|
||
|
Next: <a href="Selectors.html#Selectors" accesskey="n" rel="next">Selectors</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>
|