The Rust Compiler (rustc) — User Guide

1. Quick Start

The rust-lang/rust repository is the monorepo that produces the Rust programming language compiler (rustc), the standard library (core, alloc, std, proc_macro), and the complete development toolchain including Clippy, rustfmt, Miri, rust-analyzer, and rustdoc. If you want to use Rust to compile your own programs, install via rustup instead — building from source is for contributors and distribution builders.

Key features:

• Multi-stage bootstrapping compiler written in Rust, targeting LLVM for code generation
• Experimental Cranelift and GCC codegen backends for faster debug builds and broader platform support
• Standard library spanning no_std embedded (core) through full OS integration (std)
• Bundled tools: Clippy (800+ lints), rustfmt (auto-formatting), Miri (undefined behavior detection), rust-analyzer (IDE), rustdoc (documentation generation)
• 50,000+ tests across UI diagnostics, MIR optimizations, codegen, and integration suites
• Cross-compilation for 80+ target triples
• Incremental compilation to speed up rebuilds during development

Prerequisites: Python 3, a C/C++ compiler (GCC or Clang on Linux, MSVC on Windows, Xcode on macOS), cmake, curl, and 30+ GB of disk space.

Quick build:

git clone https://github.com/rust-lang/rust.git
cd rust
./x setup compiler
./x build

Building bootstrap
    Finished `dev` profile [unoptimized] target(s)
Building stage0 library artifacts (x86_64-unknown-linux-gnu)
Building stage0 compiler artifacts (x86_64-unknown-linux-gnu)
Building stage1 library artifacts (x86_64-unknown-linux-gnu)
Building stage1 compiler artifacts (x86_64-unknown-linux-gnu)

Tip

Run ./x setup interactively to choose a profile (compiler, library, tools, codegen, dist, or none). Each profile pre-configures bootstrap.toml with sensible defaults for your workflow.

What to try next: Run ./x test tests/ui to exercise the compiler's diagnostic test suite, or ./x doc library --open to build and browse the standard library documentation.

2. Installation

System Requirements

Getting the Source

git clone https://github.com/rust-lang/rust.git
cd rust

Important

The repository is large (~2 GB clone). Use --depth 1 for a shallow clone if you only need to build without full history: git clone --depth 1 https://github.com/rust-lang/rust.git.

Platform Dependencies

Linux (Debian/Ubuntu)

sudo apt-get install build-essential python3 cmake curl ninja-build pkg-config libssl-dev

Linux (Fedora/RHEL)

sudo dnf install gcc gcc-c++ python3 cmake curl ninja-build pkgconfig openssl-devel

macOS

xcode-select --install
brew install cmake ninja python3

Windows

Install Visual Studio 2019+ with the "Desktop development with C++" workload.
Ensure Python 3 is on PATH.
Install CMake and Ninja via winget or the official installers.

Initial Configuration

Run the interactive setup wizard:

./x setup

Welcome to the Rust compiler build system!

The following profiles are available:

    a]  compiler: Contribute to the compiler itself
    b]  library: Contribute to the standard library
    c]  tools: Contribute to tools (Clippy, rustfmt, etc.)
    d]  codegen: Contribute to code generation (LLVM, Cranelift)
    e]  dist: Build a full distribution
    f]  none: Start from a blank slate

Please choose a profile (a-f):

This generates a bootstrap.toml configuration file. You can also copy and edit the annotated example:

cp bootstrap.example.toml bootstrap.toml

Note

The build system uses x.py (aliased as ./x on Unix, x.ps1 on Windows) to orchestrate multi-stage builds. All ./x commands documented here also work as python3 x.py if the shell alias is not available. The RUST_IGNORE_OLD_PYTHON environment variable suppresses warnings about older Python versions.

Building the Compiler

# Build the compiler (stage 1 by default for the "compiler" profile)
./x build

# Build a specific component
./x build compiler
./x build library
./x build src/tools/clippy

# Build stage 2 compiler (full self-hosted, slower)
./x build --stage 2

Post-Build Verification

# Run the built compiler
./build/host/stage1/bin/rustc --version

rustc 1.XX.0-dev

# Create a rustup toolchain link to your build
rustup toolchain link stage1 build/host/stage1
rustc +stage1 --version

Tip

Linking your build as a rustup toolchain lets you test it on real projects: cargo +stage1 build.

Install Troubleshooting

Error: python3: command not found

