Directives (GNU Compiler Collection (GCC) Internals)

#### 6.2.1 Syntax and Descriptions of test directives ¶

Test directives appear within comments in a test source file and begin with `dg-`. Some of these are defined within DejaGnu and others are local to the GCC testsuite.

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.

Several test directives include selectors (see Selecting targets to which a test applies) which are usually preceded by the keyword `target` or `xfail`.

#### 6.2.1.1 Specify how to build the test ¶

`{ dg-do do-what-keyword [{ target/xfail selector }] }`

  do-what-keyword specifies how the test is compiled and whether it is executed. It is one of:

  `preprocess`

    Compile with `-E` to run only the preprocessor.

  `compile`

    Compile with `-S` to produce an assembly code file.

  `assemble`

    Compile with `-c` to produce a relocatable object file.

  `link`

    Compile, assemble, and link to produce an executable file.

  `run`

    Produce and run an executable file, which is expected to return an exit code of 0.

  The default is `compile`. That can be overridden for a set of tests by redefining `dg-do-what-default` within the `.exp` file for those tests.

  If the directive includes the optional ‘`{ target selector }`’ then the test is skipped unless the target system matches the selector.

  If do-what-keyword is `run` and the directive includes the optional ‘`{ xfail selector }`’ and the selector is met then the test is expected to fail. The `xfail` clause is ignored for other values of do-what-keyword; those tests can use directive `dg-xfail-if`.

#### 6.2.1.2 Specify additional compiler options ¶

`{ dg-options options [{ target selector }] }`

  This DejaGnu directive provides a list of compiler options, to be used if the target system matches selector, that replace the default options used for this set of tests.

`{ dg-add-options feature … }`

  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 `dg-options` directives. For supported values of feature see Features for `dg-add-options`.

`{ dg-remove-options feature … }`

  Remove any compiler options that are needed to access certain features. This directive does nothing on targets that disable the features by default, or that don’t provide them at all. It must come after all `dg-options` and `dg-add-options` directives. For supported values of feature see Features for `dg-remove-options`.

`{ dg-additional-options options [{ target selector }] }`

  This directive provides a list of compiler options, to be used if the target system matches selector, that are added to the default options used for this set of tests.

#### 6.2.1.3 Modify the test timeout value ¶

The normal timeout limit, in seconds, is found by searching the following in order:

- the value defined by an earlier `dg-timeout` directive in the test
- variable tool_timeout defined by the set of tests
- gcc,timeout set in the target board
- 300

`{ dg-timeout n [{target selector }] }`

  Set the time limit for the compilation and for the execution of the test to the specified number of seconds.

`{ dg-timeout-factor x [{ target selector }] }`

  Multiply the normal time limit for compilation and execution of the test by the specified floating-point factor.

#### 6.2.1.4 Skip a test for some targets ¶

`{ dg-do-if action { selector } }`

  Same as dg-do if the selector matches and the test hasn’t already been marked as unsupported. Use it to override an action on a target while leaving the default action alone for other targets.

`{ dg-skip-if comment { selector } [{ include-opts } [{ exclude-opts }]] }`

  Arguments include-opts and exclude-opts 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:

  - the test system is included in selector
  - for at least one of the option strings in include-opts, every option from that string is in the set of options with which the test would be compiled; use ‘`"*"`’ for an include-opts list that matches any options; that is the default if include-opts is not specified
  - for each of the option strings in exclude-opts, at least one option from that string is not in the set of options with which the test would be compiled; use ‘`""`’ for an empty exclude-opts list; that is the default if exclude-opts is not specified

  For example, to skip a test if option `-Os` is present:

      /* { dg-skip-if "" { *-*-* }  { "-Os" } { "" } } */

  To skip a test if both options `-O2` and `-g` are present:

      /* { dg-skip-if "" { *-*-* }  { "-O2 -g" } { "" } } */

  To skip a test if either `-O2` or `-O3` is present:

      /* { dg-skip-if "" { *-*-* }  { "-O2" "-O3" } { "" } } */

  To skip a test unless option `-Os` is present:

      /* { dg-skip-if "" { *-*-* }  { "*" } { "-Os" } } */

  To skip a test if either `-O2` or `-O3` is used with `-g` but not if `-fpic` is also present:

      /* { dg-skip-if "" { *-*-* }  { "-O2 -g" "-O3 -g" } { "-fpic" } } */

`{ dg-require-effective-target keyword [{ target selector }] }`

  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 ‘`{ selector }`’ then the effective-target test is only performed if the target system matches the selector. This directive must appear after any `dg-do` directive in the test and before any `dg-additional-sources` directive. See Keywords describing target attributes.

`{ dg-require-support args }`

  Skip the test if the target does not provide the required support. These directives must appear after any `dg-do` directive in the test and before any `dg-additional-sources` directive. They require at least one argument, which can be an empty string if the specific procedure does not examine the argument. See Variants of `dg-require-support`, for a complete list of these directives.

#### 6.2.1.5 Expect a test to fail for some targets ¶

`{ dg-xfail-if comment { selector } [{ include-opts } [{ exclude-opts }]] }`

  Expect the test to fail if the conditions (which are the same as for `dg-skip-if`) are met. This does not affect the execute step.

