LLVM Project Administrator & Architecture Guide

This guide is the deep reference for the people who build, package, integrate, and extend the LLVM Project: distribution maintainers, toolchain engineers, release managers, CI operators, and contributors. Where the User Guide shows how to use the tools, this guide explains how the monorepo is architected, how to configure and produce a toolchain from it, and how its internals fit together.

It is written against the source tree at commit 53cbf88b6. Every build fact is grounded in llvm/CMakeLists.txt and the repository layout.

Table of Contents

1. Executive Summary
2. Architecture Overview
3. Repository Structure
4. System Requirements
5. Build Configuration Mastery
6. Producing & Distributing a Toolchain
7. Operations: Testing, CI, and Releases
8. Security Analysis
9. Internals & Module Reference
10. Code Patterns & Conventions
11. Testing Strategy
12. Potential Improvements & Technical Debt
13. Contributing
14. Quick Reference

1. Executive Summary

The LLVM Project is a monorepo that produces a complete, modular compiler toolchain. It is one of the largest open-source codebases in existence — this checkout contains 176,510 files. Its defining architectural idea is a target-independent intermediate representation (LLVM IR) that decouples language frontends from optimizations and from machine-specific backends, so each layer can be reused independently.

What an administrator needs to know up front:

• There is no server to deploy. "Operating" LLVM means building it, testing it, packaging it, and shipping a toolchain to users. Your "configuration surface" is CMake.
• The repo is split into projects (built by the host compiler via LLVM_ENABLE_PROJECTS) and runtimes (built by the freshly-built compiler via LLVM_ENABLE_RUNTIMES). This split is the single most important concept for building correctly.
• Builds are resource-intensive: a full debug build needs tens of GB of RAM for linking and 100+ GB of disk. Production packaging almost always uses multi-stage (bootstrap) Release builds.
• The codebase is C++17 and uses CMake ≥ 3.20.0, Ninja, TableGen, and lit/FileCheck for tests.

2. Architecture Overview

The three-phase compiler model

LLVM's architecture is the classic frontend → optimizer → backend pipeline, made reusable by a shared IR in the middle.

 ┌───────────────────────────────────────────────────────────────────────┐
 │                         THE LLVM PROJECT                                 │
 │                                                                         │
 │  FRONTENDS              MIDDLE-END                 BACKENDS              │
 │  ┌──────────┐           ┌──────────────┐          ┌──────────────────┐  │
 │  │  Clang   │──┐        │              │          │ 20 target codegen│  │
 │  │ (C/C++/  │  │        │   LLVM IR    │          │ AArch64, X86,    │  │
 │  │  ObjC)   │  ├──IR──▶ │  + Pass      │──IR──────▶│ RISCV, ARM, ...  │  │
 │  ├──────────┤  │        │  Manager     │          │                  │  │
 │  │  Flang   │──┤        │  (opt)       │          │   → .o / .s      │  │
 │  │ (Fortran)│  │        │              │          └──────────────────┘  │
 │  ├──────────┤  │        │  + Polly     │                   │            │
 │  │  MLIR    │──┘        │  (polyhedral)│                   ▼            │
 │  │ frontends│           └──────────────┘            ┌──────────────┐   │
 │  └──────────┘                                        │     LLD      │   │
 │                                                      │  (linker)    │   │
 │                                                      └──────┬───────┘   │
 │                                                             ▼           │
 │  RUNTIMES linked into the final program:             executable /      │
 │  libc++, libc++abi, libunwind, compiler-rt,          shared library    │
 │  OpenMP, libc, ...                                                      │
 │                                                                         │
 │  DIAGNOSTICS / DEBUG:  LLDB (debugger), sanitizers (compiler-rt)        │
 └───────────────────────────────────────────────────────────────────────┘

The key consequence: a new language only needs a frontend that emits LLVM IR to inherit all optimizations and all 20 backends. A new CPU only needs a backend to be reachable from every frontend.

MLIR — the second IR

MLIR (Multi-Level Intermediate Representation) generalizes the idea of an IR. Where LLVM IR is a single, relatively low-level representation, MLIR is a framework for defining many coexisting IRs ("dialects") at different abstraction levels, with infrastructure to progressively lower between them — frequently ending at the LLVM IR dialect, which then feeds LLVM Core. MLIR is the foundation for modern ML compilers, Flang's lowering, and domain-specific compilers.

Library-first design

Every capability is exposed as a library first and a tool second. clang the binary is a thin driver over libraries like clangFrontend, clangSema, clangCodeGen; opt is a thin driver over the LLVM pass libraries. This is why the ecosystem (clang-tidy, clangd, IDE integrations, custom compilers) can be built without forking — they link the same libraries.

TableGen — the metacompiler

