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
===================
--------------------
- 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
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>
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:
function generate-cmake-base() {
echo "--- Generating CMake"
${CMAKE} \
+ -S "${MONOREPO_ROOT}/runtimes" \
-B "${BUILD_DIR}" \
-GNinja -DCMAKE_MAKE_PROGRAM="${NINJA}" \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
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 \
"${@}"
}
# 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 \
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
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
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)
projects / platform / upstream / llvm.git / commitdiff