The Rust Compiler (rustc) — Administrator & Developer Guide

1. Architecture Overview

The rust-lang/rust monorepo (57,526 files, ~66 million characters of source at commit b2f1ccf5) produces the Rust compiler (rustc), the standard library (core, alloc, std, proc_macro, test), and the complete development toolchain. It is a self-hosted compiler: the Rust compiler is written in Rust and compiles itself through a multi-stage bootstrap process.

The compiler transforms Rust source code through a pipeline of intermediate representations — from the token stream through AST, HIR, THIR, and MIR, then lowers to machine code via LLVM (primary), Cranelift (experimental, faster debug builds), or GCC (experimental, broader platform reach). The standard library is compiled as part of the build and distributed alongside the compiler as part of the "sysroot."

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                         x.py / bootstrap                            │
│  (Python + Rust build orchestrator, multi-stage management)         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────── compiler/ ────────────────────────────────┐ │
│  │                                                                │ │
│  │  Source → rustc_lexer → rustc_parse → rustc_ast                │ │
│  │            (tokenize)    (parse)      (AST)                    │ │
│  │                                                                │ │
│  │  → rustc_ast_lowering → rustc_hir → rustc_hir_analysis        │ │
│  │    (AST→HIR)            (HIR)       (type checking)           │ │
│  │                                                                │ │
│  │  → rustc_hir_typeck → rustc_borrowck → rustc_mir_build        │ │
│  │    (type inference)   (borrow check)   (HIR→MIR)              │ │
│  │                                                                │ │
│  │  → rustc_mir_transform → rustc_codegen_ssa                    │ │
│  │    (MIR optimizations)   (codegen interface)                  │ │
│  │                                                                │ │
│  │  → rustc_codegen_llvm ──→ LLVM ──→ Object files ──→ Linker   │ │
│  │    rustc_codegen_cranelift (alt)                               │ │
│  │    rustc_codegen_gcc      (alt)                               │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌───────────── library/ ──────────┐  ┌──── src/tools/ ──────────┐ │
│  │ core (no_std foundation)        │  │ clippy (linter)          │ │
│  │ alloc (heap allocation)         │  │ rustfmt (formatter)      │ │
│  │ std (full OS integration)       │  │ miri (MIR interpreter)   │ │
│  │ proc_macro (procedural macros)  │  │ rust-analyzer (IDE)      │ │
│  │ test (test framework)           │  │ rustdoc (via librustdoc) │ │
│  │ compiler-builtins (intrinsics)  │  │ compiletest (test runner)│ │
│  │ stdarch (SIMD intrinsics)       │  │ tidy (style checker)     │ │
│  │ backtrace (stack traces)        │  │ opt-dist (PGO builds)    │ │
│  │ portable-simd (SIMD types)      │  │ rust-installer (pkging)  │ │
│  └─────────────────────────────────┘  └──────────────────────────┘ │
│                                                                     │
│  ┌──────────── tests/ ─────────────────────────────────────────┐   │
│  │ ui/ (diagnostics) │ mir-opt/ │ codegen-llvm/ │ run-make/    │   │
│  │ rustdoc-js/       │ rustdoc-gui/ │ ui-fulldeps/ │ assembly/ │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

Component Inventory

Technology Stack

Compilation Pipeline Data Flow

Source (.rs)
  │
  ▼
Lexer (rustc_lexer) ──→ Token stream
  │
  ▼
Parser (rustc_parse) ──→ AST (rustc_ast)
  │
  ▼
Macro expansion (rustc_expand + rustc_builtin_macros)
  │
  ▼
AST validation (rustc_ast_passes)
  │
  ▼
AST lowering (rustc_ast_lowering) ──→ HIR (rustc_hir)
  │
  ▼
Name resolution (rustc_resolve)
  │
  ├──→ Type checking (rustc_hir_typeck + rustc_hir_analysis)
  │      │
  │      ▼
  │    Trait solving (rustc_traits)
  │
  ▼
