Onboarding: rust-lang/rust

Generated by RepoPilot · 2026-05-05 · Source

Verdict

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 33%)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

This is the canonical source repository for the Rust programming language itself — it contains the rustc compiler (under compiler/rustc and the many compiler/rustc_* crates), the standard library, and all official tooling. It solves the problem of building a systems programming language with compile-time memory safety guarantees via an ownership/borrow-checker model, zero-cost abstractions, and no garbage collector. Monorepo: the compiler lives in compiler/rustc_* crates (each a separate concern: parser, HIR, MIR, trait solving, codegen, etc.), the standard library in library/core, library/alloc, library/std, developer tooling in src/tools/ (clippy, rustfmt, miri, compiletest, tidy, etc.), and the bootstrap build system itself in src/bootstrap/. The workspace Cargo.toml at root wires it all together with resolver='2'.

Who it's for

Two audiences: (1) systems programmers using Rust to build OSes, embedded firmware, WebAssembly, or performance-critical services who want to understand or patch the compiler; (2) compiler engineers and language contributors who work on rustc internals, MIR optimizations, LLVM codegen, standard library APIs, or language feature stabilization via the RFC process.

Maturity & risk

Rust 1.0 shipped in 2015 and the repo has thousands of contributors, a full CI pipeline in .github/workflows/ci.yml, and an extensive test suite under src/tools/compiletest and tests/. The project is unambiguously production-ready and one of the most actively maintained language implementations in existence, with multiple commits landing daily.

Risk is extremely low for consumption — Rust has a formal stability guarantee and a six-week release train. Contributing is high-complexity: the compiler codebase is massive (140M+ lines of Rust), bootstrapping requires a prior stage0 compiler, and CI can take hours. The Cargo.lock pins all tool dependencies and the workspace excludes cranelift/GCC codegen backends, so those require separate handling.

Active areas of work

Active areas visible from the repo structure include: Miri (src/tools/miri) for UB detection, the wasm-component-ld linker (src/tools/wasm-component-ld) for WASM components, coverage tooling (src/tools/coverage-dump), the opt-dist pipeline (src/tools/opt-dist) for PGO/LTO optimized builds, and ongoing rustdoc improvements (src/tools/rustdoc, rustdoc-gui-test). The renovate.json5 and dependencies.yml indicate active dependency automation.

Get running

git clone https://github.com/rust-lang/rust.git && cd rust && cp bootstrap.example.toml bootstrap.toml # edit bootstrap.toml as needed && ./x setup # interactive setup wizard && ./x build # builds stage1 compiler — takes 30-60 min on first run && ./x test library/std # run std tests

Daily commands: ./x build # full compiler build ./x build compiler/rustc # just the compiler ./x test compiler/rustc_borrowck # test a specific crate ./x doc library/std # build std docs ./x fmt # run rustfmt on the repo ./x clippy compiler # run clippy on compiler crates

Map of the codebase

• compiler/rustc/src/main.rs — Entry point for the rustc compiler binary — every compilation invocation starts here before delegating to the driver.
• compiler/rustc_ast/src/ast.rs — Defines the core Abstract Syntax Tree node types that every compiler phase (parsing, name resolution, HIR lowering) operates on.
• compiler/rustc_abi/src/lib.rs — Central ABI and data layout definitions shared across codegen backends and the type system — wrong assumptions here cause silent miscompilations.
• compiler/rustc_abi/src/layout.rs — Implements the type layout algorithm that determines struct field offsets, padding, and size — foundational to correct code generation.
• compiler/rustc_ast/src/token.rs — Defines every lexical token in the Rust language; the lexer, parser, and macro expander all depend on this taxonomy.
• Cargo.toml — Workspace manifest that declares all compiler and tool crates, their resolver version, and inter-crate dependency structure.
• compiler/rustc_ast/src/visit.rs — Implements the Visitor pattern over the AST used by linting, name resolution, and many compiler passes — must be updated whenever AST nodes change.

