116 lines · plain
1===================2FatLTO3===================4.. contents::5 :local:6 :depth: 27 8.. toctree::9 :maxdepth: 110 11Introduction12============13 14FatLTO objects are a special type of `fat object file15<https://en.wikipedia.org/wiki/Fat_binary>`_ that contain LTO compatible IR in16addition to generated object code, instead of containing object code for17multiple target architectures. This allows users to defer the choice of whether18to use LTO or not to link-time, and has been a feature available in other19compilers, like `GCC20<https://gcc.gnu.org/onlinedocs/gccint/LTO-Overview.html>`_, for some time.21 22Under FatLTO the compiler can emit standard object files which contain both the23machine code in the ``.text`` section and LLVM bitcode in the ``.llvm.lto``24section.25 26Overview27========28 29Within LLVM, FatLTO is supported by choosing the ``FatLTODefaultPipeline``.30This 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.. NOTE38 39 Previously, we conservatively ran independent pipelines on separate copies40 of the LLVM module to generate the bitcode section and the object code,41 which happened to be identical to those used outside of FatLTO. While that42 resulted in compiled artifacts that were identical to those produced by the43 default and (Thin)LTO pipelines, module cloning led to some cases of44 miscompilation, and we have moved away from trying to keep bitcode45 generation and optimization completely disjoint.46 47 Bit-for-bit compatibility is not (and never was) a guarantee, and we reserve48 the right to change this at any time. Explicitly, users should not rely on49 the produced bitcode or object code to match their non-LTO counterparts50 precisely. They will exhibit similar performance characteristics, but may51 not be bit-for-bit the same.52 53Internally, the ``.llvm.lto`` section is created by running the54``EmbedBitcodePass`` after the ``ThinLTOPreLinkDefaultPipeline``. This pass is55responsible for emitting the ``.llvm.lto`` section. Afterwards, the56``ThinLTODefaultPipeline`` runs and the compiler can emit the fat object file.57 58Limitations59===========60 61Linkers62-------63 64Currently, using LTO with LLVM fat lto objects is supported by LLD and by the65GNU linkers via :doc:`GoldPlugin`. This may change in the future, but66extending support to other linkers isn't planned for now.67 68.. NOTE69 For standard linking the fat object files should be usable by any70 linker capable of using ELF objects, since the ``.llvm.lto`` section is71 marked ``SHF_EXCLUDE``.72 73Supported File Formats74----------------------75 76The current implementation only supports ELF files. At time of writing, it is77unclear if it will be useful to support other object file formats like ``COFF``78or ``Mach-O``.79 80Usage81=====82 83Clang users can specify ``-ffat-lto-objects`` with ``-flto`` or ``-flto=thin``.84Without the ``-flto`` option, ``-ffat-lto-objects`` has no effect.85 86Compile an object file using FatLTO:87 88.. code-block:: console89 90 $ clang -flto -ffat-lto-objects example.c -c -o example.o91 92Link using the object code from the fat object without LTO. This turns93``-ffat-lto-objects`` into a no-op, when ``-fno-lto`` is specified:94 95.. code-block:: console96 97 $ clang -fno-lto -ffat-lto-objects -fuse-ld=lld example.o98 99Alternatively, you can omit any references to LTO with fat objects and retain standard linker behavior:100 101.. code-block:: console102 103 $ clang -fuse-ld=lld example.o104 105Link using the LLVM bitcode from the fat object with Full LTO:106 107.. code-block:: console108 109 $ clang -flto -ffat-lto-objects -fuse-ld=lld example.o # clang will pass --lto=full --fat-lto-objects to ld.lld110 111Link using the LLVM bitcode from the fat object with Thin LTO:112 113.. code-block:: console114 115 $ clang -flto=thin -ffat-lto-objects -fuse-ld=lld example.o # clang will pass --lto=thin --fat-lto-objects to ld.lld116