Summary

Getting Started

About this guide

---

Building and debugging rustc

• How to build and run the compiler
  • Quickstart
  • Prerequisites
  • Suggested workflows
  • Distribution artifacts
  • Building documentation
  • Rustdoc overview
  • Adding a new target
  • Optimized build
• Testing the compiler
  • Running tests
    • Testing with Docker
    • Testing with CI
  • Adding new tests
  • Best practices
  • Compiletest
    • UI tests
    • Test directives
    • Minicore
  • Ecosystem testing
    • Crater
    • Fuchsia
    • Rust for Linux
  • Codegen backend testing
    • Cranelift codegen backend
    • GCC codegen backend
  • Performance testing
  • Autodiff CI job
  • Pre-stabilization CI job for the next solver and polonius alpha
  • Misc info
• Debugging the compiler
  • Using the tracing/logging instrumentation
• Profiling the compiler
  • with the linux perf tool
  • with Windows Performance Analyzer
  • with the Rust benchmark suite
• crates.io dependencies

Contributing to Rust

• Contribution procedures
• About the compiler team
• Using Git
• Mastering @rustbot
• Walkthrough: a typical contribution
• Implementing new language features
• Stability guarantees
• Stability attributes
• Stabilizing language features
  • Stabilization report template
• Feature Gates
• Coding conventions
• Procedures for breaking changes
• Using external repositories
• Fuzzing
• Notification groups
  • Apple
  • ARM
  • Emscripten
  • Fuchsia
  • LoongArch
  • RISC-V
  • Rust for Linux
  • WASI
  • WebAssembly
  • Windows
  • GPU target
• Licenses
• Editions

Bootstrapping

• Prologue
• What Bootstrapping does
• How Bootstrap does it
• Writing tools in Bootstrap
• Debugging bootstrap
• cfg(bootstrap) in dependencies

High-level compiler architecture

• Prologue
• Overview of the compiler
• The compiler source code
• Queries: demand-driven compilation
  • The Query Evaluation Model in detail
  • Incremental compilation
  • Incremental compilation in detail
  • Debugging and testing
  • Salsa
• Memory management in rustc
• Serialization in rustc
• Parallel compilation
• Rustdoc internals
  • Search
  • The rustdoc-html test suite
  • The rustdoc-gui test suite
  • The rustdoc-json test suite
• GPU offload internals
  • Installation
  • Usage
  • Contributing
• Autodiff internals
  • Installation
  • How to debug
  • Autodiff flags
  • Type Trees

Source code representation

• Prologue
• Syntax and the AST
  • Lexing and parsing
  • Macro expansion
  • Name resolution
  • Attributes
  • #[test] implementation
  • Panic implementation
  • AST validation
  • Feature gate checking
  • Lang Items
• The HIR (High-level IR)
  • Lowering AST to HIR
  • Attribute Parsing
  • Debugging
• Ambig/Unambig Types and Consts
• The THIR (Typed High-level IR)
• The MIR (Mid-level IR)
  • MIR construction
  • MIR visitor and traversal
  • MIR queries and passes: getting the MIR
• Inline assembly

Supporting infrastructure

• Command-line arguments
• rustc_driver and rustc_interface
  • External rustc_drivers
  • Example: Type checking
  • Example: Getting diagnostics
• Errors and lints
  • Diagnostic and subdiagnostic structs
  • Translation
  • LintStore
  • Error codes
  • Diagnostic items
  • ErrorGuaranteed

Analysis

• Prologue
• Generic parameter definitions
  • EarlyBinder and instantiating parameters
• Binders and Higher ranked regions
  • Instantiating binders
• Early vs Late bound parameters
• The ty module: representing types
  • ADTs and Generic Arguments
  • Parameter types/consts/regions
• TypeFolder and TypeFoldable
• Aliases and normalization
• Typing/Param envs
• Type inference
• Trait solving
  • Higher-ranked trait bounds
  • Caching subtleties
  • Implied bounds
  • Specialization
  • Chalk-based trait solving
    • Lowering to logic
    • Goals and clauses
    • Canonical queries
    • Canonicalization
  • Next-gen trait solving
    • Invariants of the type system
    • The solver
    • Candidate preference
    • Canonicalization
    • Coinduction
    • Caching
    • Proof trees
    • Opaque types
    • Significant changes and quirks
    • Sharing the trait solver with rust-analyzer
  • Unsize and CoerceUnsized traits
  • Having separate Trait and Projection bounds
• Well-formedness
• Variance
• Coherence checking
• HIR Type checking
  • Coercions
  • Method lookup
• Const generics
• Opaque types
  • Inference details
  • Return Position Impl Trait In Trait
  • Region inference restrictions
• Const traits and const condition checking
• Pattern and exhaustiveness checking
• Unsafety checking
• MIR dataflow
• Drop elaboration
• The borrow checker
  • Tracking moves and initialization
    • Move paths
  • MIR type checker
  • Drop check
  • Region inference
    • Constraint propagation
    • Lifetime parameters
    • Member constraints
    • Placeholders and universes
    • Closure constraints
    • Error reporting
  • Two-phase-borrows
• Closure capture inference
• Async closures/“coroutine-closures”

MIR to binaries

• Prologue
• MIR optimizations
• Debugging MIR
• Constant evaluation
  • Interpreter
• Monomorphization
• Lowering MIR
• Code generation
  • Updating LLVM
  • Debugging LLVM
  • Backend Agnostic Codegen
  • Implicit caller location
• Debug info
  • Rust codegen
  • LLVM codegen
  • Debugger internals
    • LLDB internals
    • GDB internals
  • Debugger visualizers
    • LLDB - Python Providers
    • GDB - Python Providers
    • CDB - Natvis
  • Testing
  • (Lecture notes) Debugging support in the Rust compiler
• Libraries and metadata
• Profile-guided optimization
• LLVM source-based code coverage
• Sanitizers support

---

Appendix A: Background topics

Appendix B: Glossary

Appendix C: Code Index

Appendix D: Compiler Lecture Series

Appendix E: Bibliography

Appendix Z: HumorRust