[libc-commits] [libc] [libc][docs][NFC] Restructure Getting Started guide and update Build … (PR #187701)
Jeff Bailey via libc-commits
libc-commits at lists.llvm.org
Fri Mar 20 07:04:40 PDT 2026
https://github.com/kaladron created https://github.com/llvm/llvm-project/pull/187701
…Concepts
Restructured the Getting Started guide into a numbered step-by-step path for easier readability. Added a Hello World verification step to confirm build integrity after build completion.
Additionally, updated build_concepts.rst and the Getting Started guide to clarify that Overlay Mode is intended for augmenting the system's C library rather than incremental adoption.
>From f147b440ec4eec050bbf4ce437e221fa833b37da Mon Sep 17 00:00:00 2001
From: Jeff Bailey <jbailey at raspberryginger.com>
Date: Fri, 20 Mar 2026 13:47:46 +0000
Subject: [PATCH] [libc][docs][NFC] Restructure Getting Started guide and
update Build Concepts
Restructured the Getting Started guide into a numbered step-by-step
path for easier readability. Added a Hello World verification step
to confirm build integrity after build completion.
Additionally, updated build_concepts.rst and the Getting Started guide
to clarify that Overlay Mode is intended for augmenting the system's
C library rather than incremental adoption.
---
libc/docs/build_concepts.rst | 4 +-
libc/docs/getting_started.rst | 117 +++++++++++++++++++++++-----------
2 files changed, 81 insertions(+), 40 deletions(-)
diff --git a/libc/docs/build_concepts.rst b/libc/docs/build_concepts.rst
index f613a02128122..04571c4bb9198 100644
--- a/libc/docs/build_concepts.rst
+++ b/libc/docs/build_concepts.rst
@@ -14,8 +14,8 @@ configurations depending on your target environment and intended usage.
The Five Build Scenarios
========================
-1. Overlay Mode (Incremental Adoption)
---------------------------------------
+1. Overlay Mode (Augmenting the System Libc)
+--------------------------------------------
In Overlay Mode, LLVM-libc functions are compiled alongside the host's existing
system library (like ``glibc``). Only the functions explicitly implemented in
diff --git a/libc/docs/getting_started.rst b/libc/docs/getting_started.rst
index 9d846e6d22acf..7508dcff73e6e 100644
--- a/libc/docs/getting_started.rst
+++ b/libc/docs/getting_started.rst
@@ -1,58 +1,99 @@
+.. _getting_started:
+
+===============
Getting Started
===============
-Let's fetch the llvm-libc sources and build them.
+This guide provides a single, robust path for new users and contributors to
+build, test, and verify LLVM-libc. We use the **runtimes build** (see
+:ref:`build_concepts` for more information) because it is faster and sufficient
+for most development tasks.
+
+1. Install Dependencies
+=======================
+
+To build LLVM-libc, you will need a recent version of Clang (v15+) and basic
+build tools. On a Debian/Ubuntu-based system, you can install these using
+``apt-get``:
+
+.. code-block:: sh
+
+ sudo apt-get update
+ sudo apt-get install git cmake ninja-build clang gcc-multilib
+
+2. Clone and Configure
+======================
+
+The following command clones the complete LLVM project and configures the
+build for LLVM-libc. We include ``compiler-rt`` to enable the Scudo memory
+allocator.
-Install dependencies first:
+.. code-block:: sh
+
+ git clone --depth=1 https://github.com/llvm/llvm-project.git
+ cd llvm-project
+ cmake -G Ninja -S runtimes -B build \
+ -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
+ -DLLVM_LIBC_FULL_BUILD=ON \
+ -DCMAKE_BUILD_TYPE=Debug \
+ -DCMAKE_C_COMPILER=clang \
+ -DCMAKE_CXX_COMPILER=clang++ \
+ -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 \
+ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+
+3. Build and Test
+=================
+
+After configuring, you can build the library, the math library (libm), and
+run all unit tests:
.. code-block:: sh
- $ sudo apt update
- $ sudo apt install git cmake ninja-build clang gcc-multilib
+ ninja -C build libc libm check-libc
+
+To run a specific test, such as ``isalpha`` in ``ctype.h``:
.. code-block:: sh
- $ git clone --depth=1 git at github.com:llvm/llvm-project.git /tmp/llvm-project
- $ mkdir /tmp/llvm-project/build
- $ cd /tmp/llvm-project/build
- $ cmake ../runtimes -GNinja \
- -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
- -DCMAKE_BUILD_TYPE=Debug \
- -DCMAKE_CXX_COMPILER=clang++ \
- -DCMAKE_C_COMPILER=clang \
- -DLLVM_LIBC_FULL_BUILD=ON \
- -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
- $ ninja libc libm
+ ninja -C build libc.test.src.ctype.isalpha_test.__unit__
-This will produce the following artifacts:
+4. Verify with Hello World
+==========================
-.. code-block::
+To verify your build, create a simple ``hello.c`` file:
- llvm-project/build/libc/lib/libc.a
- llvm-project/build/libc/lib/libm.a
- llvm-project/build/libc/startup/linux/crt1.o
- llvm-project/build/libc/include/**.h
+.. code-block:: c
-We can then compile and run hello world via:
+ #include <stdio.h>
+
+ int main() {
+ printf("Hello world from LLVM-libc!\n");
+ return 0;
+ }
+
+Compile it using the build artifacts:
+
+.. code-block:: sh
-.. code-block:: c++
+ clang -nostdinc -nostdlib hello.c -o hello \
+ -I build/libc/include \
+ -I $(clang -print-resource-dir)/include \
+ build/libc/startup/linux/crt1.o \
+ build/libc/lib/libc.a \
+ build/libc/lib/libm.a
- // hello.c
- #include <stdio.h>
- int main () { puts("hello world"); }
+Finally, run the executable:
.. code-block:: sh
- $ clang -nostdinc -nostdlib hello.c -I libc/include \
- -I $(clang -print-resource-dir)/include libc/startup/linux/crt1.o \
- libc/lib/libc.a
- $ ./a.out
- hello world
+ ./hello
+ # Output: Hello world from LLVM-libc!
-This was what we call a "full build" of llvm-libc. From here, you can visit
-:ref:`full_host_build` for more info, :ref:`full_cross_build` for cross
-compiling, :ref:`overlay_mode` for mixing llvm-libc with another libc,
-:ref:`libc_gpu` for targeting GPUs, or :ref:`libc_uefi` for targeting UEFI.
+This setup builds LLVM-libc as a standalone library using the
+recommended set of flags. From here, you can visit :ref:`full_host_build`
+for advanced sysroot setup, :ref:`overlay_mode` to learn about using
+LLVM-libc to augment your system's C library, or :ref:`build_concepts`
+to understand other build scenarios.
More information about the libc-commits
mailing list