`{ dg-xfail-run-if comment { selector } [{ include-opts } [{ exclude-opts }]] }`

  Expect the execute step of a test to fail if the conditions (which are the same as for `dg-skip-if`) are met.

#### 6.2.1.6 Expect the compiler to crash ¶

`{ dg-ice comment [{ selector } [{ include-opts } [{ exclude-opts }]]] }`

  Expect the compiler to crash with an internal compiler error and return a nonzero exit status if the conditions (which are the same as for `dg-skip-if`) are met. Used for tests that test bugs that have not been fixed yet.

#### 6.2.1.7 Expect the test executable to fail ¶

`{ dg-shouldfail comment [{ selector } [{ include-opts } [{ exclude-opts }]]] }`

  Expect the test executable to return a nonzero exit status if the conditions (which are the same as for `dg-skip-if`) are met.

#### 6.2.1.8 Verify compiler messages ¶

Where line is an accepted argument for these commands, a value of ‘`0`’ can be used if there is no line associated with the message.

`{ dg-error regexp [comment [{ target/xfail selector } [line] ]] }`

  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 regexp then the check fails and comment is included in the `FAIL` message. The check does not look for the string ‘`error`’ unless it is part of regexp.

`{ dg-warning regexp [comment [{ target/xfail selector } [line] ]] }`

  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 regexp then the check fails and comment is included in the `FAIL` message. The check does not look for the string ‘`warning`’ unless it is part of regexp.

`{ dg-message regexp [comment [{ target/xfail selector } [line] ]] }`

  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 regexp then the check fails and comment is included in the `FAIL` message.

`{ dg-note regexp [comment [{ target/xfail selector } [line] ]] }`

  The line is expected to get a ‘`note`’ message. If there is no message for that line or if the text of that message is not matched by regexp then the check fails and comment is included in the `FAIL` message.

  By default, any excess ‘`note`’ messages are pruned, meaning their appearance doesn’t trigger excess errors. However, if ‘`dg-note`’ is used at least once in a testcase, they’re not pruned and instead must all be handled explicitly. Thus, if looking for just single instances of messages with ‘`note:` ’ prefixes without caring for all of them, use ‘`dg-message "note: […]"`’ instead of ‘`dg-note`’, or use ‘`dg-note`’ together with ‘`dg-prune-output "note: "`’.

`{ dg-bogus regexp [comment [{ target/xfail selector } [line] ]] }`

  This DejaGnu directive appears on a source line that should not get a message matching regexp, or else specifies the source line associated with the bogus message. It is usually used with ‘`xfail`’ to indicate that the message is a known problem for a particular set of targets.

`{ dg-line linenumvar }`

  This DejaGnu directive sets the variable linenumvar to the line number of the source line. The variable linenumvar can then be used in subsequent `dg-error`, `dg-warning`, `dg-message`, `dg-note` and `dg-bogus` directives. For example:

      int a;   /* { dg-line first_def_a } */
      float a; /* { dg-error "conflicting types of" } */
      /* { dg-message "previous declaration of" "" { target *-*-* } first_def_a } */

`{ dg-excess-errors comment [{ target/xfail selector }] }`

  This DejaGnu directive indicates that the test is expected to fail due to compiler messages that are not handled by ‘`dg-error`’, ‘`dg-warning`’, `dg-message`, ‘`dg-note`’ or ‘`dg-bogus`’. For this directive ‘`xfail`’ has the same effect as ‘`target`’.

`{ dg-prune-output regexp }`

  Prune messages matching regexp from the test output.

#### 6.2.1.9 Verify output of the test executable ¶

`{ dg-output regexp [{ target/xfail selector }] }`

  This DejaGnu directive compares regexp to the combined output that the test executable writes to `stdout` and `stderr`.

`{ dg-output-file file [{ target/xfail selector }] }`

  Compares the content of file against the combined output that the test executable writes to `stdout` and `stderr`.

#### 6.2.1.10 Specify environment variables for a test ¶

`{ dg-set-compiler-env-var var_name "var_value" }`

  Specify that the environment variable var_name needs to be set to var_value before invoking the compiler on the test file.

`{ dg-set-target-env-var var_name "var_value" }`

  Specify that the environment variable var_name needs to be set to var_value before execution of the program created by the test.

#### 6.2.1.11 Specify additional files for a test ¶

`{ dg-additional-files "filelist" }`

  Specify additional files, other than source files, that must be copied to the system where the compiler runs.

`{ dg-additional-sources "filelist" [{ \[linkonly\] \[target selector\] }] }`

  Specify additional source files to appear in the compile line following the main test file. If the directive includes the optional ‘`{ selector }`’ then the additional sources are only added if the target system matches the selector. If ‘`linkonly`’ is specified, additional sources are used only in ‘`link`’ and ‘`run`’ tests; they are reported as unsupported and discarded in other kinds of tests that direct the compiler to output to a single file.

#### 6.2.1.12 Add checks at the end of a test ¶

`{ dg-final { local-directive } }`

  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 ‘`dg-final`’ commands are processed in the order in which they appear in the source file. See Commands for use in `dg-final`, for a list of directives that can be used within `dg-final`.