How to make changes

Add a new AST node type

1. Define the new node struct or enum variant in the central AST definitions file. (compiler/rustc_ast/src/ast.rs)
2. Add a corresponding visit method to the read-only visitor trait so passes can traverse the new node. (compiler/rustc_ast/src/visit.rs)
3. Add a mutable visit method so macro expansion and AST transformation passes can rewrite the node. (compiler/rustc_ast/src/mut_visit.rs)
4. Add any new token variants needed by the lexer/parser to represent the node's syntax. (compiler/rustc_ast/src/token.rs)

Add support for a new extern ABI

1. Add the ABI string variant to the ExternAbi enum and its Display/parsing logic. (compiler/rustc_abi/src/extern_abi.rs)
2. Implement or extend calling convention register assignment rules for the new ABI. (compiler/rustc_abi/src/callconv.rs)
3. If the ABI requires target-specific register types, add them here. (compiler/rustc_abi/src/callconv/reg.rs)

Add a new compiler attribute

1. Define the attribute's data structure and any associated metadata in the attribute module. (compiler/rustc_ast/src/attr/mod.rs)
2. Add the attribute's data structure definition if it carries complex parsed data. (compiler/rustc_ast/src/attr/data_structures.rs)
3. Update the AST node that the attribute attaches to, ensuring it appears in traversals. (compiler/rustc_ast/src/ast.rs)

Add a new built-in language feature / expansion

1. Create a new expansion module or extend the existing expansion entry point. (compiler/rustc_ast/src/expand/mod.rs)
2. If the feature needs allocator-like special-casing, model it after the existing allocator expansion. (compiler/rustc_ast/src/expand/allocator.rs)
3. Register the feature's AST representation so the visitor infrastructure covers it. (compiler/rustc_ast/src/visit.rs)

Why these technologies

• Rust (self-hosted) — The compiler is written in the language it compiles, enabling dogfooding, leveraging Rust's own safety guarantees, and allowing the standard library to be used in compiler implementation.
• Arena allocation (rustc_arena) — Compiler IR nodes have complex, interleaved lifetimes; arena allocation avoids individual heap allocations and allows bulk deallocation at phase boundaries, dramatically improving throughput.
• Workspace Cargo resolver v2 — The repo contains 100+ crates with divergent feature requirements; resolver v2 avoids feature unification problems that would otherwise force unnecessary dependencies into every crate.
• LLVM (via rustc_codegen_llvm) — LLVM provides mature, battle-tested optimization pipelines and target support for dozens of architectures, avoiding the need to build a custom backend from scratch.
• Visitor pattern (visit.rs / mut_visit.rs) — Separating traversal from node definitions allows many independent compiler passes (linting, name resolution, lowering) to operate over the AST without modifying node types.

Trade-offs already made

• Self-hosted compiler (bootstrapping)

  • Why: Allows the compiler to use the full Rust language and standard library in its own implementation.
  • Consequence: Requires a multi-stage bootstrap process (stage0 → stage1 → stage2), increasing CI complexity and build times significantly.

• Monorepo for compiler + stdlib + tools

  • Why: Ensures that compiler changes and standard library changes are always tested together, preventing interface drift.
  • Consequence: The repository is very large (~600 files at top level, thousands total), making orientation for new contributors difficult.

• Arena-based IR allocation with lifetime parameters

  • Why: Maximizes allocation performance and makes sharing of IR nodes cheap.
  • Consequence: Pervasive lifetime annotations in compiler internals make the code harder to read and refactor; lifetime errors in compiler code are notoriously difficult to diagnose.

• Separate AST → HIR → MIR → LLVM IR pipeline

  • Why: Each IR is optimally shaped for its compilation phase, keeping concerns separated and enabling targeted optimizations.
  • Consequence: Multiple

Traps & gotchas

