Architecture

This page sketches the high-level architecture of the rust-lang/rust repository — both the layout of the source tree and the data flow inside the rustc compiler. Detailed per-crate documentation lives under Compiler, and per-library coverage lives under Library.

Top-level layout

graph TD
    Root[rust-lang/rust]
    Root --> Compiler[compiler/]
    Root --> Library[library/]
    Root --> Src[src/]
    Root --> Tests[tests/]

    Compiler --> RustcCrates["~70 rustc_* crates<br/>(driver, parser, HIR, MIR, type checker,<br/>borrow checker, codegen backends)"]

    Library --> Std["std, core, alloc<br/>proc_macro, test"]
    Library --> Runtime["panic_unwind, panic_abort,<br/>compiler-builtins, profiler_builtins"]
    Library --> Vendored["stdarch, portable-simd,<br/>backtrace (subtrees)"]

    Src --> Bootstrap["bootstrap/<br/>(x.py build system)"]
    Src --> Tools["tools/<br/>(rustdoc, miri, clippy,<br/>rustfmt, rust-analyzer, tidy)"]
    Src --> Doc["doc/<br/>(reference, nomicon,<br/>rustc-dev-guide, books)"]
    Src --> Ci["ci/<br/>(Docker images, scripts,<br/>citool)"]
    Src --> Librustdoc["librustdoc/<br/>(rustdoc internals)"]

    Tests --> CompiletestSuites["compiletest suites:<br/>ui, codegen-llvm, mir-opt,<br/>incremental, run-make, …"]

The four top-level directories map to four conceptual layers:

• compiler/ — what rustc is
• library/ — what rustc ships
• src/ — what builds, tests, and documents the rest
• tests/ — how everything is verified

Build orchestration is the bootstrap binary in src/bootstrap/, fronted by x.py (and the x / x.ps1 shims). Bootstrap downloads a "stage 0" compiler, builds itself with it, then drives Cargo to compile rustc, std, and tools across multiple stages — see Bootstrap.

The compiler pipeline

rustc is structured as a long pipeline that lowers source code through progressively more typed and more lowered intermediate representations. The query system (in rustc_query_system + rustc_query_impl) memoizes computations across these stages and is the backbone of incremental compilation.

graph LR
    Source[".rs source"] --> Lexer["rustc_lexer<br/>tokens"]
    Lexer --> Parser["rustc_parse<br/>AST"]
    Parser --> Expand["rustc_expand<br/>+ rustc_builtin_macros"]
    Expand --> Resolve["rustc_resolve<br/>name resolution"]
    Resolve --> Lower["rustc_ast_lowering<br/>AST → HIR"]
    Lower --> HIR[("HIR<br/>rustc_hir")]
    HIR --> TypeCheck["rustc_hir_analysis<br/>rustc_hir_typeck<br/>type checking"]
    TypeCheck --> ThirBuild["rustc_mir_build<br/>HIR → THIR → MIR"]
    ThirBuild --> MIR[("MIR<br/>rustc_middle::mir")]
    MIR --> Borrowck["rustc_borrowck<br/>borrow checking"]
    MIR --> Const["rustc_const_eval<br/>CTFE"]
    Borrowck --> MirTransform["rustc_mir_transform<br/>MIR → optimized MIR"]
    MirTransform --> Mono["rustc_monomorphize<br/>generic instantiation"]
    Mono --> Codegen["rustc_codegen_*<br/>(llvm | gcc | cranelift)"]
    Codegen --> Linker[Linker]
    Linker --> Binary[Object / library]

Cross-cutting concerns:

• rustc_middle — the central data structures (TyCtxt, Ty, Const, Body, …) used by every later stage
• rustc_query_system / rustc_query_impl — the demand-driven query engine that drives the pipeline lazily and caches results between runs
• rustc_errors / rustc_error_messages / rustc_error_codes — diagnostics infrastructure (with Diag, Subdiagnostic, Fluent message catalogs)
• rustc_session + rustc_interface — driver-level configuration, command-line parsing, and the orchestration of phases
• rustc_metadata — reads and writes .rmeta / .rlib crate metadata across compilation units
• rustc_incremental — saves and loads the on-disk incremental compilation cache

Standard library layering

The standard library is itself layered: core is freestanding (no allocator, no OS), alloc adds heap-allocated types (Box, Vec, String), and std adds OS-level facilities (std::fs, std::net, std::thread, std::sync).

graph BT
    Compiler["compiler-builtins<br/>(intrinsics, soft-float)"] --> Core
    Core["core (no_std primitives)"] --> Alloc
    Alloc["alloc (Box, Vec, String, …)"] --> Std
    PanicUnwind["panic_unwind / panic_abort"] --> Std
    Stdarch["stdarch (SIMD intrinsics)"] --> Core
    Std["std (OS, threads, I/O, sync)"]
    ProcMacro["proc_macro"] --> Std
    TestCrate["test (built-in test harness)"] --> Std

See Library packages for per-crate detail.

Bootstrap stages

Building Rust requires a Rust compiler, so rustc is bootstrapped through stages:

graph LR
    Stage0["Stage 0<br/>(downloaded beta compiler)"] -->|builds| Stage1Std["Stage 1 std"]
    Stage0 -->|builds| Stage1["Stage 1 rustc"]
    Stage1 -->|builds| Stage2Std["Stage 2 std"]
    Stage1 -->|builds| Stage2["Stage 2 rustc<br/>(shipped)"]

x.py build --stage N selects how far through this chain to go. Most contributors work at --stage 1 (fastest feedback); the final shipped artifacts come from stage 2. See Bootstrap for the full state machine.

CI and release pipeline

CI runs in GitHub Actions (.github/workflows/ci.yml) but the heavy lifting happens in custom Docker images under src/ci/docker/ driven by src/ci/run.sh and the citool Rust binary in src/ci/citool/. Merges go through the bors-like merge queue (rust-bors, configured in rust-bors.toml); only PRs that pass the full try/perf/CI matrix get merged to main. See Deployment for the release-train cadence (nightly → beta → stable, every 6 weeks).

Testing strategy

Almost all language and compiler behavior is verified via the compiletest test runner over the tests/ directory. Suites cover everything from UI diagnostics (tests/ui/) and codegen output (tests/codegen-llvm/, tests/assembly-llvm/) to MIR optimizations (tests/mir-opt/), incremental compilation (tests/incremental/), debugger integration (tests/debuginfo/), run-make style end-to-end builds, and rustdoc HTML/JSON (tests/rustdoc-html/, tests/rustdoc-json/). See Testing.