[llvm] 8190e09 - [docs][NFC] Add usage instructions for FatLTO (#75853)

[via llvm-commits]

Author: Paul Kirth
Date: 2023-12-19T10:44:18-08:00
New Revision: 8190e09e680033598fff24e919836cdfa8e98a9c

URL: https://github.com/llvm/llvm-project/commit/8190e09e680033598fff24e919836cdfa8e98a9c
DIFF: https://github.com/llvm/llvm-project/commit/8190e09e680033598fff24e919836cdfa8e98a9c.diff

LOG: [docs][NFC] Add usage instructions for FatLTO (#75853)

We included these in the commit message when we added
`-ffat-lto-objects`, but they should be in the documentation as well.

Added: 
    

Modified: 
    llvm/docs/FatLTO.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/FatLTO.rst b/llvm/docs/FatLTO.rst
index 21da24504bcdf6..76b849b16fc967 100644
--- a/llvm/docs/FatLTO.rst
+++ b/llvm/docs/FatLTO.rst
@@ -76,3 +76,40 @@ Supported File Formats
 The current implementation only supports ELF files. At time of writing, it is
 unclear if it will be useful to support other object file formats like ``COFF``
 or ``Mach-O``.
+
+Usage
+=====
+
+Clang users can specify ``-ffat-lto-objects`` with ``-flto`` or ``-flto=thin``.
+Without the ``-flto`` option, ``-ffat-lto-objects`` has no effect.
+
+Compile an object file using FatLTO:
+
+.. code-block:: console
+
+   $ clang -flto -ffat-lto-objects example.c -c -o example.o
+
+Link using the object code from the fat object without LTO. This turns
+``-ffat-lto-objects`` into a no-op, when ``-fno-lto`` is specified:
+
+.. code-block:: console
+
+   $ clang -fno-lto -ffat-lto-objects -fuse-ld=lld example.o
+
+Alternatively, you can omit any references to LTO with fat objects and retain standard linker behavior:
+
+.. code-block:: console
+
+   $ clang -fuse-ld=lld example.o
+
+Link using the LLVM bitcode from the fat object with Full LTO:
+
+.. code-block:: console
+
+   $ clang -flto -ffat-lto-objects -fuse-ld=lld example.o  # clang will pass --lto=full --fat-lto-objects to ld.lld
+
+Link using the LLVM bitcode from the fat object with Thin LTO:
+
+.. code-block:: console
+
+   $ clang -flto=thin -ffat-lto-objects -fuse-ld=lld example.o  # clang will pass --lto=thin --fat-lto-objects to ld.lld