Large amounts of LLVM (instruction definitions, register files, intrinsics, clang diagnostics and driver options, attributes) are described declaratively in .td files and compiled by TableGen into C++ at build time. This is why TableGen build performance matters (LLVM_OPTIMIZED_TABLEGEN) and why the actual command-line option sets of clang/llc/opt live in TableGen and cl::opt definitions rather than in plain argument-parsing code.

Note

Because options are defined via TableGen/cl::opt, the authoritative, version-accurate flag list for each tool is obtained from the tool itself (<tool> --help) and from the generated docs at llvm.org/docs — not from a single hand-maintained file.

3. Repository Structure

Top-level directories correspond to the projects and runtimes:

Important

The CMake entry point is llvm/CMakeLists.txt, not the repo root. All cmake -S invocations target the llvm subdirectory; other components are pulled in through LLVM_ENABLE_PROJECTS / LLVM_ENABLE_RUNTIMES.

Notable subtrees within llvm/

4. System Requirements

Caution

The most common build failure on constrained machines is the linker running out of memory, not compilation. Plan link parallelism (LLVM_PARALLEL_LINK_JOBS) against available RAM, and prefer lld for linking LLVM itself.

5. Build Configuration Mastery

CMake is the configuration interface for LLVM. This section is the complete, grounded reference for the options that matter most to packagers and integrators.

Component selection

Known projects ("all" = bolt;clang;clang-tools-extra;cross-project-tests;lld;lldb;mlir;polly), plus extra projects flang, libc, compiler-rt.

Runtimes:

• Default set: libcxx;libcxxabi;libunwind;libclc;compiler-rt;openmp
• Supported set: libc;libunwind;libcxxabi;libcxx;compiler-rt;openmp;llvm-libgcc;offload;flang-rt;libclc;libsycl;orc-rt

Warning

Three guardrails are enforced at configure time:

1. openmp as a project is removed — use it as a runtime (fatal error otherwise).
2. An unknown name in LLVM_ENABLE_PROJECTS aborts with "isn't a known project".
3. An unsupported runtime aborts with "is not a supported runtime". Building flang as a project additionally requires mlir.

Targets

Stable (LLVM_ALL_TARGETS): AArch64, AMDGPU, ARM, AVR, BPF, Hexagon, Lanai, LoongArch, Mips, MSP430, NVPTX, PowerPC, RISCV, Sparc, SPIRV, SystemZ, VE, WebAssembly, X86, XCore.

Experimental (LLVM_ALL_EXPERIMENTAL_TARGETS): ARC, CSKY, DirectX, M68k, Xtensa.

JIT-capable (LLVM_TARGETS_WITH_JIT): X86, PowerPC, AArch64, ARM, Mips, SystemZ.

Build-type and correctness options

Performance and packaging options

Tip

For redistribution, prefer static component libraries (BUILD_SHARED_LIBS=OFF) and optionally a single aggregate libLLVM via LLVM_BUILD_LLVM_DYLIB=ON + LLVM_LINK_LLVM_DYLIB=ON to shrink tool binaries. BUILD_SHARED_LIBS=ON is a developer-iteration convenience, not a packaging mode.

Reference build recipes

Minimal C/C++ compiler (fast)

cmake -S llvm -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_PROJECTS="clang" \
  -DLLVM_TARGETS_TO_BUILD="host" \
  -DCMAKE_INSTALL_PREFIX=/opt/llvm
ninja -C build install

Full self-hosting toolchain

cmake -S llvm -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_PROJECTS="clang;lld;clang-tools-extra" \
  -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind;compiler-rt" \
  -DLLVM_TARGETS_TO_BUILD="all" \
  -DLLVM_ENABLE_LLD=ON \
  -DCMAKE_INSTALL_PREFIX=/opt/llvm
ninja -C build install

LLVM developer config

cmake -S llvm -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DLLVM_ENABLE_PROJECTS="clang;lld" \
  -DLLVM_TARGETS_TO_BUILD="host" \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DLLVM_OPTIMIZED_TABLEGEN=ON \
  -DLLVM_CCACHE_BUILD=ON \
  -DLLVM_USE_LINKER=lld \
  -DLLVM_PARALLEL_LINK_JOBS=2

6. Producing & Distributing a Toolchain

Multi-stage (bootstrap) builds

Production toolchains are usually built in stages: a stage-1 compiler builds a stage-2 compiler (and often a stage-3 for verification). This produces a toolchain that compiles itself identically and benefits from Clang/LTO/PGO.

 host compiler ──▶ stage-1 clang ──▶ stage-2 clang ──▶ (stage-3 verify)
   (GCC/MSVC)        (Release)         (LTO/PGO)         (bit-identical)

Tip

