Update all LLVM documentation mentioning runtimes in LLVM_ENABLE_PROJECTS

We are moving away from building the runtimes with LLVM_ENABLE_PROJECTS,
however the documentation was largely outdated. This commit updates all
the documentation I could find to use LLVM_ENABLE_RUNTIMES instead of
LLVM_ENABLE_PROJECTS for building runtimes.

Note that in the near future, libcxx, libcxxabi and libunwind will stop
supporting being built with LLVM_ENABLE_PROJECTS altogether. I don't know
what the plans are for other runtimes like libc, openmp and compiler-rt,
so I didn't make any changes to the documentation that would imply
something for those projects.

Once this lands, I will also cherry-pick this on the release/14.x branch
to make sure that LLVM's documentation is up-to-date and reflects what
we intend to support in the future.

Differential Revision: https://reviews.llvm.org/D119351

README.md

@@ -63,17 +63,25 @@ This is an example work-flow and configuration to get and build the LLVM source:
 
         Some common options:
 
-        * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
+        * ``-DLLVM_ENABLE_PROJECTS='...'`` and ``-DLLVM_ENABLE_RUNTIMES='...'`` ---
-          sub-projects you'd like to additionally build. Can include any of: clang,
+          semicolon-separated list of the LLVM sub-projects and runtimes you'd like to
-          clang-tools-extra, compiler-rt,cross-project-tests, flang, libc, libclc,
+          additionally build. ``LLVM_ENABLE_PROJECTS`` can include any of: clang,
-          libcxx, libcxxabi, libunwind, lld, lldb, mlir, openmp, polly, or pstl.
+          clang-tools-extra, cross-project-tests, flang, libc, libclc, lld, lldb,
+          mlir, openmp, polly, or pstl. ``LLVM_ENABLE_RUNTIMES`` can include any of
+          libcxx, libcxxabi, libunwind, compiler-rt, libc or openmp. Some runtime
+          projects can be specified either in ``LLVM_ENABLE_PROJECTS`` or in
+          ``LLVM_ENABLE_RUNTIMES``.
 
           For example, to build LLVM, Clang, libcxx, and libcxxabi, use
-          ``-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"``.
+          ``-DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.
 
         * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
           path name of where you want the LLVM tools and libraries to be installed
-          (default ``/usr/local``).
+          (default ``/usr/local``). Be careful if you install runtime libraries: if
+          your system uses those provided by LLVM (like libc++ or libc++abi), you
+          must not overwrite your system's copy of those libraries, since that
+          could render your system unusable. In general, using something like
+          ``/usr`` is not advised, but ``/usr/local`` is fine.
 
         * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
           Release, RelWithDebInfo, and MinSizeRel. Default is Debug.

bolt/docs/OptimizingClang.md

@@ -41,7 +41,7 @@ Collecting accurate profile requires running `perf` on a hardware that
 implements taken branch sampling (`-b/-j` flag). For that reason, it may not be possible to
 collect the accurate profile in a virtualized environment, e.g. in the cloud.
 We do support regular sampling profiles, but the performance