Cause: Python 3 is not installed or not on PATH.

Solution:

1. Install Python 3 from your package manager or python.org
2. Verify: python3 --version

Prevention: The x wrapper script checks for Python at startup.

Error: CMake not found

Cause: CMake is required to build LLVM from source.

Solution:

1. Install CMake via your package manager
2. Alternatively, set download-ci-llvm = true in bootstrap.toml to skip the LLVM build entirely

Error: LLVM build failed with out of memory

Cause: LLVM compilation is memory-intensive. Systems with less than 8 GB RAM may fail.

Solution:

1. Set download-ci-llvm = true in [llvm] in bootstrap.toml (recommended — downloads pre-built LLVM)
2. Or limit parallelism: ./x build -j 2
3. Or set ninja = false under [llvm] to reduce peak memory

Prevention: Use download-ci-llvm = true on memory-constrained machines.

Error: error: linking with cc failed

Cause: System linker cannot find required libraries.

Solution:

1. Debian/Ubuntu: sudo apt-get install libc6-dev
2. Fedora: sudo dnf install glibc-devel
3. macOS: ensure Xcode command line tools are installed

Error: Could not find C compiler

Cause: No C/C++ toolchain installed.

Solution:

1. Linux: sudo apt-get install build-essential
2. macOS: xcode-select --install
3. Windows: install Visual Studio with the C++ workload

3. Configuration

bootstrap.toml Overview

The primary configuration file is bootstrap.toml at the repository root, generated by ./x setup or copied from bootstrap.example.toml. It controls every aspect of the build.

Recommended development configuration:

# Fast builds for compiler contributors
[llvm]
download-ci-llvm = true   # Skip LLVM build, download pre-built

[rust]
debug-assertions = true    # Catch internal bugs
incremental = true         # Faster rebuilds

Key Environment Variables

Warning

Setting RUSTC_BOOTSTRAP=1 enables nightly-only features on any toolchain. The build system uses this internally. Never set it in production builds — it voids all stability guarantees.

See the Admin Guide for the full configuration reference including all bootstrap.toml sections, internal environment variables, and per-tool configuration knobs.

4. Core Usage

The x Build System

All interaction with the Rust build system goes through the x command (a wrapper around x.py):

Common flags:

Tip

Use ./x check during development for rapid feedback. It runs type checking without code generation, completing in a fraction of the time of a full ./x build.

Understanding Build Stages

The Rust compiler uses a multi-stage bootstrap process:

Most contributors work exclusively with Stage 1. A Stage 2 build proves the compiler can compile itself but takes significantly longer.

Note

The --keep-stage 1 flag tells the build system to reuse existing Stage 1 artifacts, rebuilding only what changed. This dramatically speeds up the edit-compile-test cycle. If you see unexpected behavior, do a clean rebuild: ./x clean && ./x build.

Running the Built Compiler

# Direct invocation
./build/host/stage1/bin/rustc my_program.rs

# Through rustup toolchain link
rustup toolchain link stage1 build/host/stage1
rustc +stage1 my_program.rs
cargo +stage1 build

Using Bundled Tools

Clippy (Linter)

Clippy provides 800+ lints for catching common mistakes, style issues, and performance pitfalls.

# Build and test Clippy
./x build src/tools/clippy
./x test src/tools/clippy

# Run Clippy on the compiler source
./x clippy compiler
./x clippy library

rustfmt (Formatter)

# Build rustfmt
./x build src/tools/rustfmt

# Format the entire repository
./x fmt

# Check formatting without modifying files
./x fmt --check

Warning

CI rejects pull requests with formatting errors. Always run ./x fmt before pushing.

Miri (MIR Interpreter)

Miri interprets Rust's Mid-level Intermediate Representation to detect undefined behavior, data races, and memory leaks.

./x build src/tools/miri
./x test src/tools/miri

rust-analyzer (IDE Support)

./x build src/tools/rust-analyzer
./x test src/tools/rust-analyzer

Important

When developing the rust-lang/rust repo, the ./x setup wizard configures rust-analyzer to use the proc-macro server built from the tree. Using a mismatched system-installed version can cause spurious errors in your IDE.

5. Common Tasks

Task: Run the Test Suite

Goal: Verify your changes pass existing tests.

# Run UI tests (the primary compiler diagnostic test suite)
./x test tests/ui

# Run a specific test file
./x test tests/ui/borrowck/borrowck-moved-value-into-closure.rs