1. The workspace excludes compiler/rustc_codegen_cranelift and compiler/rustc_codegen_gcc — these must be built via ./x with specific flags, not with plain cargo. 2) src/bootstrap is also excluded from the workspace and uses its own Cargo.toml — never run cargo commands directly inside it. 3) Building requires a stage0 compiler downloaded from the internet; the specific version is pinned in src/stage0. 4) The rustc_thread_pool (rayon fork) has overflow-checks disabled in release profile due to issue #90227 — this is intentional. 5) tidy checks enforce tidy-alphabetical-start/end block ordering in Cargo.toml member lists — inserting a new workspace member out of alphabetical order will fail CI.

Architecture

Concepts to learn

• Multi-stage bootstrap compilation — rustc is written in Rust, so building it requires a prior (stage0) compiler; understanding the stage0→stage1→stage2 pipeline is essential before making any compiler changes.
• Mid-level Intermediate Representation (MIR) — MIR is the core IR where borrow checking, optimization, and const evaluation happen; most compiler work below HIR and above LLVM IR touches MIR.
• Chalk trait solver — Rust's new trait solving engine (being integrated into rustc) uses logic-programming-style rules; understanding it is necessary for work on type system features or trait errors.
• Borrow checker / Non-Lexical Lifetimes (NLL) — The core memory-safety enforcement mechanism in rustc; implemented in compiler/rustc_borrowck using MIR-based dataflow analysis.
• Procedural macros and hygiene — Rust's macro system uses span-based hygiene to prevent name collisions; this affects the parser, name resolution, and how compiler plugins interact with user code.
• Profile-Guided Optimization (PGO) with LLVM — The opt-dist tool (src/tools/opt-dist) builds the production compiler with PGO+LTO via LLVM; understanding this is required to work on release build performance.
• Fluent localization for diagnostics — rustc uses the Fluent internationalization system for compiler error messages, stored in .ftl files; adding or modifying diagnostics requires knowing this system rather than plain string literals.

Related repos

• rust-lang/rust-clippy — The official Rust linter; while its source lives in src/tools/clippy here, the upstream development repo tracks issues and lint RFCs separately.
• rust-lang/cargo — The Rust package manager and build tool that every Rust project uses; tightly coupled to rustc's ABI and feature flags.
• rust-lang/rust-analyzer — The official LSP language server for Rust IDEs; reimplements much of rustc's analysis independently and must track compiler changes.
• rust-lang/miri — The Rust undefined behavior interpreter; its canonical upstream, though a copy lives in src/tools/miri and is tested against the in-tree compiler.
• gcc-mirror/gcc — Predecessor/inspiration for the GCC codegen backend (compiler/rustc_codegen_gcc); Rust originally targeted LLVM exclusively but GCC backend enables new target support.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Split compiler/rustc_abi/src/lib.rs into focused sub-modules

The rustc_abi crate already has some sub-modules (callconv, layout, extern_abi, canon_abi) but lib.rs likely still contains a large amount of core ABI type definitions and logic that could be extracted into their own focused files (e.g. scalar.rs, aggregate.rs, primitive.rs). This is a high-value refactor for a large compiler crate that new contributors can tackle incrementally without deep compiler knowledge, improving readability and compile times for the crate.

• [ ] Audit compiler/rustc_abi/src/lib.rs for large type definitions (Scalar, Abi, FieldsShape, etc.) that are not yet in sub-modules
• [ ] Create new files such as compiler/rustc_abi/src/scalar.rs, compiler/rustc_abi/src/primitive.rs, compiler/rustc_abi/src/aggregate.rs as appropriate
• [ ] Move identified types and their impl blocks into the new sub-modules, keeping pub use re-exports in lib.rs to avoid breaking the public API
• [ ] Ensure existing tests in compiler/rustc_abi/src/tests.rs still compile and pass after the reorganization
• [ ] Run ./x check compiler/rustc_abi and ./x test compiler/rustc_abi to verify nothing is broken

Add dedicated unit tests for compiler/rustc_abi/src/layout/simple.rs

