gcc/testsuite/gcc.dg/lto/README

   1 This directory contains tests for link-time optimization (LTO).
   2
   3 === Directives ===
   4
   5 The LTO harness recognizes the following special DejaGnu directives:
   6  *  dg-lto-do - the equivalent of dg-do with a limited set of supported
   7       arguments (see below),
   8  *  dg-lto-options - the equivalent of dg-options with additional syntax
   9       to support different sets of options for different files compiled
  10       as part of the same test case,
  11  *  dg-lto-warning - the equivalent of dg-warning for diagnostics expected
  12       to be emitted at LTO link time,
  13  *  dg-lto-message - the equivakent of dg-message for informational notes
  14       expected to be emitted at LTO link time.
  15
  16 === Test Names ===
  17
  18 Tests in this directory may span multiple files, so the naming of
  19 the files is significant.
  20
  21 The name of every file must end with '_N' where N is an integer.
  22 All the files with the same name base and different _N suffixes
  23 will be compiled separately and linked together to form the final
  24 executable.
  25
  26 By default, each set of files will be compiled with list of
  27 options listed in LTO_OPTIONS (../../lib/lto.exp), which can be
  28 overridden in the shell environment or using the 'dg-lto-options'
  29 directive in the main file of the set (i.e., the file with _0
  30 suffix).
  31
  32 For example, given the files a_0.C a_1.C a_2.C, they will be
  33 compiled as:
  34
  35 $ g++ -c <flags> a_0.C
  36 $ g++ -c <flags> a_1.C
  37 $ g++ -c <flags> a_2.C
  38 $ g++ -o <executable> a_0.o a_1.o a_2.o
  39
  40 Tests that do not need more than one file are a special case
  41 where there is a single file named 'foo_0.C'.
  42
  43 === The dg-lto-do Directive ==
  44
  45 The only supported dg-lto-do options are 'assemble', 'run' and 'link'.
  46 Additionally, these can only be used in the main file.  If
  47 'assemble' is used, only the individual object files are
  48 generated.  If 'link' is used, the final executable is generated
  49 but not executed (in this case, function main() needs to exist
  50 but it does not need to do anything).  If 'run' is used, the
  51 final executable is generated and the resulting binary executed.
  52
  53 The default value for dg-lto-do is 'run'.