llvm/docs/FatLTO.rst

   1 ===================
   2 FatLTO
   3 ===================
   4 .. contents::
   5    :local:
   6    :depth: 2
   7
   8 .. toctree::
   9    :maxdepth: 1
  10
  11 Introduction
  12 ============
  13
  14 FatLTO objects are a special type of `fat object file
  15 <https://en.wikipedia.org/wiki/Fat_binary>`_ that contain LTO compatible IR in
  16 addition to generated object code, instead of containing object code for
  17 multiple target architectures. This allows users to defer the choice of whether
  18 to use LTO or not to link-time, and has been a feature available in other
  19 compilers, like `GCC
  20 <https://gcc.gnu.org/onlinedocs/gccint/LTO-Overview.html>`_, for some time.
  21
  22 Under FatLTO the compiler can emit standard object files which contain both the
  23 machine code in the ``.text`` section and LLVM bitcode in the ``.llvm.lto``
  24 section.
  25
  26 Overview
  27 ========
  28
  29 Within LLVM, FatLTO is supported by choosing the ``FatLTODefaultPipeline``.
  30 This pipeline will:
  31
  32 #) Run the pre-link (Thin)LTO pipeline on the current module.
  33 #) Embed the pre-link bitcode in a special ``.llvm.lto`` section.
  34 #) Finish optimizing the module using the ModuleOptimization pipeline.
  35 #) Emit the object file, including the new ``.llvm.lto`` section.
  36
  37 .. NOTE
  38
  39    Previously, we conservatively ran independent pipelines on separate copies
  40    of the LLVM module to generate the bitcode section and the object code,
  41    which happen to be identical to those used outside of FatLTO. While that
  42    resulted in  compiled artifacts that were identical to those produced by the
  43    default and (Thin)LTO pipelines, module cloning led to some cases of
  44    miscompilation, and we have moved away from trying to keep bitcode
  45    generation and optimization completely disjoint.
  46
  47    Bit-for-bit compatibility is not (and never was) a guarantee, and we reserve
  48    the right to change this at any time. Explicitly, users should not rely on
  49    the produced bitcode or object code to match their non-LTO counterparts
  50    precisely. They will exhibit similar performance characteristics, but may
  51    not be bit-for-bit the same.
  52
  53 Internally, the ``.llvm.lto`` section is created by running the
  54 ``EmbedBitcodePass`` after the ``ThinLTOPreLinkDefaultPipeline``. This pass is
  55 responsible for emitting the ``.llvm.lto`` section. Afterwards, the
  56 ``ThinLTODefaultPipeline`` runs and the compiler can emit the fat object file.
  57
  58 Limitations
  59 ===========
  60
  61 Linkers
  62 -------
  63
  64 Currently, using LTO with LLVM fat lto objects is supported by LLD and by the
  65 GNU linkers via :doc:`GoldPlugin`. This may change in the future, but
  66 extending support to other linkers isn't planned for now.
  67
  68 .. NOTE
  69    For standard linking the fat object files should be usable by any
  70    linker capable of using ELF objects, since the ``.llvm.lto`` section is
  71    marked ``SHF_EXCLUDE``.
  72
  73 Supported File Formats
  74 ----------------------
  75
  76 The current implementation only supports ELF files. At time of writing, it is
  77 unclear if it will be useful to support other object file formats like ``COFF``
  78 or ``Mach-O``.
  79
  80 Usage
  81 =====
  82
  83 Clang users can specify ``-ffat-lto-objects`` with ``-flto`` or ``-flto=thin``.
  84 Without the ``-flto`` option, ``-ffat-lto-objects`` has no effect.
  85
  86 Compile an object file using FatLTO:
  87
  88 .. code-block:: console
  89
  90    $ clang -flto -ffat-lto-objects example.c -c -o example.o
  91
  92 Link using the object code from the fat object without LTO. This turns
  93 ``-ffat-lto-objects`` into a no-op, when ``-fno-lto`` is specified:
  94
  95 .. code-block:: console
  96
  97    $ clang -fno-lto -ffat-lto-objects -fuse-ld=lld example.o
  98
  99 Alternatively, you can omit any references to LTO with fat objects and retain standard linker behavior:
 100
 101 .. code-block:: console
 102
 103    $ clang -fuse-ld=lld example.o
 104
 105 Link using the LLVM bitcode from the fat object with Full LTO:
 106
 107 .. code-block:: console
 108
 109    $ clang -flto -ffat-lto-objects -fuse-ld=lld example.o  # clang will pass --lto=full --fat-lto-objects to ld.lld
 110
 111 Link using the LLVM bitcode from the fat object with Thin LTO:
 112
 113 .. code-block:: console
 114
 115    $ clang -flto=thin -ffat-lto-objects -fuse-ld=lld example.o  # clang will pass --lto=thin --fat-lto-objects to ld.lld