[llvm] [docs][NFC] Add usage instructions for FatLTO (PR #75853)

[Paul Kirth via llvm-commits]

https://github.com/ilovepi updated https://github.com/llvm/llvm-project/pull/75853

>From a879e37daad6a1bec3c0b48215afd7e5e4394e9d Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulkirth at google.com>
Date: Mon, 18 Dec 2023 12:54:29 -0800
Subject: [PATCH 1/2] [docs] Add usage instructions for FatLTO

We included these in the commit message when we added
`-ffat-lto-objects`, but they should be in the documentation as well.
---
 llvm/docs/FatLTO.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/llvm/docs/FatLTO.rst b/llvm/docs/FatLTO.rst
index 21da24504bcdf6..bc4051f2d9ec62 100644
--- a/llvm/docs/FatLTO.rst
+++ b/llvm/docs/FatLTO.rst
@@ -76,3 +76,56 @@ 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
+===========
+
+Users are expected to pass ``-ffat-lto-objects`` to clang in addition to one of
+the ``-flto`` variants. Without the ``-flto`` flag, ``-ffat-lto-objects`` has
+no effect.
+
+
+Compile and link. Use the object code from the fat object without LTO.
+
+.. code-block:: console
+
+   $ clang -fno-lto -ffat-lto-objects -fuse-ld=lld foo.c
+
+Compile and link. Select full LTO at link time.
+
+.. code-block:: console
+
+   $ clang -flto -ffat-lto-objects -fuse-ld=lld foo.c
+
+Compile and link. Select ThinLTO at link time.
+
+.. code-block:: console
+
+   $ clang -flto=thin -ffat-lto-objects -fuse-ld=lld foo.c
+
+Compile and link. Use ThinLTO with the UnifiedLTO pipeline.
+
+.. code-block:: console
+
+   $ clang -flto=thin -ffat-lto-objects -funified-lto -fuse-ld=lld foo.c
+
+Compile and link. Use full LTO  with the UnifiedLTO pipeline.
+
+.. code-block:: console
+
+   $ clang -flto -ffat-lto-objects -funified-lto -fuse-ld=lld foo.c
+
+Link separately, using ThinLTO.
+
+.. code-block:: console
+
+   $ clang -c -flto=thin -ffat-lto-objects foo.c
+   $ clang -flto=thin -fuse-ld=lld foo.o -ffat-lto-objects  # pass --lto=thin --fat-lto-objects to ld.lld
+
+Link separately, using full LTO.
+
+.. code-block:: console
+
+   $ clang -c -flto -ffat-lto-objects foo.c
+   $ clang -flto -fuse-ld=lld foo.o  # pass --lto=full --fat-lto-objects to ld.lld
+

>From fbdee927a4b4aafaa22f6d3ecf71bbac51fe7d2f Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulkirth at google.com>
Date: Mon, 18 Dec 2023 13:34:04 -0800
Subject: [PATCH 2/2] !fixup Address comments

Rename foo.c to example.c

Remove UnifiedLTO examples, since FatLTO always uses that pipeline now.
---
 llvm/docs/FatLTO.rst | 22 +++++-----------------
 1 file changed, 5 insertions(+), 17 deletions(-)

diff --git a/llvm/docs/FatLTO.rst b/llvm/docs/FatLTO.rst
index bc4051f2d9ec62..537053a5452e8c 100644
--- a/llvm/docs/FatLTO.rst
+++ b/llvm/docs/FatLTO.rst
@@ -89,43 +89,31 @@ Compile and link. Use the object code from the fat object without LTO.
 
 .. code-block:: console
 
-   $ clang -fno-lto -ffat-lto-objects -fuse-ld=lld foo.c
+   $ clang -fno-lto -ffat-lto-objects -fuse-ld=lld example.c
 
 Compile and link. Select full LTO at link time.
 
 .. code-block:: console
 
-   $ clang -flto -ffat-lto-objects -fuse-ld=lld foo.c
+   $ clang -flto -ffat-lto-objects -fuse-ld=lld example.c
 
 Compile and link. Select ThinLTO at link time.
 
 .. code-block:: console
 
-   $ clang -flto=thin -ffat-lto-objects -fuse-ld=lld foo.c
-
-Compile and link. Use ThinLTO with the UnifiedLTO pipeline.
-
-.. code-block:: console
-
-   $ clang -flto=thin -ffat-lto-objects -funified-lto -fuse-ld=lld foo.c
-
-Compile and link. Use full LTO  with the UnifiedLTO pipeline.
-
-.. code-block:: console
-
-   $ clang -flto -ffat-lto-objects -funified-lto -fuse-ld=lld foo.c
+   $ clang -flto=thin -ffat-lto-objects -fuse-ld=lld example.c
 
 Link separately, using ThinLTO.
 
 .. code-block:: console
 
-   $ clang -c -flto=thin -ffat-lto-objects foo.c
+   $ clang -c -flto=thin -ffat-lto-objects example.c
    $ clang -flto=thin -fuse-ld=lld foo.o -ffat-lto-objects  # pass --lto=thin --fat-lto-objects to ld.lld
 
 Link separately, using full LTO.
 
 .. code-block:: console
 
-   $ clang -c -flto -ffat-lto-objects foo.c
+   $ clang -c -flto -ffat-lto-objects example.c
    $ clang -flto -fuse-ld=lld foo.o  # pass --lto=full --fat-lto-objects to ld.lld