MIR construction (rustc_mir_build) ──→ MIR (in rustc_middle)
  │
  ▼
Borrow checking (rustc_borrowck)
  │
  ▼
MIR optimization (rustc_mir_transform)
  │
  ▼
Monomorphization (rustc_monomorphize)
  │
  ▼
Code generation (rustc_codegen_ssa → rustc_codegen_llvm)
  │
  ▼
LLVM optimization passes → Object file (.o)
  │
  ▼
Linker → Executable / Library

Note

The query system (rustc_query_impl / rustc_middle) underpins the entire pipeline. Rather than a linear pass sequence, the compiler is demand-driven: each compilation stage is a query that lazily computes and caches its result. This enables incremental compilation — on subsequent builds, only invalidated queries are recomputed.

2. System Requirements

Build Host Requirements

Runtime Dependencies

The built compiler has minimal runtime dependencies:

3. Configuration Reference

bootstrap.toml Sections

The bootstrap.toml file (generated by ./x setup or copied from bootstrap.example.toml) is the central build configuration. Below are the key sections and options derived from source.

[build] — General Build Settings

[llvm] — LLVM Configuration

[rust] — Compiler Configuration

[target.<triple>] — Per-Target Configuration

Environment Variables — Complete Reference

Compiler Runtime Variables

Thread Pool Variables

Test Framework Variables

Clippy Variables

Miri Variables

rust-analyzer Variables

Cranelift Backend Variables

GCC Backend Variables

Build System / CI Variables

Standard Library Build Variables

Important

Variables prefixed with CG_GCCJIT_* and CG_CLIF_* only affect their respective codegen backends and are ignored when using the default LLVM backend.

Standard Library stdarch Test Variables

4. Deployment & Scaling

Multi-Stage Bootstrap

The compiler builds itself through three stages:

The bootstrap process is managed by src/bootstrap/ (excluded from the Cargo workspace — it builds independently) and orchestrated by x.py.

Distribution Builds

./x setup dist
./x dist

This produces platform-specific tarballs in build/dist/ containing:

• The compiler (rustc)
• Standard library
• Cargo (external, fetched)
• Clippy, rustfmt, and other extended tools
• Offline documentation
• Source distribution

The src/tools/build-manifest/ (4 files, 37K chars) generates the manifest files that rustup uses to discover available components. The src/tools/rust-installer/ (8 files, 35K chars) handles tarball creation and install scripts.

Cross-Compilation

To build the standard library for additional targets:

# bootstrap.toml
[build]
target = ["x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu", "wasm32-unknown-unknown"]

[target.aarch64-unknown-linux-gnu]
cc = "aarch64-linux-gnu-gcc"
cxx = "aarch64-linux-gnu-g++"
linker = "aarch64-linux-gnu-gcc"

Note

Cross-compilation for embedded targets (e.g., thumbv6m-none-eabi, wasm32-unknown-unknown) only builds core and alloc (no std). The standard library conditionally compiles OS-specific code based on cfg(target_os), cfg(target_arch), and related configuration values controlled by compiler/rustc_session/src/config/cfg.rs.

Profile-Guided Optimization (PGO)

The src/tools/opt-dist/ tool automates PGO builds for the compiler:

# Set up PGO build
DIST_TRY_BUILD=1 ./x dist

5. Operations

Build System Commands

Tip

For CI workflows, the src/ci/citool/ (9 files, 67K chars) provides job orchestration, metric collection, and test scheduling. It reads workflow definitions and routes jobs to appropriate runners.

Monitoring Compiler Internals

Tip

The -Z self-profile flag produces a trace file that can be analyzed with summarize and crox tools to visualize which queries take the most time. This is the primary tool for compiler performance work.

Incremental Compilation

Incremental compilation is managed by compiler/rustc_incremental/ and the query system. Key files:

• compiler/rustc_incremental/src/assert_dep_graph.rs — dependency graph assertions
• compiler/rustc_incremental/src/persist/ — cache serialization