The file compiler/rustc_abi/src/layout/simple.rs handles layout computation for 'simple' types. The only test file visible is compiler/rustc_abi/src/tests.rs, which likely focuses on higher-level cases. Adding targeted unit tests directly inside simple.rs (or expanding tests.rs with cases covering simple layout edge cases like zero-sized types, 1-byte scalars, and packed structs) would improve confidence when contributors modify low-level layout logic, and serve as living documentation of expected behavior.

• [ ] Read through compiler/rustc_abi/src/layout/simple.rs to understand what cases it handles (ZSTs, scalars, arrays, etc.)
• [ ] Review the existing tests in compiler/rustc_abi/src/tests.rs to identify gaps in coverage for the simple layout path
• [ ] Add a #[cfg(test)] mod tests block inside compiler/rustc_abi/src/layout/simple.rs with unit tests for: zero-sized types, single scalar types, homogeneous arrays, and packed struct representations
• [ ] Ensure tests use only types available within the crate (no TyCtxt dependency) so they run without bootstrapping the full compiler
• [ ] Run ./x test compiler/rustc_abi to confirm all new and existing tests pass

Add a GitHub Actions workflow to enforce tidy-alphabetical ordering on Cargo.toml workspace members in CI

The Cargo.toml already uses tidy-alphabetical-start / tidy-alphabetical-end markers for the workspace members list, and the repo has a tidy tool at src/tools/tidy. However, there is no standalone lightweight GitHub Actions workflow that runs only the tidy check on pull requests that modify Cargo.toml or Cargo.lock, separate from the full CI run in .github/workflows/ci.yml. A fast, targeted tidy-check workflow would give contributors immediate feedback on ordering violations without waiting for the full multi-hour CI pipeline.

• [ ] Review .github/workflows/ci.yml to understand how the existing tidy step is invoked (likely ./x test tidy)
• [ ] Create a new file .github/workflows/tidy-check.yml that triggers on pull_request paths: ['Cargo.toml', 'Cargo.lock', '**/Cargo.toml']
• [ ] In the workflow, set up the minimal Rust toolchain using actions/setup-rust or dtolnay/rust-toolchain and run ./x test tidy -- --check-only or equivalent

Good first issues

1. Add missing UI test coverage for specific edge cases in compiler/rustc_borrowck — look for // FIXME comments in existing .rs test files under tests/ui/borrowck/. 2) Improve error message diagnostics for a specific compiler/rustc_resolve error variant by adding a structured suggestion (StructuredSuggestion) in the relevant match arm. 3) Add documentation examples (/// # Examples blocks) to functions in library/core/src/slice/ or library/core/src/str/ that currently have none — these are high-visibility and easy to verify with ./x doc.

Top contributors

• @JonathanBrouwer — 21 commits
• @bors — 16 commits
• @RalfJung — 11 commits
• @jhpratt — 8 commits
• @nnethercote — 7 commits

Recent commits

• cb40c25 — Auto merge of #156139 - inq:minimize-reshell-perf, r=lcnr (bors)
• 55ff2e1 — Short-circuit calculate_fallback_to_f32 when no float vars (inq)
• 1d72d7e — Auto merge of #156134 - jhpratt:rollup-79KaBC4, r=jhpratt (bors)
• 037e2b0 — Rollup merge of #156132 - nnethercote:more-lifting-tweaks, r=oli-obk (jhpratt)
• 06c89cf — Rollup merge of #156125 - GTimothy:refactor-exprparenthesesneeded, r=ShoyuVanilla (jhpratt)
• 19fbc62 — Rollup merge of #156120 - inq:test-alias-relate-7, r=lcnr (jhpratt)
• d4c413e — Apply suggestion from @lcnr (inq)
• 783062d — Auto merge of #154095 - joboet:vec_clear_truncate, r=nnethercote (bors)
• 2cf4884 — Remove silly FmtPrinter<'tcx, 'tcx> instance. (nnethercote)
• 809fcab — Shift lift calls outward. (nnethercote)

