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

[aidengrossman]

Summary

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.

[aidengrossman]

Just adds some more documentation on a (at least what I assume would be) a decently common build configuration since the documentation on the specific flags in these caches is somewhat sparse. Also sets the stage for documenting a PGO/(Thin)LTO/BOLT optimized build, which also takes advantage of these flags as well.

[sylvestre.ledru]

much better, thanks

btw, maybe explains what "cmake cache" means. it is used a bunch in this doc without defining it :)

[aidengrossman]

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

[sylvestre.ledru]

llvm/docs/AdvancedBuilds.rst

22

Perfect, merci!

llvm/docs/AdvancedBuilds.rst

 
 If **you are a new contributor**, please start with the :doc:`GettingStarted` or
 :doc:`CMake` pages. This page is intended for users doing more complex builds.
 
 Many of the examples below are written assuming specific CMake Generators.
 Unless otherwise explicitly called out these commands should work with any CMake
 generator.
 
 Bootstrap Builds
 ================
 
 The Clang CMake build system supports bootstrap (aka multi-stage) builds. At a
 high level a multi-stage build is a chain of builds that pass data from one
 stage into the next. The most common and simple version of this is a traditional
 bootstrap build.
 
 In a simple two-stage bootstrap build, we build clang using the system compiler,

 
 At a high level, the way PGO works is that you build an instrumented compiler,
 then you run the instrumented compiler against sample source files. While the
 instrumented compiler runs it will output a bunch of files containing
 performance counters (.profraw files). After generating all the profraw files
 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
 build directory. This takes a really long time because it builds clang twice,
 and you *must* have compiler-rt in your build tree.
 
 This process uses any source files under the perf-training directory as training
 data as long as the source files are marked up with LIT-style RUN lines.