Enable with:

[rust]
incremental = true

On subsequent builds, the compiler loads the dependency graph, invalidates changed queries, and only recomputes affected results.

6. Performance

Build Performance Optimization

Compiler Runtime Performance

The compiler uses several techniques for runtime performance:

• Parallel frontend: The rustc_thread_pool (a fork of Rayon with deadlock detection) parallelizes type checking and other frontend passes. Thread count is controlled by RAYON_NUM_THREADS.
• Query caching: Every intermediate result is cached as a query. The rustc_middle crate manages TyCtxt, the central context that holds all cached state.
• Arena allocation: compiler/rustc_arena/ provides typed arena allocators to reduce allocation overhead.
• Jemalloc: The compiler binary uses tikv-jemalloc-sys for memory allocation when built for distribution, providing better allocation performance than the system allocator.

7. Security

Compiler Integrity

The Rust compiler is built from a trusted bootstrap chain:

1. Stage 0 is downloaded from Rust infrastructure with verified checksums
2. Each subsequent stage is built by the previous stage
3. CI enforces reproducible builds and tests on every commit

Security-Relevant Configuration

Warning

The RUSTC_BOOTSTRAP variable should only be set by the build system itself. External use bypasses the stability guarantee that is the primary safety contract of the Rust release channels.

Built-in Cfg Protections

The compiler (compiler/rustc_session/src/config/cfg.rs) enforces that certain --cfg values cannot be set by the user via the command line because they would create incoherent behavior:

Attempting to set these via --cfg emits the EXPLICIT_BUILTIN_CFGS_IN_FLAGS lint.

Caution

Sanitizer flags (-Z sanitizer=address,cfi,memory,thread,hwaddress,kcfi) fundamentally change code generation. KASAN maps to ADDRESS and KHWASAN maps to HWADDRESS internally. Mixing sanitizer-instrumented and uninstrumented code in the same binary causes undefined behavior.

Memory Safety in the Compiler Itself

The compiler is written in Rust and benefits from its own safety guarantees. The few unsafe blocks are concentrated in:

• compiler/rustc_data_structures/ (concurrent data structures, vec_cache, steal)
• compiler/rustc_arena/ (arena allocation with smallvec may_dangle)
• compiler/rustc_codegen_llvm/ (FFI to LLVM C++ API)

8. Developer Internals

Repository Structure