-improvements are expected to be more modest. 
+improvements are expected to be more modest.
 
 ```bash
 $ mkdir ${TOPLEV}/stage3
@@ -211,7 +211,8 @@ $ cd ${TOPLEV}/stage1
 $ cmake -G Ninja ${TOPLEV}/llvm-project/llvm -DLLVM_TARGETS_TO_BUILD=X86 \
       -DCMAKE_BUILD_TYPE=Release \
       -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_ASM_COMPILER=gcc \
-      -DLLVM_ENABLE_PROJECTS="clang;lld;compiler-rt" \
+      -DLLVM_ENABLE_PROJECTS="clang;lld" \
+      -DLLVM_ENABLE_RUNTIMES="compiler-rt" \
       -DCOMPILER_RT_BUILD_SANITIZERS=OFF -DCOMPILER_RT_BUILD_XRAY=OFF \
       -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
       -DCMAKE_INSTALL_PREFIX=${TOPLEV}/stage1/install

clang/docs/DataFlowSanitizer.rst

@@ -32,15 +32,15 @@ libc++ and the libc++ ABI with data flow sanitizer instrumentation.
 
 .. code-block:: console
 
+  mkdir libcxx-build
   cd libcxx-build
 
   # An example using ninja
-  cmake -GNinja path/to/llvm-project/llvm \
+  cmake -GNinja -S <monorepo-root>/runtimes \
     -DCMAKE_C_COMPILER=clang \
     -DCMAKE_CXX_COMPILER=clang++ \
     -DLLVM_USE_SANITIZER="DataFlow" \
-    -DLLVM_ENABLE_LIBCXX=ON \
+    -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"
-    -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi"
 
   ninja cxx cxxabi
 

clang/docs/Toolchain.rst

@@ -230,7 +230,7 @@ libunwind (LLVM)
 ^^^^^^^^^^^^^^^^
 
 LLVM's unwinder library is part of the llvm-project git repository. To
-build it, pass ``-DLLVM_ENABLE_PROJECTS=libunwind`` to the cmake invocation.
+build it, pass ``-DLLVM_ENABLE_RUNTIMES=libunwind`` to the cmake invocation.
 
 If using libc++abi, you may need to configure it to use libunwind
 rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES``

compiler-rt/www/index.html

@@ -112,7 +112,7 @@
   <p>Generally, you need to build LLVM/Clang in order to build compiler-rt. You
     can build it either together with llvm and clang, or separately.
 
-  <p>To build it together, simply add compiler-rt to the -DLLVM_ENABLE_PROJECTS= option to
+  <p>To build it together, simply add compiler-rt to the -DLLVM_ENABLE_RUNTIMES= option to
     cmake.
 
   <p>To build it separately, first

flang/README.md

@@ -33,8 +33,8 @@ read the [style guide](docs/C++style.md)
 and
 also review [how flang uses modern C++ features](docs/C++17.md).
 
-If you are interested in writing new documentation, follow 
+If you are interested in writing new documentation, follow
-[markdown style guide from LLVM](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
+[LLVM's Markdown style guide](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
 
 ## Building flang
 There are two ways to build flang. The first method is to build it at the same
@@ -55,7 +55,7 @@ Note that compiler-rt is only needed to access libraries that support 16 bit
 floating point numbers.  It's not needed to run the automated tests.
 
 Here's a complete set of commands to clone all of the necessary source and do
-the build.  
+the build.
 
 First clone the source:
 ```bash
@@ -79,7 +79,8 @@ cmake \
   -DLLVM_TARGETS_TO_BUILD=host \
   -DCMAKE_INSTALL_PREFIX=$INSTALLDIR
   -DLLVM_LIT_ARGS=-v \
