gcc/doc/gccint/testsuites/support-for-testing-link-time-optimizations.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _lto-testing:
   7
   8 Support for testing link-time optimizations
   9 *******************************************
  10
  11 Tests for link-time optimizations usually require multiple source files
  12 that are compiled separately, perhaps with different sets of options.
  13 There are several special-purpose test directives used for these tests.
  14
  15 :samp:`{ dg-lto-do {do-what-keyword} }`
  16   :samp:`{do-what-keyword}` specifies how the test is compiled and whether
  17   it is executed.  It is one of:
  18
  19   ``assemble``
  20     Compile with :option:`-c` to produce a relocatable object file.
  21
  22   ``link``
  23     Compile, assemble, and link to produce an executable file.
  24
  25   ``run``
  26     Produce and run an executable file, which is expected to return
  27     an exit code of 0.
  28
  29   The default is ``assemble``.  That can be overridden for a set of
  30   tests by redefining ``dg-do-what-default`` within the ``.exp``
  31   file for those tests.
  32
  33   Unlike ``dg-do``, ``dg-lto-do`` does not support an optional
  34   :samp:`target` or :samp:`xfail` list.  Use ``dg-skip-if``,
  35   ``dg-xfail-if``, or ``dg-xfail-run-if``.
  36
  37 :samp:`{ dg-lto-options { { {options} } [{ {options} }] } [{ target {selector} }]}`
  38   This directive provides a list of one or more sets of compiler options
  39   to override :samp:`{LTO_OPTIONS}`.  Each test will be compiled and run with
  40   each of these sets of options.
  41
  42 :samp:`{ dg-extra-ld-options {options} [{ target {selector} }]}`
  43   This directive adds :samp:`{options}` to the linker options used.
  44
  45 :samp:`{ dg-suppress-ld-options {options} [{ target {selector} }]}`
  46   This directive removes :samp:`{options}` from the set of linker options used.