rust-lang/rust/
├── compiler/                  # ~50 crates comprising the compiler
│   ├── rustc/                 # Entry point binary (main.rs → rustc_driver)
│   ├── rustc_driver_impl/     # CLI, session setup, compilation orchestration
│   ├── rustc_lexer/           # Tokenizer (no dependencies on rest of compiler)
│   ├── rustc_parse/           # Parser
│   ├── rustc_ast/             # AST data structures
│   ├── rustc_ast_lowering/    # AST → HIR
│   ├── rustc_hir/             # HIR data structures
│   ├── rustc_hir_analysis/    # Trait resolution, coherence
│   ├── rustc_hir_typeck/      # Type inference (27 files, 1.1M chars)
│   ├── rustc_borrowck/        # Borrow checker (17 files, 321K chars)
│   ├── rustc_resolve/         # Name resolution (12 files, 940K chars)
│   ├── rustc_middle/          # Central types: TyCtxt, MIR, query system
│   ├── rustc_mir_transform/   # MIR optimization passes (78 files, 1.2M chars)
│   ├── rustc_codegen_llvm/    # LLVM code generation (22 files, 601K chars)
│   ├── rustc_codegen_cranelift/  # Cranelift backend
│   ├── rustc_codegen_gcc/     # GCC/libgccjit backend
│   ├── rustc_codegen_ssa/     # Shared codegen traits
│   ├── rustc_lint/            # Built-in lints (53 files, 847K chars)
│   ├── rustc_session/         # Compiler options and session state
│   ├── rustc_type_ir/         # Type IR shared with chalk (30 files, 398K chars)
│   ├── rustc_feature/         # Feature gate definitions
│   ├── rustc_thread_pool/     # Rayon fork with deadlock detection
│   ├── rustc_data_structures/ # Shared data structures (32 files, 216K chars)
│   └── ...                    # ~30 more crates
├── library/                   # Standard library
│   ├── core/                  # #![no_std] foundation
│   ├── alloc/                 # Heap allocation (15 files, 707K chars)
│   ├── std/                   # Full standard library with OS integration
│   ├── proc_macro/            # Procedural macro support
│   ├── test/                  # Test framework (#[test])
│   ├── compiler-builtins/     # Compiler intrinsics (12 files, 62K chars)
│   ├── stdarch/               # Platform SIMD intrinsics
│   ├── portable-simd/         # Portable SIMD abstractions
│   └── backtrace/             # Stack trace generation
├── src/
│   ├── bootstrap/             # Build system (excluded from workspace)
│   ├── tools/                 # Development tools
│   │   ├── clippy/            # Linter (800+ lints)
│   │   ├── rustfmt/           # Code formatter
│   │   ├── miri/              # MIR interpreter
│   │   ├── rust-analyzer/     # IDE/LSP server
│   │   ├── compiletest/       # Test runner
│   │   ├── tidy/              # Style/hygiene enforcement
│   │   ├── opt-dist/          # PGO build orchestration
│   │   ├── rust-installer/    # Packaging/distribution
│   │   ├── build-manifest/    # Rustup manifest generation
│   │   └── ...                # ~30 more tools
│   ├── librustdoc/            # Rustdoc implementation
│   │   ├── html/              # HTML generation (13 files, 244K chars)
│   │   └── json/              # JSON output (4 files, 64K chars)
│   ├── ci/                    # CI tooling
│   │   └── citool/            # Job orchestration (9 files, 67K chars)
│   ├── build_helper/          # Build script utilities (8 files, 34K chars)
│   └── doc/                   # Documentation sources
│       ├── rustc-dev-guide/   # Compiler contributor guide
│       ├── rust-by-example/   # Examples
│       ├── embedded-book/     # Embedded Rust book
│       └── style-guide/       # Rust style guide
├── tests/                     # 50,000+ test files
│   ├── ui/                    # Compiler diagnostics
│   ├── mir-opt/               # MIR optimization (135 files, 237K chars)
│   ├── codegen-llvm/          # LLVM codegen (351 files, 553K chars)
│   ├── run-make/              # Integration tests
│   ├── run-make-cargo/        # Cargo-based integration
│   ├── rustdoc-js/            # Rustdoc search tests (152 files, 125K chars)
│   ├── rustdoc-gui/           # Rustdoc rendering tests
│   └── ui-fulldeps/           # Tests requiring full deps (20 files, 46K chars)
├── x.py                       # Build system entry point
├── x / x.ps1                  # Shell wrappers
├── Cargo.toml                 # Workspace manifest
├── bootstrap.example.toml     # Annotated configuration template
└── REUSE.toml                 # License annotations

Architecture Deep Dive

The Query System

The query system is the backbone of the compiler. Rather than executing compilation as a linear sequence of passes, each computational step is modeled as a query that takes inputs and produces cached outputs. Queries are:

• Demand-driven: computed lazily when their result is first needed
• Memoized: results are cached for the duration of the compilation
• Incremental: on re-compilation, only queries whose inputs changed are recomputed

The central query context is TyCtxt<'tcx> in compiler/rustc_middle/, which holds all compilation state and provides access to every query.

Thread Pool and Parallelism

The compiler uses a custom fork of Rayon (compiler/rustc_thread_pool/, 9 files, 108K chars) with additional deadlock detection. The sleep module implements a sophisticated protocol using atomic counters and sequentially consistent fences to coordinate worker threads:

• Active threads: executing a job
• Idle threads: searching for work (stealing from other queues)
• Sleeping threads: blocked on a condition variable

The Jobs Event Counter (JEC) uses an even/odd toggle protocol to detect when new work is available without expensive synchronization. Deadlock detection monitors active_threads and blocked_threads counts — a deadlock is flagged when active_threads == 0 && blocked_threads > 0.

Diagnostic System

Error messages use Fluent-based internationalization (compiler/rustc_error_messages/, 2 files, 19K chars). The compiler's error index contains 997 unique error patterns spanning:

• Pattern analysis errors (malformed ranges, unexpected constructors)
• MIR transformation errors (invalid phase transitions)
• Type checking errors (inference failures, trait resolution)
• Borrow checking errors (moved values, lifetime violations)
• Lint infrastructure errors (push/pop mismatches, renamed lints)

The driver (compiler/rustc_driver_impl/src/highlighter.rs) includes a syntax highlighter for rustc --explain output, coloring keywords, types, literals, and function calls.

Codegen Backends

All backends implement the traits defined in compiler/rustc_codegen_ssa/. The LLVM backend interfaces with LLVM through compiler/rustc_llvm/ (C++ FFI wrapper).

The entry point binary (compiler/rustc/src/main.rs) is minimal:

fn main() -> ExitCode {
    rustc_driver::main()
}

It uses jemalloc on supported platforms through the tikv-jemalloc-sys crate with override_allocator_on_supported_platforms, which replaces the system allocator's malloc/free at the libc level.

Module Reference

compiler/rustc_driver_impl/ — Compiler Driver

The driver (7 files, 100K chars) orchestrates the compilation pipeline:

• lib.rs — Entry point: CLI parsing, session creation, callback registration, --explain handler, ICE hook installation. Key types: TimePassesCallbacks, Compilation (enum: Continue/Stop), HandledOptions
• args.rs — Argument file expansion (@file syntax). Supports -Z shell-argfiles for shell-style quoting
• highlighter.rs — Syntax highlighting for --explain output. Recognizes Rust keywords, primitive types, string/char/number literals, function calls, and derive attributes
• pretty.rs — Pretty-printing passes (-Z unpretty=...)

compiler/rustc_session/ — Session Configuration

The session crate manages compiler options and the diagnostic context. The config/ subdirectory (5 files, 38K chars) includes:

• cfg.rs — --cfg and --check-cfg processing, built-in cfg protections, default configuration generation
• Key types: Cfg (set of name-value pairs), CheckCfg (exhaustive cfg validation), ExpectedValues
• Built-in cfgs: debug_assertions, overflow_checks, ub_checks, contract_checks, panic, proc_macro, target_*, sanitize, fmt_debug

compiler/rustc_hir_typeck/ — Type Inference

The largest compiler crate by source volume (27 files, 1.1M chars). Handles:

• Type inference with unification variables
• Method resolution
• Coercion and cast checking
• Closure typing
• Operator overloading resolution

compiler/rustc_borrowck/ — Borrow Checker

17 files, 321K chars. Implements Non-Lexical Lifetimes (NLL):

• Region inference
• Move/borrow analysis
• Lifetime error diagnostics

compiler/rustc_mir_transform/ — MIR Optimizations

The largest by file count (78 files, 1.2M chars). Individual optimization passes include:

• Inlining (inline.rs) — with ForceInline for #[inline(always)]
• Constant propagation
• Dead code elimination
• Copy propagation
• Promotion of constants to statics

compiler/rustc_resolve/ — Name Resolution

12 files, 940K chars. Resolves all names in the program:

• Import resolution (glob, named, re-exports)
• Macro name resolution
• Lifetime name resolution
• Privacy checking

compiler/rustc_lint/ — Lint Infrastructure

53 files, 847K chars. The compiler ships hundreds of built-in lints organized into:

• levels.rs — Lint level computation (allow, warn, deny, forbid)
• expect.rs — #[expect(lint)] tracking
• Individual lint passes (non_fmt_panic, lifetime_syntax, etc.)

The lint definitions themselves live in compiler/rustc_lint_defs/ (2 files, 233K chars).

compiler/rustc_data_structures/ — Shared Data Structures

32 files, 216K chars. Thread-safe data structures used across the compiler:

• steal.rs — Single-writer steal cells for inter-query data transfer
• sync.rs — Dynamic thread-safety mode selection
• vec_cache.rs — Bucket-indexed cache with atomic operations
• small_c_str.rs — Small C string optimization for FFI

compiler/rustc_thread_pool/ — Rayon Fork

9 files, 108K chars. A fork of the Rayon work-stealing thread pool with:

• Deadlock detection for user-code blocking
• Configurable via RAYON_NUM_THREADS and RAYON_RS_NUM_CPUS
• Atomic sleep/wake protocol using seq-cst fences
• Jobs Event Counter (JEC) for efficient new-work detection

compiler/rustc_pattern_analysis/ — Exhaustiveness Checking

9 files, 208K chars. Implements pattern exhaustiveness and usefulness analysis:

• constructor.rs — Pattern constructors (int ranges, slices, variants)
• usefulness.rs — Core exhaustiveness algorithm
• rustc.rs — Rust-specific pattern lowering

library/alloc/ — Allocation Library

15 files, 707K chars. Provides heap-allocated types for #![no_std] environments:

• Vec<T>, String, Box<T>, Rc<T>, Arc<T>
• B-tree maps and sets
• Binary heap
• Linked list

src/librustdoc/ — Rustdoc

Documentation generator with two output modes:

• html/ (13 files, 244K chars) — HTML generation with syntax highlighting, search index, and responsive CSS
• json/ (4 files, 64K chars) — Machine-readable JSON documentation format

Code Patterns and Conventions

Naming Conventions

Common Patterns

• Query definition: Queries are defined via macros in rustc_middle and implemented in the crate that owns the computation
• Arena allocation: Long-lived data is allocated in arenas tied to 'tcx, avoiding individual heap allocations
• Visitor pattern: Both AST and HIR use visitor traits (intravisit::Visitor) for tree traversal
• Diagnostic builder: Errors are constructed via struct_span_err! / span_bug! macros, allowing machine-readable structured diagnostics
• Feature gates: Unstable features are gated in compiler/rustc_feature/src/ and checked at the AST pass level
• #[instrument]: The tracing crate's #[instrument] attribute is used throughout for structured logging (e.g., #[instrument(level = "debug", skip(self))])
• tidy-alphabetical-start/-end: Comments marking sections that must be kept alphabetically sorted

The Workspace Manifest

The root Cargo.toml defines a Rust workspace with:

