1=================== 2FatLTO 3=================== 4.. contents:: 5 :local: 6 :depth: 2 7 8.. toctree:: 9 :maxdepth: 1 10 11Introduction 12============ 13 14FatLTO objects are a special type of `fat object file 15<https://en.wikipedia.org/wiki/Fat_binary>`_ that contain LTO compatible IR in 16addition to generated object code, instead of containing object code for 17multiple target architectures. This allows users to defer the choice of whether 18to use LTO or not to link-time, and has been a feature available in other 19compilers, like `GCC 20<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 the 23machine code in the ``.text`` section and LLVM bitcode in the ``.llvm.lto`` 24section. 25 26Overview 27======== 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.. 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 53Internally, the ``.llvm.lto`` section is created by running the 54``EmbedBitcodePass`` after the ``ThinLTOPreLinkDefaultPipeline``. This pass is 55responsible for emitting the ``.llvm.lto`` section. Afterwards, the 56``ThinLTODefaultPipeline`` runs and the compiler can emit the fat object file. 57 58Limitations 59=========== 60 61Linkers 62------- 63 64Currently, using LTO with LLVM fat lto objects is supported by LLD and by the 65GNU linkers via :doc:`GoldPlugin`. This may change in the future, but 66extending 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 73Supported File Formats 74---------------------- 75 76The current implementation only supports ELF files. At time of writing, it is 77unclear if it will be useful to support other object file formats like ``COFF`` 78or ``Mach-O``. 79 80Usage 81===== 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:: console 89 90 $ clang -flto -ffat-lto-objects example.c -c -o example.o 91 92Link 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 99Alternatively, 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 105Link 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 111Link 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 116