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

[libc][docs][NFC] Add Build Concepts page with five build scenarios

Added build_concepts.rst defining the five ways to build LLVM-libc:

overlay, full build, bootstrap, cross-compiler, and bootstrap
cross-compiler. Updated full_host_build.rst to cross-reference the new
concepts page for both the runtimes and bootstrap build sections, and
removed a duplicate GWP_ASAN flag from the sysroot CMake recipe. Added
the new page to index.rst.

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.
+
+

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:
 

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