x.py Build Script Reference

Overview

x.py is the main entry point for building, testing, and developing the Rust compiler. It’s a cross-platform script that bootstraps the build system and provides a consistent interface across all platforms.

Entry Points

x (Unix)

Shell script for Unix-like systems (Linux, macOS, BSD)

x.ps1 (Windows)

PowerShell script for Windows systems

x.py (Cross-platform)

Python script that works on all platforms

All three entry points provide identical functionality. Use the one most convenient for your platform.

Quick Start

# Build the compiler and standard library (stage 1)
./x.py build --stage 1

# Run tests
./x.py test

# Build documentation
./x.py doc

# Install locally
./x.py install

Subcommands

build

Compile the compiler, libraries, or specific components.

./x.py build [OPTIONS] [PATHS...]

--stage

number

default:"1"

Stage to build (0, 1, or 2). Each stage uses the previous stage’s compiler.

--timings

flag

Pass --timings to Cargo to generate build timing information.

-j, --jobs

number

Number of parallel jobs to run. Defaults to number of CPU cores.

Examples:

# Build stage 1 compiler and standard library
./x.py build --stage 1 library/std

# Results in: build/$ARCH/stage1/bin/rustc

check

Quickly check code for errors without producing binaries.

./x.py check [OPTIONS] [PATHS...]

--all-targets

flag

Check all targets (lib, bin, tests, examples, benches).

Examples:

# Check the standard library
./x.py check library/std

# Check compiler for errors
./x.py check compiler/rustc

# Check everything
./x.py check --all-targets

check is much faster than build since it doesn’t generate code. Use it for quick validation during development.

clippy

Run Clippy linter on Rust code.

./x.py clippy [OPTIONS] [PATHS...]

--fix

flag

Automatically apply Clippy suggestions.

--allow-dirty

flag

Allow fixing even with uncommitted changes (requires --fix).

--allow-staged

flag

Allow fixing even with staged changes (requires --fix).

-A, --allow

string[]

Clippy lints to allow.

-D, --deny

string[]

Clippy lints to deny.

-W, --warn

string[]

Clippy lints to warn on.

Examples:

# Run clippy on standard library
./x.py clippy library/core

# Auto-fix issues
./x.py clippy library/std --fix

# Deny specific lints
./x.py clippy -D clippy::unwrap_used

test

Run test suites.

./x.py test [OPTIONS] [PATHS...]

--stage

number

default:"1"

Stage to test. Note that test --stage N uses the stage N-1 compiler.

--test-args

string

Arguments to pass to the test runner (libtest, compiletest, or rustdoc).

--no-fail-fast

flag

Run all tests regardless of failures.

--bless

flag

Automatically update expected test outputs (for UI tests).

--no-doc

flag

Skip documentation tests.

--doc

flag

Run only documentation tests.

--compare-mode

string

Mode for comparing UI test output (e.g., “next-solver”).

--pass

check | build | run

Force check/build/run-pass tests to this mode.

Examples:

# Run UI tests
./x.py test tests/ui

# Run standard library tests
./x.py test library/std

# Run specific test with filter
./x.py test library/std --test-args hash_map

./x.py test --stage N does NOT test the stage N compiler. It uses the stage N-1 compiler to test stage N artifacts.

doc

Build documentation.

./x.py doc [OPTIONS] [PATHS...]

--open

flag

Open the documentation in a browser after building.

--json

flag

Generate JSON format documentation in addition to HTML.

Examples:

# Build and open std docs
./x.py doc library/std --open

# Build all documentation
./x.py doc

# Build compiler docs
./x.py doc compiler

# Build with JSON output
./x.py doc library/std --json

fmt

Format code using rustfmt.

./x.py fmt [OPTIONS]

--check

flag

Check if code is formatted without applying changes.

--all

flag

Format all files, not just modified ones.

Examples:

# Format modified files
./x.py fmt

# Check formatting
./x.py fmt --check

# Format all files
./x.py fmt --all

clean

Remove build artifacts.

./x.py clean [OPTIONS]

--all

flag

Clean entire build directory.

--stage

number

Clean specific stage without touching other artifacts.

Examples:

# Clean stage 2
./x.py clean --stage 2

# Clean everything
./x.py clean --all

dist

Build distribution artifacts (tarballs).

./x.py dist [PATHS...]

Examples:

# Create distribution tarballs
./x.py dist

# Distribute specific components
./x.py dist rustc rust-std

install

Install built artifacts to a prefix.

./x.py install [PATHS...]

Examples:

# Install to default prefix (/usr/local)
./x.py install

# Install specific components
./x.py install library/std cargo

run

Run tools from the repository.

./x.py run [OPTIONS] <TOOL> -- [ARGS...]

--args

string[]

Arguments to pass to the tool.

Examples:

# Run bump-stage0 tool
./x.py run src/tools/bump-stage0

# Run with arguments
./x.py run src/tools/tidy -- --help

setup

Interactive setup for development environment.

./x.py setup [PROFILE]

PROFILE

library | compiler | tools | dist | none

Development profile to configure.

Profiles:

library

For standard library development:

Downloads CI-built LLVM and rustc
Minimal build configuration
Fast iteration on stdlib changes

compiler

For compiler development:

Downloads CI-built LLVM
Builds rustc from source
Optimized for compiler changes

tools

For tool development (cargo, rustfmt, etc.):

Downloads CI-built compiler
Minimal configuration

dist

For building distributions:

Builds everything from source
Full optimization
Used for releases

Examples:

# Interactive setup
./x.py setup

# Setup for compiler development
./x.py setup compiler

# Setup git hooks
./x.py setup hook

vendor

Vendor Rust dependencies.

./x.py vendor [OPTIONS]

--sync

path[]

Additional Cargo.toml files to sync and vendor.

--versioned-dirs

flag

Always include version in subdirectory names.

Examples:

# Vendor all dependencies
./x.py vendor

# Vendor with additional manifests
./x.py vendor --sync path/to/Cargo.toml

Global Options

These options work with all subcommands:

--config

path

Path to bootstrap.toml configuration file.

--build-dir

path

Build directory (overrides config).

--build

triple

Build target triple.

--host

triple[]

Host target triples.

--target

triple[]

Target triples to build for.

--exclude

path[]

Paths to exclude from build.

--skip

path[]

Paths to skip.

--include-default-paths

flag

Include default paths in addition to specified ones.

-v, --verbose

flag

Verbose output. Use multiple times for more verbosity (-vv, -vvv).

-i, --incremental

flag

Use incremental compilation.

--dry-run

flag

Show what would be built without actually building.

--keep-stage

number[]

Stages to keep without recompiling.

--keep-stage-std

number[]

Standard library stages to keep without recompiling.

--color

auto | always | never

Control color output.

--warnings

deny | warn | default

How to handle warnings.

--json-output

flag

Use JSON message format.

--on-fail

command

Command to run on failure.

--set

key=value

Override bootstrap.toml options (e.g., --set rust.debug=true).

Common Workflows

Quick Development Iteration

# Initial setup
./x.py setup compiler

# Make changes to compiler
vim compiler/rustc_something/src/lib.rs

# Quick check
./x.py check compiler/rustc

# Full build (only if needed)
./x.py build --stage 1 --keep-stage 0

# Test changes
./x.py test tests/ui --stage 1

Working on Standard Library

# Setup for library development
./x.py setup library

# Edit std
vim library/std/src/collections/hash/map.rs

# Test specific module
./x.py test library/std --test-args collections::hash

# Build docs
./x.py doc library/std --open

Running Benchmarks

# Build optimized compiler
./x.py build --stage 2

# Run benchmarks
./x.py bench library/std

Cross-Compilation

# Build for specific target
./x.py build --target wasm32-wasip1

# Test cross-compiled artifacts
./x.py test --target aarch64-unknown-linux-gnu

Performance Tips

Use --keep-stage

Prevent recompilation of unchanged stages:

./x.py build --keep-stage 0 --keep-stage 1

Download CI Artifacts

Configure in bootstrap.toml:

[llvm]
download-ci-llvm = true

[rust]
download-rustc = "if-unchanged"

Use check Instead of build

For quick validation:

./x.py check compiler/rustc

Limit Parallel Jobs on Low Memory

Prevent OOM errors:

./x.py build -j 4

Troubleshooting

Build Failures

# Clean and rebuild
./x.py clean --stage 2
./x.py build --stage 2

# Very verbose output
./x.py build -vvv

Python Version Issues

# Force Python 3
export PYTHON=python3
./x.py build

Submodule Issues

# Update submodules
git submodule update --init --recursive

# Or let bootstrap handle it
./x.py build  # Will update submodules automatically

Bootstrap System

Learn about the bootstrap architecture

Configuration Options

Explore bootstrap.toml settings

Compiler Internals

Build System

Resources

x.py Build Script Reference

Overview

Entry Points

x (Unix)

x.ps1 (Windows)

x.py (Cross-platform)

Quick Start

Subcommands

build

check

clippy

test

doc

fmt

clean

dist

install

run

setup

vendor

Global Options

Common Workflows

Quick Development Iteration

Working on Standard Library

Running Benchmarks

Cross-Compilation

Performance Tips

Troubleshooting

Build Failures

Python Version Issues

Submodule Issues

Bootstrap System

Configuration Options

Build docs developers (and LLMs) love

Compiler Internals

Build System

Resources

​Overview

​Entry Points

x (Unix)

x.ps1 (Windows)

x.py (Cross-platform)

​Quick Start

​Subcommands

​build

​check

​clippy

​test

​doc

​fmt

​clean

​dist

​install

​run

​setup

​vendor

​Global Options

​Common Workflows

​Quick Development Iteration

​Working on Standard Library

​Running Benchmarks

​Cross-Compilation

​Performance Tips

​Troubleshooting

​Build Failures

​Python Version Issues

​Submodule Issues

​Related Documentation

Bootstrap System

Configuration Options

Build docs developers (and LLMs) love

Overview

Entry Points

Quick Start

Subcommands

build

check

clippy

test

doc

fmt

clean

dist

install

run

setup

vendor

Global Options

Common Workflows

Quick Development Iteration

Working on Standard Library

Running Benchmarks

Cross-Compilation

Performance Tips

Troubleshooting

Build Failures

Python Version Issues

Submodule Issues

Related Documentation