[PATCH] D137898: [Docs] Add Documentation on (Thin)LTO + PGO Build Configs

[Aiden Grossman via Phabricator via llvm-commits]

aidengrossman created this revision.
Herald added subscribers: wenlei, inglorion.
Herald added a project: All.
aidengrossman requested review of this revision.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

This patch adds documentation on the AdvancedBuilds page on how to do
PGO builds with (Thin)LTO with the currently undocumented (as far as I
can tell) PGO_INSTRUMENT_LTO option in the Clang PGO caches.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D137898

Files:
  llvm/docs/AdvancedBuilds.rst


Index: llvm/docs/AdvancedBuilds.rst
===================================================================
--- llvm/docs/AdvancedBuilds.rst
+++ llvm/docs/AdvancedBuilds.rst
@@ -110,11 +110,34 @@
 you use llvm-profdata to merge the files into a single profdata file that you
 can feed into the LLVM_PROFDATA_FILE option.
 
-Our PGO.cmake cache automates that whole process. You can use it by running:
+Our PGO.cmake cache automates that whole process. You can use it for
+configuration with CMake with the following command:
+
+.. code-block:: console
+
+  $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake \
+      <path to source>/llvm
+
+There are several additional options that the cache file also accepts to modify
+the build, particularly the PGO_INSTRUMENT_LTO option. Setting this option to
+Thin or Full will enable ThinLTO or full LTO respectively, further enhancing
+the performance gains from a PGO build by enabling interprocedural
+optimizations. For example, to run a CMake configuration for a PGO build
+that also enables ThinTLO, use the following command:
+
+.. code-block:: console
+
+  $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake \
+      -DPGO_INSTRUMENT_LTO=Thin \
+      <path to source>/llvm
+
+After configuration, building the stage2-instrumented-generate-profdata target
+will automatically build the stage1 compiler, build the instrumented compiler
+with the stage1 compiler, and then run the instrumented compiler against the
+perf training data:
 
 .. code-block:: console
 
-  $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake <path to source>
   $ ninja stage2-instrumented-generate-profdata
 
 If you let that run for a few hours or so, it will place a profdata file in your


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D137898.474974.patch
Type: text/x-patch
Size: 1759 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20221113/6f1387cd/attachment.bin>