-  -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;compiler-rt"
+  -DLLVM_ENABLE_PROJECTS="clang;mlir;flang" \
+  -DLLVM_ENABLE_RUNTIMES="compiler-rt"
 
 ninja
 ```

libcxx/docs/BuildingLibcxx.rst

@@ -523,8 +523,8 @@ We can now run CMake:
 
 .. code-block:: bash
 
-  $ cmake -G Ninja -S llvm -B build           \
+  $ cmake -G Ninja -S runtimes -B build       \
-    -DLLVM_ENABLE_PROJECTS="libcxx"           \
+    -DLLVM_ENABLE_RUNTIMES="libcxx"           \
     -DLIBCXX_CXX_ABI=libstdc++                \
     -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
   $ ninja -C build install-cxx
@@ -549,8 +549,8 @@ We can now run CMake like:
 
 .. code-block:: bash
 
-  $ cmake -G Ninja -S llvm -B build                                   \
+  $ cmake -G Ninja -S runtimes -B build                               \
-          -DLLVM_ENABLE_PROJECTS="libcxx"                             \
+          -DLLVM_ENABLE_RUNTIMES="libcxx"                             \
           -DLIBCXX_CXX_ABI=libcxxrt                                   \
           -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src
   $ ninja -C build install-cxx

libunwind/docs/BuildingLibunwind.rst

@@ -32,7 +32,7 @@ The basic steps needed to build libc++ are:
    * ``cd where you want to build llvm``
    * ``mkdir build``
    * ``cd build``
-   * ``cmake -G <generator> -DLLVM_ENABLE_PROJECTS=libunwind [options] <path to llvm sources>``
+   * ``cmake -G <generator> -DLLVM_ENABLE_RUNTIMES=libunwind [options] <llvm-monorepo>/runtimes``
 
    For more information about configuring libunwind see :ref:`CMake Options`.
 

llvm/docs/BuildingADistribution.rst

@@ -199,8 +199,8 @@ Relevant CMake Options
 This section provides documentation of the CMake options that are intended to
 help construct distributions. This is not an exhaustive list, and many
 additional options are documented in the :doc:`CMake` page. Some key options
-that are already documented include: *LLVM_TARGETS_TO_BUILD*,
+that are already documented include: *LLVM_TARGETS_TO_BUILD*, *LLVM_ENABLE_PROJECTS*,
-*LLVM_ENABLE_PROJECTS*, *LLVM_BUILD_LLVM_DYLIB*, and *LLVM_LINK_LLVM_DYLIB*.
+*LLVM_ENABLE_RUNTIMES*, *LLVM_BUILD_LLVM_DYLIB*, and *LLVM_LINK_LLVM_DYLIB*.
 
 **LLVM_ENABLE_RUNTIMES**:STRING
   When building a distribution that includes LLVM runtime projects (i.e. libcxx,

llvm/docs/CMake.rst

@@ -221,6 +221,10 @@ description is in `LLVM-related variables`_ below.
   Control which projects are enabled. For example you may want to work on clang
   or lldb by specifying ``-DLLVM_ENABLE_PROJECTS="clang;lldb"``.
 
+**LLVM_ENABLE_RUNTIMES**:STRING
+  Control which runtimes are enabled. For example you may want to work on
+  libc++ or libc++abi by specifying ``-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.
+
 **LLVM_LIBDIR_SUFFIX**:STRING
   Extra suffix to append to the directory where libraries are to be
   installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
@@ -505,17 +509,17 @@ enabled sub-projects. Nearly all of these variable names begin with
 
 **LLVM_ENABLE_PROJECTS**:STRING
   Semicolon-separated list of projects to build, or *all* for building all
-  (clang, lldb, compiler-rt, lld, polly, etc) projects. This flag assumes
+  (clang, lldb, lld, polly, etc) projects. This flag assumes that projects
-  that projects are checked out side-by-side and not nested, i.e. clang
+  are checked out side-by-side and not nested, i.e. clang needs to be in
-  needs to be in parallel of llvm instead of nested in `llvm/tools`.
+  parallel of llvm instead of nested in `llvm/tools`. This feature allows
-  This feature allows to have one build for only LLVM and another for clang+llvm
+  to have one build for only LLVM and another for clang+llvm using the same
-  using the same source checkout.
+  source checkout.
   The full list is:
-  ``clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;lld;lldb;openmp;polly;pstl``
+  ``clang;clang-tools-extra;cross-project-tests;libc;libclc;lld;lldb;openmp;polly;pstl``
 
 **LLVM_ENABLE_RUNTIMES**:STRING
-  Build libc++, libc++abi or other projects using that a just-built compiler.
+  Build libc++, libc++abi, libunwind or compiler-rt using the just-built compiler.
-  This is the correct way to build libc++ when putting together a toolchain.
+  This is the correct way to build runtimes when putting together a toolchain.
   It will build the builtins separately from the other runtimes to preserve
   correct dependency ordering. If you want to build the runtimes using a system
   compiler, see the `libc++ documentation <https://libcxx.llvm.org/BuildingLibcxx.html>`_.

llvm/docs/GettingStarted.rst

@@ -623,10 +623,15 @@ used by people developing LLVM.
 |                         | other LLVM subprojects to additionally build. (Only|
 |                         | effective when using a side-by-side project layout |
 |                         | e.g. via git). The default list is empty. Can      |
-|                         | include: clang, clang-tools-extra, compiler-rt,    |
+|                         | include: clang, clang-tools-extra,                 |
-|                         | cross-project-tests, flang, libc, libclc, libcxx,  |
+|                         | cross-project-tests, flang, libc, libclc, lld,     |
-|                         | libcxxabi, libunwind, lld, lldb, mlir, openmp,     |
+|                         | lldb, mlir, openmp, polly, or pstl.                |
-|                         | polly, or pstl.                                    |
++-------------------------+----------------------------------------------------+
+| LLVM_ENABLE_RUNTIMES    | A semicolon-delimited list selecting which of the  |
+|                         | runtimes to build. (Only effective when using the  |
+|                         | full monorepo layout). The default list is empty.  |
+|                         | Can include: compiler-rt, libc, libcxx, libcxxabi, |
+|                         | libunwind, or openmp.                              |
 +-------------------------+----------------------------------------------------+
 | LLVM_ENABLE_SPHINX      | Build sphinx-based documentation from the source   |
 |                         | code. This is disabled by default because it is    |
@@ -1217,6 +1222,11 @@ following options with cmake:
    compiling more than one project, separate the items with a semicolon. Should
    you run into issues with the semicolon, try surrounding it with single quotes.
 
+* -DLLVM_ENABLE_RUNTIMES
+   Set this equal to the runtimes you wish to compile (e.g. libcxx, libcxxabi, etc.)
+   If compiling more than one runtime, separate the items with a semicolon. Should
+   you run into issues with the semicolon, try surrounding it with single quotes.
+
  * -DCLANG_ENABLE_STATIC_ANALYZER
    Set this option to OFF if you do not require the clang static analyzer. This
    should improve your build time slightly.