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

[Aiden Grossman via Phabricator via llvm-commits]

aidengrossman updated this revision to Diff 475053.
aidengrossman added a comment.

Added documentation on what a CMake cache is, along with where to
find them in the monorepo.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D137898/new/

https://reviews.llvm.org/D137898

Files:
  llvm/docs/AdvancedBuilds.rst


Index: llvm/docs/AdvancedBuilds.rst
===================================================================
--- llvm/docs/AdvancedBuilds.rst
+++ llvm/docs/AdvancedBuilds.rst
@@ -19,6 +19,13 @@
 Unless otherwise explicitly called out these commands should work with any CMake
 generator.
 
+Many of the build configurations mentioned on this documentation page can be
+utilized by using a CMake cache. A CMake cache is essentially a configuration
+file that sets the necessary flags for a specific build configuration. The caches
+for Clang are located in :code:`/clang/cmake/caches` within the monorepo. They
+can be passed to CMake using the :code:`-C` flag as demonstrated in the examples
+below along with additional configuration flags.
+
 Bootstrap Builds
 ================
 
@@ -110,11 +117,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.475053.patch
Type: text/x-patch
Size: 2366 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20221114/6ae1018a/attachment.bin>