• ~45 workspace members (compiler, tools, support crates)
• Excludes: build/, compiler/rustc_codegen_cranelift, compiler/rustc_codegen_gcc, src/bootstrap, tests/rustdoc-gui
• Custom profiles: overflow-checks = false for rustc_thread_pool (workaround for CI stack overflows, see issue #90227), strip = true for lld-wrapper and wasm-component-ld

Testing Strategy

The test infrastructure is managed by compiletest (src/tools/compiletest/) with multiple test suites:

Test annotations (in .rs files):

• //~ ERROR — expected error on this line
• //~ WARN — expected warning
• //~ HELP — expected help suggestion
• //@ compile-flags: — extra compiler flags
• //@ run-pass — test should compile and run successfully
• //@ ignore-* / //@ only-* — platform filtering
• //@ revisions: — parameterized test variants

Style enforcement: The tidy tool (src/tools/tidy/) checks:

• File formatting and line length
• License headers
• Feature gate documentation
• Alphabetical ordering of declared lists
• External dependency allowlists

Note

The --bless flag updates expected output to match actual compiler output. This is the standard workflow for updating tests after intentional diagnostic changes.

Potential Improvements

Based on source analysis:

1. Incremental compilation robustness: The RUST_DEP_GRAPH / RUST_DEP_GRAPH_FILTER debugging tools suggest ongoing work on dependency graph correctness. The assert_dep_graph module contains assertion infrastructure for catching incremental compilation bugs.

2. Thread pool deadlock detection: The rustc_thread_pool fork includes custom deadlock detection (SleepData tracking) that is more conservative than upstream Rayon — the overflow-checks = false profile override for this crate is a workaround for CI stability (issue #90227).

3. GCC backend maturity: compiler/rustc_codegen_gcc/ provides an alternative code generation path through libgccjit. The extensive CG_GCCJIT_* debugging variables indicate active development. This backend could expand Rust's platform support to architectures not covered by LLVM.

4. Diagnostic infrastructure: The 997 unique error patterns extracted from source span every major compilation phase. The Fluent-based i18n system (rustc_error_messages) is relatively new and positions the compiler for multilingual diagnostics.

5. Self-profile tooling: The -Z self-profile flag and associated tooling provide detailed query-level performance data. This is the primary mechanism for identifying compilation bottlenecks and has been used to drive significant performance improvements.

Contributing Guide

1. Find an issue: Browse issues labeled E-easy or E-mentor at https://github.com/rust-lang/rust/issues
2. Set up: ./x setup compiler (or library/tools depending on focus)
3. Make changes: Edit code, run ./x check for fast feedback
4. Test: ./x test tests/ui (or the appropriate suite), use ./x suggest for guidance
5. Format: ./x fmt
6. Lint: ./x test tidy
7. Submit: Push to a fork, open a PR. CI runs the full test matrix.

The comprehensive contributor guide is at https://rustc-dev-guide.rust-lang.org/ (source: src/doc/rustc-dev-guide/).

Key development conventions:

• All compiler crates use the rustc_ prefix
• Dependencies within compiler/ use path dependencies
• External dependencies require allowlisting in src/tools/tidy/
• Code changes must pass ./x test tidy and ./x fmt --check
• New features require a feature gate in compiler/rustc_feature/
• Diagnostic changes should update affected UI test expectations with --bless

9. Integration Points

Rustup Integration

The src/tools/build-manifest/ generates manifests consumed by rustup. Distribution artifacts are produced by ./x dist and uploaded to the Rust release infrastructure.

IDE Integration (rust-analyzer)

The src/tools/rust-analyzer/ is a full Language Server Protocol implementation. It uses several compiler crates directly (proc-macro-srv for proc macro expansion). Key integration points:

• editors/code/ — VS Code extension (TypeScript, reads VSCODE_EXEC_PATH, PATH, CARGO_HOME)
• crates/rust-analyzer/src/handlers/ — LSP request handlers (3 files, 143K chars)
• crates/ide/src/ — Core IDE features: goto-definition, rename, completion, highlighting (43 files, 988K chars)
• crates/ide-assists/src/handlers/ — Code actions and refactorings (134 files, 2.3M chars)

CI Integration

The src/ci/citool/ orchestrates GitHub Actions CI:

• jobs.rs — Workflow type detection and job list computation
• metrics.rs — Build metrics deserialization from CI URLs
• utils.rs — Git command helpers

Unstable Feature Documentation

The src/tools/unstable-book-gen/ automatically generates documentation for unstable features from their feature gate definitions in compiler/rustc_feature/. The src/tools/features-status-dump/ produces machine-readable feature status reports.

License Tooling

The src/tools/collect-license-metadata/ (4 files, 20K chars) and src/tools/generate-copyright/ (2 files, 14K chars) automate license compliance. The root REUSE.toml provides structured license annotations following the REUSE specification (version 1, using reuse-tool v4.0.3). The primary license is MIT OR Apache-2.0, with specific exceptions for LLVM (Apache-2.0 WITH LLVM-exception), GCC components (GPL-3.0+), and font files (OFL-1.1).