[runtimes] Use the new "runtimes" build by default and deprecate othe…

…r builds

This commit makes the new "runtimes" build (with <monorepo>/runtimes as
the root of the CMake invocation) the default way of building libc++.
The other supported way of building libc++ is the "bootstrapping" build,
where `<monorepo>/llvm` is used as the root of the CMake invocation.

All other ways of building libc++ are deprecated effective immediately.
There should be no use-case for building libc++ that isn't supported by
one of these two builds, and the two new builds work on all environments
and are lightweight. They will also make it possible to greatly simplify
the build infrastructure of the runtimes, which is currently way too
convoluted.

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

libcxx/docs/BuildingLibcxx.rst

@@ -25,50 +25,58 @@ libc++ :ref:`here <using-libcxx>`.
 The default build
 =================
 
-By default, libc++ and libc++abi are built as sub-projects of the LLVM project.
-This can be achieved with the usual CMake invocation:
+The default way of building libc++, libc++abi and libunwind is to root the CMake
+invocation at ``<monorepo>/runtimes``. While those projects are under the LLVM
+umbrella, they are different in nature from other build tools, so it makes sense
+to treat them as a separate set of entities. The default build can be achieved
+with the following CMake invocation:
 
 .. code-block:: bash
 
   $ git clone https://github.com/llvm/llvm-project.git
   $ cd llvm-project
   $ mkdir build
-  $ cmake -G Ninja -S llvm -B build -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" # Configure
-  $ ninja -C build cxx cxxabi                                                 # Build
-  $ ninja -C build check-cxx check-cxxabi                                     # Test
-  $ ninja -C build install-cxx install-cxxabi                                 # Install
+  $ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" # Configure
+  $ ninja -C build cxx cxxabi unwind                                                        # Build
+  $ ninja -C build check-cxx check-cxxabi check-unwind                                      # Test
+  $ ninja -C build install-cxx install-cxxabi install-unwind                                # Install
 
 .. note::
   See :ref:`CMake Options` below for more configuration options.
 
-After building the ``install-cxx`` and ``install-cxxabi`` targets, shared libraries
-for libc++ and libc++abi should now be present in ``<CMAKE_INSTALL_PREFIX>/lib``, and
-headers in ``<CMAKE_INSTALL_PREFIX>/include/c++/v1``. See :ref:`using an alternate
-libc++ installation <alternate libcxx>` for information on how to use this libc++ over
-the default one.
+After building the various ``install-XXX`` targets, shared libraries for libc++, libc++abi and
+libunwind should now be present in ``<CMAKE_INSTALL_PREFIX>/lib``, and headers in
+``<CMAKE_INSTALL_PREFIX>/include/c++/v1``. See :ref:`using an alternate libc++ installation
+<alternate libcxx>` for information on how to use this libc++ over the default one.
 
-In the default configuration, libc++ and libc++abi will be built using the compiler available
-by default on your system. It is also possible to bootstrap Clang and build libc++ with it.
+In the default configuration, the runtimes will be built using the compiler available by default
+on your system. Of course, you can change what compiler is being used with the usual CMake
+variables. If you wish to build the runtimes from a just-built Clang, the bootstrapping build
+explained below makes this task easy.
 
 
 Bootstrapping build
 ===================
 
-It is also possible to build Clang and then build libc++ and libc++abi using that
-just-built compiler. This is the correct way to build libc++ when putting together
-a toolchain, or when the system compiler is not adequate to build libc++ (too old,
-unsupported, etc.). This type of build is also commonly called a "Runtimes build":
+It is possible to build Clang and then build the runtimes using that just-built compiler in a
+single CMake invocation. This is usually the correct way to build the runtimes when putting together
+a toolchain, or when the system compiler is not adequate to build them (too old, unsupported, etc.).
+To do this, use the following CMake invocation, and in particular notice how we're now rooting the
+CMake invocation at ``<monorepo>/llvm``:
 
 .. code-block:: bash
 
   $ mkdir build
