Skip to main content

​
Configuration File

The build system uses bootstrap.toml for configuration. You can:
  1. Create it manually
  2. Generate it with ./configure
  3. Use ./x.py setup for interactive configuration
The build system looks for bootstrap.toml in the current directory, or you can specify a custom file with --config.
See bootstrap.example.toml in the repository root for a complete reference with all available options and their default values.

​
Configuration Profiles

Profiles provide pre-configured defaults optimized for different use cases:
Optimized for contributing to the standard library:
profile = "library"
  • Downloads pre-built compiler
  • Fast iteration on library code
  • Minimal build times

​
LLVM Configuration

LLVM is the most time-consuming part of the build. Optimize it carefully:
If you need to build LLVM (e.g., for local LLVM changes):
[llvm]
download-ci-llvm = false

# Use Ninja (much faster than Make)
ninja = true

# Optimize LLVM
optimize = true

# Enable assertions for better error messages
assertions = false

# Select targets (reduces build time)
targets = "X86;ARM;AArch64"

# Link LLVM dynamically (faster linking)
link-shared = true
Building LLVM requires significant time (1-3 hours) and disk space (10+ GB).
Use LLVM installed on your system:
[target.x86_64-unknown-linux-gnu]
llvm-config = "/usr/bin/llvm-config"
Verify it’s a Rust-patched version or set:
llvm-has-rust-patches = false

[llvm]
# ThinLTO for LLVM itself (requires clang)
thin-lto = true

# Enable specific experimental targets
experimental-targets = "AVR;M68k"

# Limit parallel linker invocations (saves memory)
link-jobs = 2

# Include debug info in release builds
release-debuginfo = false

# Enable LLVM tests (for LLVM development)
tests = false

# Use zstd compression
libzstd = true

# Custom compiler flags
cflags = "-march=native"
cxxflags = "-march=native"
ldflags = ""

# Use libc++ instead of libstdc++
use-libcxx = false

# Specify linker for LLVM
use-linker = "/usr/bin/lld"

​
Build Options

Control the build process: 
[build]
# Build triple (auto-detected by default)
build = "x86_64-unknown-linux-gnu"

# Host triples (platforms to build a compiler for)
host = ["x86_64-unknown-linux-gnu"]

# Target triples (platforms to build libraries for)
target = [
  "x86_64-unknown-linux-gnu",
  "aarch64-unknown-linux-gnu",
]

# Build directory
build-dir = "build"

# Parallel jobs (0 = number of CPUs)
jobs = 0

# Build extended tools
extended = true

# Specific tools to build
tools = [
  "cargo",
  "clippy",
  "rustdoc",
  "rustfmt",
  "rust-analyzer",
  "analysis",
  "src",
]

# Use vendored dependencies
vendor = false

# Locked dependencies (don't update Cargo.lock)
locked-deps = false

# Build documentation
docs = true

# Build compiler documentation
compiler-docs = false

# Manage git submodules automatically
submodules = true

# Print timing information
print-step-timings = true

# Use ccache
ccache = true
# Or specify path
# ccache = "/usr/bin/ccache"

# Low priority build (Unix: nice +10, Windows: low priority)
low-priority = false

# Enable metrics collection
metrics = false
For faster development builds, disable documentation and use ccache:
[build]
docs = false
compiler-docs = false
ccache = true

​
Rust Compiler Options

Configure how the Rust compiler itself is built: 
[rust]
# Optimization level (true = 3, false = 0, 1-3, "s", "z")
optimize = true

# Code generation units (higher = faster compile, slower runtime)
codegen-units = 16

# LTO for rustc ("thin-local", "thin", "fat", "off")
lto = "thin-local"

# Strip symbols
strip = false

​
Target-Specific Configuration

Configure settings for specific target triples: 
[target.x86_64-unknown-linux-gnu]
# C compiler
cc = "gcc"

# C++ compiler
cxx = "g++"

# Archiver
ar = "ar"

# Ranlib
ranlib = "ranlib"

# Linker
linker = "gcc"

# LLVM config
llvm-config = "/usr/bin/llvm-config"

# Additional rustflags for this target
rustflags = ["-Ctarget-cpu=native"]

# Static or dynamic CRT
crt-static = false

# Split debuginfo ("off", "unpacked", "packed")
split-debuginfo = "off"

# Build sanitizers for this target
sanitizers = true

# Build profiler for this target
profiler = true

# Enable rpath
rpath = true

# Test runner (for cross-compilation)
runner = "qemu-aarch64"

# Skip building std
no-std = false

# Musl root (for musl targets)
musl-root = "/usr/local/musl"

# WASI root (for WASM targets)
wasi-root = "/path/to/wasi-sdk"

​
Cross-Compilation Example

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

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

​
Installation Configuration

Configure where x.py install places files: 
[install]
# Installation prefix
prefix = "/usr/local"

# System configuration directory
sysconfdir = "/etc"

# Documentation directory
docdir = "share/doc/rust"

# Binary directory
bindir = "bin"

# Library directory
libdir = "lib"

# Man page directory
mandir = "share/man"

# Data directory
datadir = "share"

​
Distribution Options

For building release distributions: 
[dist]
# Sign artifacts
sign-folder = "/path/to/artifacts"

# Upload URL
upload-addr = "https://example.com/dist"

# Build source tarball
src-tarball = true

# Compression formats
compression-formats = ["gz", "xz"]

# Compression profile ("fast", "balanced", "best")
compression-profile = "fast"

# Include MinGW linker (Windows)
include-mingw-linker = true

# Vendor dependencies
vendor = true

​
Example Configurations

profile = "compiler"

[llvm]
download-ci-llvm = true

[build]
docs = false
compiler-docs = false
ccache = true
extended = false

[rust]
incremental = true
debug-assertions = true
debuginfo-level = 1

[build]
extended = true
tools = ["cargo", "clippy", "rustfmt", "rust-analyzer"]
docs = true

[llvm]
download-ci-llvm = false
optimize = true
thin-lto = true
link-shared = false

[rust]
channel = "stable"
optimize = true
debug-assertions = false
debuginfo-level = 0
lto = "thin"
codegen-units = 1

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

[llvm]
download-ci-llvm = true

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

[target.armv7-unknown-linux-gnueabihf]
linker = "arm-linux-gnueabihf-gcc"

[llvm]
download-ci-llvm = false
optimize = false
assertions = true
tests = true
ninja = true

# Only build needed targets
targets = "X86"

[rust]
debug-assertions = true
debuginfo-level = 2

​
Using the Configure Script

The ./configure script provides a command-line interface to generate bootstrap.toml: 
./configure --prefix=/opt/rust

​
Configuration Tips

For library development:
  • Use profile = "library"
  • Set llvm.download-ci-llvm = true
  • Set rust.download-rustc = "if-unchanged"
To reduce disk usage:
  • Set llvm.download-ci-llvm = true
  • Run git submodule deinit src/llvm-project
  • Set build.docs = false
To speed up builds:
  • Use llvm.ninja = true
  • Enable build.ccache = true
  • Set build.docs = false
  • Use llvm.download-ci-llvm = true
  • Enable rust.incremental = true
To reduce memory usage:
  • Set build.jobs = 1 or a low number
  • Set llvm.link-jobs = 1
  • Use llvm.download-ci-llvm = true

​
Next Steps

Build on Unix

Start building on Unix systems

Build on Windows

Start building on Windows

Rustc Dev Guide

Deep dive into compiler development

Build docs developers (and LLMs) love

Get started for freeTalk to us