LTO Testing (GNU Compiler Collection (GCC) Internals)

### 6.5 Support for testing link-time optimizations ¶

Tests for link-time optimizations usually require multiple source files that are compiled separately, perhaps with different sets of options. There are several special-purpose test directives used for these tests.

`{ dg-lto-do do-what-keyword }`

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

  `assemble`

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

  `link`

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

  `ar-link`

    Similar to `link`, but combine all but the first source file into an archive file before the final link.

  `incr-link`

    As with `ar-link`, but combine the files into an object file using incremental linking, rather than an archive file. This enables testing the incremental linking features of the LTO front end.

  `run`

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

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

  Unlike `dg-do`, `dg-lto-do` does not support an optional ‘`target`’ or ‘`xfail`’ list. Use `dg-skip-if`, `dg-xfail-if`, or `dg-xfail-run-if`.

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

  This directive provides a list of one or more sets of compiler options to override LTO_OPTIONS. Every test file will be compiled and run once for each of these sets of options. Individual source files within a test may also use `dg-options` to specify additional options to include.

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

  This is similar to `dg-lto-options`, but rather than overriding LTO_OPTIONS, it appends the given options to each of the sets specified in LTO_OPTIONS. This can be used to add a given list of options to every compilation of all source files in the test, without otherwise changing which combinations of options are tested.

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

  This directive adds options to the linker options used.

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

  This directive removes options from the set of linker options used.