-  $ cmake -G Ninja -S llvm -B build -DLLVM_ENABLE_PROJECTS="clang"            \  # Configure
-                                    -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \
+  $ cmake -G Ninja -S llvm -B build -DLLVM_ENABLE_PROJECTS="clang"                      \  # Configure
+                                    -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
                                     -DLLVM_RUNTIME_TARGETS="<target-triple>"
-  $ ninja -C build runtimes                                                      # Build
-  $ ninja -C build check-runtimes                                                # Test
-  $ ninja -C build install-runtimes                                              # Install
+  $ ninja -C build runtimes                                                                # Build
+  $ ninja -C build check-runtimes                                                          # Test
+  $ ninja -C build install-runtimes                                                        # Install
 
+.. note::
+  This type of build is also commonly called a "Runtimes build", but we would like to move
+  away from that terminology, which is too confusing.
 
 Support for Windows
 ===================

libcxx/docs/ReleaseNotes.rst

@@ -57,8 +57,8 @@ Build System Changes
 --------------------
 
 - Building the libc++ shared or static library requires a C++ 20 capable compiler.
-  Use ``-DLLVM_ENABLE_PROJECTS='clang;compiler-rt' -DLLVM_ENABLE_RUNTIMES='libcxx;libcxxabi'``
-  to build libc++ using a fresh build of Clang.
+  Consider using a Bootstrapping build to build libc++ with a fresh Clang if you
+  can't use the system compiler to build libc++ anymore.
 
 - The functions ``std::atomic<T*>::fetch_(add|sub)`` and
   ``std::atomic_fetch_(add|sub)`` no longer accept a function pointer. While
@@ -77,3 +77,35 @@ Build System Changes
 
   Calls to these functions where the template argument was deduced by the
   compiler are unaffected by this change.
+
+- Historically, there has been numerous ways of building libc++ and libc++abi. This has
+  culminated in over 5 different ways to build the runtimes, which made it impossible to
+  maintain with a good level of support. Starting with this release, the runtimes support
+  exactly two ways of being built, which should cater to all use-cases. Furthermore,
+  these builds are as lightweight as possible and will work consistently even when targetting
+  embedded platforms, which used not to be the case. Please see the documentation on building
+  libc++ to see those two ways of building and migrate over to the appropriate build instructions
+  as soon as possible.
+
+  All other ways to build are deprecated and will not be supported in the next release.
+  We understand that making these changes can be daunting. For that reason, here's a
+  summary of how to migrate from the two most common ways to build:
+
+  - If you were rooting your CMake invocation at ``<monorepo>/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>``
+    (which was the previously advertised way to build the runtimes), please simply root your CMake invocation at
+    ``<monorepo>/runtimes`` and pass ``-DLLVM_ENABLE_RUNTIMES=<...>``.
+
+  - If you were doing two CMake invocations, one rooted at ``<monorepo>/libcxx`` and one rooted at
+    ``<monorepo>/libcxxabi`` (this used to be called a "Standalone build"), please move them to a
+    single invocation like so:
+
+    .. code-block:: bash
+
+        $ cmake -S <monorepo>/libcxx -B libcxx-build <LIBCXX-OPTIONS>
+        $ cmake -S <monorepo>/libcxxabi -B libcxxabi-build <LIBCXXABI-OPTIONS>
+
+    should become
+
+    .. code-block:: bash
+
+        $ cmake -S <monorepo>/runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" <LIBCXX-OPTIONS> <LIBCXXABI-OPTIONS>

libcxx/utils/ci/buildkite-pipeline.yml

@@ -267,8 +267,8 @@ steps:
           limit: 2
     timeout_in_minutes: 120
 
