diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/BuildingLibcxx.rst --- a/libcxx/docs/BuildingLibcxx.rst +++ b/libcxx/docs/BuildingLibcxx.rst @@ -25,50 +25,58 @@ 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 ``/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 ``/lib``, and -headers in ``/include/c++/v1``. See :ref:`using an alternate -libc++ installation ` 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 ``/lib``, and headers in +``/include/c++/v1``. See :ref:`using an alternate libc++ installation +` 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 ``/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="" - $ 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 =================== diff --git a/libcxx/docs/ReleaseNotes.rst b/libcxx/docs/ReleaseNotes.rst --- a/libcxx/docs/ReleaseNotes.rst +++ b/libcxx/docs/ReleaseNotes.rst @@ -57,8 +57,8 @@ -------------------- - 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::fetch_(add|sub)`` and ``std::atomic_fetch_(add|sub)`` no longer accept a function pointer. While @@ -77,3 +77,35 @@ 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 ``/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>`` + (which was the previously advertised way to build the runtimes), please simply root your CMake invocation at + ``/runtimes`` and pass ``-DLLVM_ENABLE_RUNTIMES=<...>``. + + - If you were doing two CMake invocations, one rooted at ``/libcxx`` and one rooted at + ``/libcxxabi`` (this used to be called a "Standalone build"), please move them to a + single invocation like so: + + .. code-block:: bash + + $ cmake -S /libcxx -B libcxx-build + $ cmake -S /libcxxabi -B libcxxabi-build + + should become + + .. code-block:: bash + + $ cmake -S /runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" diff --git a/libcxx/utils/ci/buildkite-pipeline.yml b/libcxx/utils/ci/buildkite-pipeline.yml --- a/libcxx/utils/ci/buildkite-pipeline.yml +++ b/libcxx/utils/ci/buildkite-pipeline.yml @@ -267,8 +267,8 @@ 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: diff --git a/libcxx/utils/ci/run-buildbot b/libcxx/utils/ci/run-buildbot --- a/libcxx/utils/ci/run-buildbot +++ b/libcxx/utils/ci/run-buildbot @@ -78,6 +78,7 @@ 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() { 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 @@ # 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 @@ 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 @@ 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 diff --git a/runtimes/CMakeLists.txt b/runtimes/CMakeLists.txt --- a/runtimes/CMakeLists.txt +++ b/runtimes/CMakeLists.txt @@ -117,6 +117,8 @@ 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)