[libc-commits] [libc] [libc][docs][NFC] Add Build Concepts and consolidate patterns (PR #187490)

[Jeff Bailey via libc-commits]

https://github.com/kaladron created https://github.com/llvm/llvm-project/pull/187490

Created the Build Concepts guide and unified build patterns across documentation:

* libc/docs/build_concepts.rst: Added a new page defining Runtimes vs. Bootstrap build methods and the standardized Scudo flag block.
* libc/docs/full_host_build.rst: Updated building and testing guides to reference the new concepts page, unified Scudo configurations, and fixed duplicate GWP_ASAN flags in the sysroot CMake recipe.
* libc/docs/index.rst: Added the Build Concepts guide to the project site structure.

>From c133b6f47e9fc6df70fd0caa13d123b8fb9ae421 Mon Sep 17 00:00:00 2001
From: Jeff Bailey <jeffbailey at google.com>
Date: Wed, 18 Mar 2026 23:07:23 +0000
Subject: [PATCH] [libc][docs][NFC] Add Build Concepts and consolidate patterns

Created the Build Concepts guide and unified build patterns across
documentation:

* libc/docs/build_concepts.rst: Added a new page defining Runtimes vs.
  Bootstrap build methods and the standardized Scudo flag block.
* libc/docs/full_host_build.rst: Updated building and testing guides to
  reference the new concepts page, unified Scudo configurations, and fixed
  duplicate GWP_ASAN flags in the sysroot CMake recipe.
* libc/docs/index.rst: Added the Build Concepts guide to the project
  site structure.
---
 libc/docs/build_concepts.rst  | 75 +++++++++++++++++++++++++++++++++++
 libc/docs/full_host_build.rst | 17 ++++----
 libc/docs/index.rst           |  1 +
 3 files changed, 85 insertions(+), 8 deletions(-)
 create mode 100644 libc/docs/build_concepts.rst

diff --git a/libc/docs/build_concepts.rst b/libc/docs/build_concepts.rst
new file mode 100644
index 0000000000000..054f5b1cd7514
--- /dev/null
+++ b/libc/docs/build_concepts.rst
@@ -0,0 +1,75 @@
+.. _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):
+
+.. code-block:: sh
+
+   cmake -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
+         -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 a standalone ``libc.a`` 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