-  - label: "New standalone runtimes build"
-    command: "libcxx/utils/ci/run-buildbot new-standalone"
+  - label: "Legacy LLVM_ENABLE_PROJECTS build"
+    command: "libcxx/utils/ci/run-buildbot legacy-project-build"
     artifact_paths:
       - "**/test-results.xml"
     agents:

libcxx/utils/ci/run-buildbot

@@ -78,6 +78,7 @@ function clean() {
 function generate-cmake-base() {
     echo "--- Generating CMake"
     ${CMAKE} \
+          -S "${MONOREPO_ROOT}/runtimes" \
           -B "${BUILD_DIR}" \
           -GNinja -DCMAKE_MAKE_PROGRAM="${NINJA}" \
           -DCMAKE_BUILD_TYPE=RelWithDebInfo \
@@ -88,8 +89,7 @@ function generate-cmake-base() {
 
 function generate-cmake() {
     generate-cmake-base \
-          -S "${MONOREPO_ROOT}/llvm" \
-          -DLLVM_ENABLE_PROJECTS="libcxx;libunwind;libcxxabi" \
+          -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
           -DLIBCXX_CXX_ABI=libcxxabi \
           "${@}"
 }
@@ -104,7 +104,7 @@ function generate-cmake-libcxx-win() {
     # even if it uses a non-permanent ABI.
 
     generate-cmake-base \
-          -S "${MONOREPO_ROOT}/libcxx" \
+          -DLLVM_ENABLE_RUNTIMES="libcxx" \
           -DCMAKE_C_COMPILER=clang-cl \
           -DCMAKE_CXX_COMPILER=clang-cl \
           -DLIBCXX_ENABLE_FILESYSTEM=YES \
@@ -437,21 +437,6 @@ documentation)
     echo "+++ Generating documentation"
     ${NINJA} -vC "${BUILD_DIR}" docs-libcxx-html
 ;;
-new-standalone)
-    clean
-
-    echo "--- Generating CMake"
-    ${CMAKE} \
-          -S "${MONOREPO_ROOT}/runtimes" \
-          -B "${BUILD_DIR}" \
-          -GNinja -DCMAKE_MAKE_PROGRAM="${NINJA}" \
-          -DCMAKE_BUILD_TYPE=RelWithDebInfo \
-          -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
-          -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
-          -DLIBCXX_TEST_CONFIG="llvm-libc++-shared.cfg.in"
-
-    check-runtimes
-;;
 runtimes-build)
     clean
 
@@ -484,6 +469,21 @@ legacy-test-config)
     generate-cmake -DLIBCXX_TEST_CONFIG="legacy.cfg.in"
     check-runtimes
 ;;
+legacy-project-build)
+    clean
+
+    echo "--- Generating CMake"
+    ${CMAKE} \
+          -S "${MONOREPO_ROOT}/llvm" \
+          -B "${BUILD_DIR}" \
+          -DLLVM_ENABLE_PROJECTS="libcxx;libunwind;libcxxabi" \
+          -GNinja -DCMAKE_MAKE_PROGRAM="${NINJA}" \
+          -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+          -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
+          -DLLVM_LIT_ARGS="-sv --show-unsupported --xunit-xml-output test-results.xml" \
+          -DLIBCXX_CXX_ABI=libcxxabi
+    check-runtimes
+;;
 legacy-standalone)
     clean
 

runtimes/CMakeLists.txt

@@ -117,6 +117,8 @@ if (NOT LLVM_DEFAULT_TARGET_TRIPLE)
 endif()
 
 option(LLVM_INCLUDE_TESTS "Generate build targets for the runtimes unit tests." ON)
+option(LLVM_INCLUDE_DOCS "Generate build targets for the runtimes documentation." ON)
+option(LLVM_ENABLE_SPHINX "Use Sphinx to generate the runtimes documentation." OFF)
 
 # Use libtool instead of ar if you are both on an Apple host, and targeting Apple.
 if(CMAKE_HOST_APPLE AND APPLE)