# Run all tests for a component
./x test compiler
./x test library
./x test src/tools/clippy

# Run tests matching a filter
./x test tests/ui -- my_test_name

# Run the full test suite (takes hours)
./x test

Tip

Use ./x suggest to automatically determine which tests to run based on changed files. This is much faster than running the entire suite.

Task: Add a New UI Test

Goal: Create a test verifying specific compiler behavior.

1. Create a .rs file in the appropriate test directory:

   // tests/ui/my-new-test.rs
   fn main() {
       let x: i32 = "not a number"; //~ ERROR mismatched types
   }
   

2. Run the test to generate expected output:

   ./x test tests/ui/my-new-test.rs --bless
   

3. Review the generated tests/ui/my-new-test.stderr to confirm it matches your intent.

4. Commit both the .rs file and the .stderr file.

Important

The --bless flag overwrites expected output files with actual compiler output. Always review the generated .stderr before committing.

Task: Build for a Different Target

Goal: Cross-compile the standard library for another platform.

1. Add the target to bootstrap.toml:

   [build]
   target = ["x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu"]
   

2. Build:

   ./x build --target aarch64-unknown-linux-gnu library
   

Task: Build Standard Library Documentation

# Build and open in browser
./x doc library --open

# Build compiler internals documentation
./x doc compiler

Task: Debug an Internal Compiler Error (ICE)

1. Reproduce with backtraces:

   RUST_BACKTRACE=1 ./build/host/stage1/bin/rustc failing_code.rs
   

2. Enable debug assertions in bootstrap.toml:

   [rust]
   debug-assertions = true
   

3. Rebuild and trigger the ICE under a debugger with RUSTC_BREAK_ON_ICE=1.

4. File an issue at https://github.com/rust-lang/rust/issues with the backtrace, input code, and output of rustc --version --verbose.

Task: Profile Compiler Performance

# Time individual compiler passes
./build/host/stage1/bin/rustc -Z time-passes my_crate.rs

Task: Run the Tidy Linter

The tidy tool enforces repository-wide style and hygiene rules.

./x test tidy

Task: Build Distribution Tarballs

./x setup dist
./x dist
# Outputs in build/dist/

Task: Format Changed Files Before Committing

# Auto-format
./x fmt

# Check only (no modifications)
./x fmt --check

Task: Use an Alternative Codegen Backend

Cranelift (faster debug builds, less optimized output):

# bootstrap.toml
[rust]
codegen-backends = ["cranelift"]

GCC (experimental, broader platform support):

The rustc_codegen_gcc backend uses libgccjit. Environment variables for debugging:

Task: Vendor Dependencies for Offline Builds

./x vendor

This copies all Cargo dependencies into the repository for offline or air-gapped builds.

6. Troubleshooting

Diagnostic Decision Tree

Build fails?
├── LLVM error? → Set download-ci-llvm = true in bootstrap.toml
├── Stage 0 download fails? → Check internet, delete build/cache, retry
├── Linker error? → Install C/C++ toolchain and development libraries
├── Out of memory? → Reduce parallelism (-j 2) or use download-ci-llvm
└── Unexpected warnings/errors? → Run ./x clean, then rebuild

Test failure?
├── Output mismatch? → Review diff, use --bless if intentional
├── Timeout? → Increase RUST_TEST_THREADS or run specific tests
├── ICE during test? → Set RUST_BACKTRACE=1, check issue tracker
└── Flaky? → Re-run, check RUST_TEST_SHUFFLE_SEED for ordering issues

IDE errors?
├── Proc-macro mismatch? → Re-run ./x setup for VS Code configuration
├── Missing standard library? → Set RUST_SRC_PATH or rebuild library
└── Slow analysis? → Adjust RA_LRU_CAP, close unused workspaces

Error: error: failed to run custom build command for rustc_llvm

Cause: LLVM build failure — missing dependencies, insufficient memory, or CMake misconfiguration.

Solution:

1. Set download-ci-llvm = true in the [llvm] section of bootstrap.toml
2. If building from source: ensure CMake and Ninja are installed, and you have 10+ GB free disk space

Prevention: Use download-ci-llvm = true unless you are specifically modifying LLVM integration.

Error: error[E0554]: #![feature] may not be used on the stable release channel

Cause: Attempting to build compiler crates with cargo build instead of ./x build.

Solution:

1. Always use ./x build — it manages the bootstrap compiler and sets RUSTC_BOOTSTRAP correctly
2. Never run cargo build directly on the compiler workspace

Prevention: Use ./x build, ./x test, ./x check for all compiler work.

Error: test failed: unexpected output difference

Cause: A UI test's actual stderr/stdout differs from the expected .stderr/.stdout file.

Solution:

1. Review the diff shown in the test output
2. If the change is intentional: ./x test tests/ui/path/to/test.rs --bless
3. If unintentional: revert or fix your compiler change

Error: thread 'main' panicked at 'bootstrap artifacts not found'

Cause: The bootstrap process could not download or locate the Stage 0 compiler.

Solution:

1. Check internet connectivity
2. Delete build/cache/ and retry: rm -rf build/cache && ./x build
3. Verify src/stage0 is intact

Issue: Build is extremely slow

Cause: Building LLVM and a full stage 2 compiler from scratch is resource-intensive.

Solution:

1. Use download-ci-llvm = true (saves 20-40 minutes)
2. Use ./x check for type-checking only (no codegen)
3. Use --keep-stage 1 for incremental rebuilds after small changes
4. Set incremental = true in [rust]
5. Reduce parallelism on memory-constrained machines: ./x build -j 4

Issue: --keep-stage produces stale or incorrect results

Cause: Cached artifacts from a previous build don't reflect your latest source changes.

Solution:

1. Do a clean build: ./x clean && ./x build
2. Only use --keep-stage when your change is isolated to one stage

ICE: Wrust-2021-incompatible-closure-captures (GitHub #155497)

Cause: Internal compiler error in closure capture analysis during edition 2021 migration.

Solution:

1. Check if reproducible on latest nightly
2. File or update the tracking issue with a minimal reproduction case

ICE: InterpErrorInfo / UndefinedBehavior(ValidationError ...) (GitHub #155496)

Cause: MIR interpreter validation error during const evaluation.

Solution:

1. Simplify the const expression to isolate the trigger
2. Search the issue tracker for known instances

Error: llvm error: export_name (GitHub #155495)

Cause: LLVM backend error related to symbol export naming.

Solution:

1. Check if the target triple is supported for the feature being used
2. Try building without LTO to isolate the issue

7. FAQ

Q: What is rust-lang/rust and who is it for?

This repository contains the source code for the Rust compiler, standard library, and toolchain. It is for compiler contributors, language designers, standard library developers, tool maintainers, and distribution packagers. Regular Rust users should install via rustup.

Q: Should I use cargo build or ./x build?

Always ./x build. The Rust compiler has a multi-stage bootstrap that cargo build cannot manage. The x.py script handles downloading the bootstrap compiler, managing stages, and setting internal environment variables.

Q: How long does a full build take?

A clean build with LLVM from source: 30–90 minutes depending on hardware. With download-ci-llvm = true: 10–30 minutes. Incremental rebuilds with --keep-stage 1: under 5 minutes for small changes.

Q: Which stage should I test against?

Stage 1 for almost all development work. Stage 2 only when verifying self-hosting behavior or preparing release builds.

Q: How do I run only tests relevant to my change?

Use ./x suggest to auto-detect affected tests. Or target specific suites: ./x test tests/ui, ./x test tests/mir-opt, ./x test src/tools/clippy.

Q: What does --bless do?

It updates the expected output files (.stderr, .stdout) for UI tests to match the current compiler output. Use it when you have intentionally changed compiler diagnostics.

Q: Can I cross-compile Rust programs with a from-source build?

Yes. Add target triples to [build] target in bootstrap.toml, build with ./x build --target <triple>, then use cargo +stage1 build --target <triple>.

Q: What are the test suite directories?

Q: Where is the rustc dev guide?

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

Q: How do I debug a specific compiler pass?

Set RUSTC_LOG=<crate_name>=debug to enable logging. For example: RUSTC_LOG=rustc_borrowck=debug ./build/host/stage1/bin/rustc test.rs. The rustc_log crate manages the logging infrastructure using the tracing framework.

Q: What is RUSTC_BOOTSTRAP?

An environment variable that enables #![feature(...)] attributes on any compiler channel. The build system sets it automatically. Setting it manually in end-user code voids Rust's stability guarantees.

Q: How do I build a distributable release?

Use the dist profile: ./x setup dist && ./x dist. Tarballs are produced in build/dist/.