diff --git a/libc/docs/build_concepts.rst b/libc/docs/build_concepts.rst new file mode 100644 index 0000000000000..f613a02128122 --- /dev/null +++ b/libc/docs/build_concepts.rst @@ -0,0 +1,76 @@ +.. _build_concepts: + +============== +Build Concepts +============== + +Most people don't need to build their own C library — the one provided by their +system works well. However, LLVM-libc's **Overlay Mode** can provide key updates +like faster or more consistent math functions for projects that need them. + +For those who do need a full C library, LLVM-libc supports several build +configurations depending on your target environment and intended usage. + +The Five Build Scenarios +======================== + +1. Overlay Mode (Incremental Adoption) +-------------------------------------- + +In Overlay Mode, LLVM-libc functions are compiled alongside the host's existing +system library (like ``glibc``). Only the functions explicitly implemented in +LLVM-libc are used; the rest "fall back" to the system library. This is the +preferred method for most contributors as it is the fastest to build and test. + +To configure for an overlay build, point CMake to the ``runtimes`` directory +and set ``LLVM_LIBC_FULL_BUILD=OFF`` (which is the default). This will build a +static archive named ``libllvmlibc.a``: + +.. code-block:: sh + + cmake -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libc" \ + -DLLVM_LIBC_FULL_BUILD=OFF ... + +2. Full Build Mode (Standalone Library) +--------------------------------------- + +In Full Build Mode, LLVM-libc is a complete replacement for the system library. +This is used to build standalone ``libc.a`` and ``libm.a`` (with separate CMake +targets) for a new operating system or to generate a sysroot for a specific target. + +To configure for a full build, set ``LLVM_LIBC_FULL_BUILD=ON``: + +.. code-block:: sh + + cmake -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \ + -DLLVM_LIBC_FULL_BUILD=ON ... + +3. Bootstrap Build +------------------ + +A bootstrap build first builds the compiler (Clang) and other LLVM tools using +the host compiler, and then uses that newly-built Clang to build the libc. +This ensures you are using a matched toolchain where the compiler and +the library are built for each other. + +To configure a bootstrap build, you point CMake to the ``llvm`` directory: + +.. code-block:: sh + + cmake -S llvm -B build -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" ... + +4. Cross-compiler Build (Targeting Other Architectures) +------------------------------------------------------- + +Used when you want to build LLVM-libc for a different architecture than you are +currently running on (e.g., building on x86_64 for an aarch64 target). +This requires a cross-compiler or a toolchain file. + +5. Bootstrap Cross-compiler (New Environment) +--------------------------------------------- + +For users who are starting from scratch (e.g., with only Linux kernel headers) +and want to generate a full C compiler and sysroot for their target. This is +the most common path for those building entire environments to tinker in. + + diff --git a/libc/docs/full_host_build.rst b/libc/docs/full_host_build.rst index 987a87e6a9157..4fdd2d4b2f7f7 100644 --- a/libc/docs/full_host_build.rst +++ b/libc/docs/full_host_build.rst @@ -23,7 +23,8 @@ Standard Building and Testing For basic development, such as adding new functions or fixing bugs, you can build and test the libc directly without setting up a full sysroot. This approach -is faster and sufficient for most contributors. +is using the **runtimes build** (see :ref:`build_concepts` for more information) +and is faster and sufficient for most contributors. To configure the build, create a build directory and run ``cmake``: @@ -40,8 +41,8 @@ To configure the build, create a build directory and run ``cmake``: -DCMAKE_BUILD_TYPE=Debug \ -DLLVM_LIBC_INCLUDE_SCUDO=ON \ -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \ - -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \ - -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \ + -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \ + -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \ -DLLVM_ENABLE_SPHINX=ON -DLIBC_INCLUDE_DOCS=ON \ -DLIBC_CMAKE_VERBOSE_LOGGING=ON @@ -140,9 +141,10 @@ headers. Step 3: Build and Install Runtimes ---------------------------------- -Now, configure the build for LLVM libc and compiler-rt. We're building with -llvm instead of runtimes because we need to install the -``clang-resource-headers`` that provide ``stdarg.h``, ``stddef.h`` and others. +Now, configure the build for LLVM libc and compiler-rt. We're using the +**bootstrap build** (see :ref:`build_concepts`) because we need to build the +full ``clang`` and then install the ``clang-resource-headers`` that provide +``stdarg.h``, ``stddef.h`` and others. .. code-block:: sh @@ -162,8 +164,7 @@ llvm instead of runtimes because we need to install the -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \ -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF \ -DCOMPILER_RT_BUILD_BUILTINS:BOOL=TRUE \ - -DCOMPILER_RT_BUILD_CRT:BOOL=TRUE \ - -DCOMPILER_RT_BUILD_GWP_ASAN:BOOL=FALSE + -DCOMPILER_RT_BUILD_CRT:BOOL=TRUE After configuring, build and install the necessary components: diff --git a/libc/docs/index.rst b/libc/docs/index.rst index b2ff376629c02..61472da0c5937 100644 --- a/libc/docs/index.rst +++ b/libc/docs/index.rst @@ -62,6 +62,7 @@ levels. See :doc:`contributing` to learn how to help. :caption: Using LLVM-libc getting_started + build_concepts overlay_mode full_host_build full_cross_build