The repository ships a PGO bootstrap helper at llvm/utils/collect_and_build_with_pgo.py. It runs an instrumented stage, collects profiles, and produces a final PGO-optimized build. Key flags: --llvm-dir, --out-dir, --cmake-extra-arg, --no-optimized-build, --use-make, --dry-run.

Installation layout

ninja install (or cmake --install build) populates CMAKE_INSTALL_PREFIX with the standard bin/, lib/, include/, and share/ layout. llvm-config in bin/ is how downstream consumers discover include/library/flag paths.

cmake --install build --prefix /opt/llvm
/opt/llvm/bin/llvm-config --version
/opt/llvm/bin/llvm-config --includedir --libdir

Packaging guidance

• Build Release with assertions off for shipped toolchains; keep an assertions-on build for internal triage.
• Use LLVM_TARGETS_TO_BUILD="all" only if your users cross-compile; otherwise ship host plus any targets you support to keep size down.
• Strip or split debug info for the binaries you ship; the unstripped artifacts are enormous.
• The Bazel build overlay lives under utils/bazel/ for organizations that build LLVM with Bazel instead of CMake.

Note

The project also publishes official prebuilt binaries per release on GitHub. Most end users should consume those rather than building; build-from-source is for distributors, integrators, and developers.

7. Operations: Testing, CI, and Releases

Running the test suites

Each project exposes a check-<project> Ninja target that runs its lit suite.

ninja -C build check-llvm       # LLVM Core regression tests
ninja -C build check-clang      # Clang tests
ninja -C build check-lld        # LLD tests
ninja -C build check-mlir       # MLIR tests
ninja -C build check-all        # Everything that is enabled

The lit + FileCheck model

LLVM's regression tests are lit test files containing RUN: lines that invoke tools and pipe output into FileCheck, which verifies the output against CHECK: patterns embedded in the same file. This is the dominant test style across llvm/test/, clang/test/, etc.

; RUN: opt -passes=instcombine -S < %s | FileCheck %s
; CHECK: ret i32 42

Tip

Regenerate the CHECK lines of codegen/IR tests with the llvm/utils/update_*_test_checks.py family (e.g. update_test_checks.py, update_llc_test_checks.py, update_cc_test_checks.py). Never hand-edit large auto-generated check blocks — re-run the updater.

Unit tests

In addition to lit tests, components ship GoogleTest unit tests under */unittests/. They are built when LLVM_BUILD_TESTS=ON and run via the same check-* targets.

Continuous integration & developer hygiene

The repo carries CI configuration and a set of maintenance scripts under llvm/utils/ and per-project ci/ folders, including:

Release process

LLVM follows a time-based major-release cadence with release branches cut from main, stabilized through release candidates, and shipped with prebuilt binaries. LLVM_APPEND_VC_REV=ON embeds the source revision into version strings so a binary can be traced back to a commit.

8. Security Analysis

LLVM is a compiler toolchain, so its security posture is different from a networked service. The relevant concerns are supply-chain integrity, the trust boundary of compiling untrusted input, and the security tooling LLVM itself provides.

Trust model

Security features LLVM provides to its users

• Sanitizers (compiler-rt): AddressSanitizer, ThreadSanitizer, MemorySanitizer, UndefinedBehaviorSanitizer — runtime detectors enabled via -fsanitize=.
• Hardening flags in Clang (stack protectors, CFI, fortify) for producing hardened binaries.
• Clang Static Analyzer (clang/lib/StaticAnalyzer/, driven by scan-build) for path-sensitive bug finding at build time.
• clang-tidy bugprone-*, cert-*, and security-oriented checks.

Important

Do not execute lli (the IR interpreter/JIT) on untrusted .ll/.bc files — it runs the code. Likewise, the *-fuzzer tools and fuzzing engines build and execute generated inputs and must run only in sandboxed environments.

Caution

The fatal-error guardrails in the CMake configure step (unknown project/runtime, removed openmp project mode) are correctness checks, not security boundaries. Never feed attacker-controlled values into your CMake invocation.

9. Internals & Module Reference

This section summarizes the major components an integrator or contributor must understand. Depths reflect each component's role in the pipeline.

LLVM Core (llvm/)

The heart of the project. Important library areas under llvm/lib/:

Clang (clang/) & Clang Tools Extra (clang-tools-extra/)

• clang/lib/ — the frontend: lexer, parser, Sema (semantic analysis), CodeGen (IR emission), Driver (the command-line driver), Tooling/ (LibTooling, the basis for standalone tools), and StaticAnalyzer/.
• clang-tools-extra/ — clang-tidy (and its many check modules), clangd (the LSP server and its index), clang-doc, include-cleaner, clang-include-fixer, clang-move, clang-query, pp-trace.