Security observations

• Medium · Overflow Checks Disabled for rustc_thread_pool — Cargo.toml (profile.release.package.rustc_thread_pool). The Cargo.toml workspace configuration explicitly disables overflow checks for the rustc_thread_pool package (a fork of Rayon) with overflow-checks = false in the release profile. This is acknowledged as a workaround for a deadlock detection issue (rust-lang/rust#90227). Disabling overflow checks means integer overflow/underflow in that crate will silently wrap in release builds, which could mask logic errors or be exploited in adversarial scenarios where the thread pool interacts with untrusted input or scheduling decisions. Fix: Resolve the underlying deadlock detection bug referenced in issue #90227 and re-enable overflow checks (overflow-checks = true) for rustc_thread_pool. Do not leave this workaround in place indefinitely.
• Low · Partial File Structure Visibility Limits Full Dependency Audit — Cargo.lock. Only a partial file structure was provided for analysis. The Cargo.lock file is present in the repository root, which pins all transitive dependency versions. Without inspecting its full contents, it is not possible to confirm that all dependencies are free from known CVEs. Given the large number of workspace members (including tools like Miri, Clippy, rustfmt, and others), the attack surface from third-party crates could be significant. Fix: Regularly audit Cargo.lock using cargo audit (from the cargo-audit tool backed by the RustSec Advisory Database) in CI/CD pipelines to detect and remediate known vulnerabilities in transitive dependencies.
• Low · Autodiff and Typetree AST Expansion Modules May Introduce Unsafe Parsing Paths — compiler/rustc_ast/src/expand/autodiff_attrs.rs, compiler/rustc_ast/src/expand/typetree.rs. The presence of compiler/rustc_ast/src/expand/autodiff_attrs.rs and compiler/rustc_ast/src/expand/typetree.rs suggests experimental or specialized expansion code paths. Compiler expansion and macro processing code historically has been a source of parsing edge cases, potential panics, or logic errors when handling malformed or adversarially crafted inputs. While this is a compiler codebase (not a runtime library), malicious inputs could trigger denial-of-service via compiler crashes or, in worst cases, miscompilation. Fix: Ensure these modules have thorough fuzz testing coverage (e.g., using cargo-fuzz or the existing Rust fuzzing infrastructure). Validate that all parser/expansion paths handle malformed inputs gracefully with proper error reporting rather than panics.
• Low · GitHub Actions Workflow Files Present — Supply Chain Risk — .github/workflows/. The repository contains several GitHub Actions workflow files (.github/workflows/ci.yml, dependencies.yml, ghcr.yml, post-merge.yml). If any workflow uses unpinned third-party actions (e.g., uses: some-action@v1 instead of a full commit SHA), it is vulnerable to supply chain attacks where a compromised or malicious action update could execute arbitrary code in the CI environment with access to repository secrets. Fix: Pin all third-party GitHub Actions to specific commit SHAs rather than mutable tags or branch references. Use tools like dependabot (already configured via .github/renovate.json5) or actionlint to enforce this. Regularly review and rotate any secrets used in CI workflows.
• Low · Renovate Configuration Present — Automated Dependency Updates Risk — .github/renovate.json5. The .github/renovate.json5 file indicates automated dependency update tooling is configured. While this is a positive security practice, misconfigured Renovate rules (e.g., auto-merge enabled without sufficient review gates, overly broad update scopes) can introduce breaking or vulnerable dependency updates automatically without sufficient human review. Fix: Ensure Renovate is configured to require human review and CI passage before merging dependency updates. Restrict auto-merge to only patch-level updates from trusted, well-known packages. Review the Renovate config periodically for overly permissive rules.
• Low · Windows Manifest File for rustc Binary — undefined. The file compiler/rustc/Windows Manifest.xml (note the space in the filename) configures Windows-specific executable properties. Misconfigured Windows manifests Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.