LLD (lld/)

Per-format linker front-ends: ELF/, COFF/, MachO/, wasm/, with shared infrastructure in Common/ and MinGW support in MinGW/.

LLDB (lldb/)

A large debugger with a plugin-based architecture: source/Core/, source/Commands/ (the command interpreter), source/Plugins/ (process, platform, language, and trace plugins), source/API/ + include/lldb/API/ (the public SB* C++/Python API), and tools/lldb-dap/ (the Debug Adapter Protocol implementation for editors).

MLIR (mlir/)

Dialect-based IR framework: include/mlir/Dialect/* and lib/Dialect/* define dialects (Affine, Arith, Linalg, Vector, SCF, GPU, SPIR-V, Tosa, SparseTensor, Transform, …); lib/Transforms/ and the Transform dialect drive rewriting; CAPI/Python bindings expose MLIR to other languages.

Runtimes

compiler-rt/ (builtins, profile, sanitizers), libcxx/ + libcxxabi/ + libunwind/ (the C++ runtime stack), openmp/ and offload/ (parallel and accelerator runtimes), libc/ (C library), flang-rt/ (Fortran runtime), plus libclc/, libsycl/, orc-rt/, llvm-libgcc/.

Note

This checkout also contains some newer/incubating subtrees visible in the tool list (e.g. ClangIR cir-* tools and a scalable-static-analysis tree). Their APIs may be less stable than the mature components above; verify behavior against the source for your specific revision before depending on them.

10. Code Patterns & Conventions

Tip

When adding a clang-tidy check, use add_new_check.py to scaffold the check, tests, and documentation consistently rather than copying an existing check by hand.

11. Testing Strategy

Best practices for maintainers:

• Add a lit/FileCheck test for every functional change; LLVM is strict about test coverage in review.
• Use llvm-reduce to minimize reproducers attached to bug reports.
• For no-functional-change (NFC) refactors in BOLT, use the NFC check tooling (bolt/utils/nfc-check-setup.py).

Warning

Auto-generated CHECK blocks must be regenerated with the matching update_*_test_checks.py script, not edited by hand. Hand edits drift from the tool output and fail review.

12. Potential Improvements & Technical Debt

These are observations about consuming and operating the toolchain, framed for administrators and integrators. They are not defects in LLVM.

• Build resource ceiling. The default LLVM_TARGETS_TO_BUILD="all" plus a Debug build is a frequent cause of OOM/disk-exhaustion on CI runners. Standardize on host targets + Release/RelWithDebInfo and explicit LLVM_PARALLEL_LINK_JOBS in shared CI to avoid flaky, resource-driven failures.
• Project-vs-runtime confusion. The most common misconfiguration is putting compiler-rt/libc/openmp in LLVM_ENABLE_PROJECTS. Encode the correct split in your build scripts and lint for it.
• Per-tool flag drift across releases. Because options are TableGen/cl::opt generated, pin the LLVM version your downstream scripts target and validate flags against --help in CI rather than assuming stability across majors.
• Incubating subtrees. Newer trees (ClangIR cir-*, scalable static analysis) appear in the tool set; if you ship them, document their stability caveats to your users explicitly.
• Known upstream issue to watch: LLDB issue #206508 — a misleading error message when re-importing a command script. Cosmetic but user-facing; track for the fix.

13. Contributing

Tip

New backend or pass work should start from the existing Target/ and Transforms/ patterns and TableGen definitions — the codebase is highly pattern-consistent, and matching existing structure speeds up review.

14. Quick Reference

Configure entry point

cmake -S llvm -B build -G Ninja [options]   # NOTE: -S llvm, not the repo root
ninja -C build [target]
ninja -C build install

Component lists

• Projects (all): bolt, clang, clang-tools-extra, cross-project-tests, lld, lldb, mlir, polly (+ flang, libc, compiler-rt)
• Runtimes (default): libcxx, libcxxabi, libunwind, libclc, compiler-rt, openmp
• Runtimes (supported): libc, libunwind, libcxxabi, libcxx, compiler-rt, openmp, llvm-libgcc, offload, flang-rt, libclc, libsycl, orc-rt

Targets

• Stable: AArch64, AMDGPU, ARM, AVR, BPF, Hexagon, Lanai, LoongArch, Mips, MSP430, NVPTX, PowerPC, RISCV, Sparc, SPIRV, SystemZ, VE, WebAssembly, X86, XCore
• Experimental: ARC, CSKY, DirectX, M68k, Xtensa
• JIT: X86, PowerPC, AArch64, ARM, Mips, SystemZ

Most-used CMake options

Test targets

ninja -C build check-llvm      # core
ninja -C build check-clang     # clang
ninja -C build check-all       # everything enabled

Documentation