Configuration Options Reference

Overview

The Rust compiler build system is configured through bootstrap.toml (or config.toml for backward compatibility). This file controls all aspects of the build process, from compiler optimization levels to LLVM configuration.

Configuration Files

bootstrap.toml

Primary configuration file (recommended)

config.toml

Legacy configuration file (still supported)

bootstrap.example.toml

Example with all available options

Profiles

Pre-configured defaults in src/bootstrap/defaults/

Getting Started

# Recommended: Interactive configuration
./x.py setup

# Select a profile when prompted

Global Settings

profile

Use different pre-set defaults than the global defaults.

profile = "compiler"  # or "library", "tools", "dist"

profile

string

Available profiles: compiler, library, tools, distSee src/bootstrap/defaults/ for profile definitions.

include

Inherit configuration from other TOML files.

include = ["local-config.toml", "team-config.toml"]

include

string[]

Paths to additional configuration files. Later files override earlier ones.Supports absolute paths and relative paths (from current directory).

change-id

Track configuration version for change detection.

change-id = 131605

change-id

number

ID from src/bootstrap/src/utils/change_tracker.rsBootstrap warns when this doesn’t match the latest change ID. Set to "ignore" to suppress warnings.

LLVM Configuration

llvm.download-ci-llvm

boolean | string

default:"false"

Download pre-built LLVM from CI instead of building locally.

true - Always download if available
false - Never download, always build
"if-unchanged" - Download only if llvm-project is unchanged

[llvm]
download-ci-llvm = true

This is the most significant build time optimization. Downloading takes ~5 minutes vs. 30-60 minutes to build.

llvm.optimize

boolean

default:"true"

Build LLVM in Release mode vs. Debug mode.

[llvm]
optimize = true

llvm.thin-lto

boolean

default:"false"

Build LLVM with ThinLTO enabled.Requires clang, lld, llvm-ar, and llvm-ranlib in your toolchain.

[llvm]
thin-lto = false

llvm.assertions

boolean

default:"false"

Enable LLVM assertions.

When disabled, bugs in rustc/LLVM integration can cause unsoundness (segfaults) in rustc itself.

[llvm]
assertions = false

llvm.tests

boolean

default:"false"

Enable LLVM test suite in the build.Tests aren’t run automatically - use ninja check-llvm in LLVM build dir.

llvm.enzyme

boolean

default:"false"

Build Enzyme as AutoDiff backend.

llvm.ninja

boolean

default:"true"

Use Ninja to build LLVM (much faster than make).

llvm.targets

string

default:"AArch64;AMDGPU;ARM;..."

Semicolon-separated list of LLVM targets to build support for.Turning targets off will make rustc unable to compile for those architectures.

[llvm]
targets = "AArch64;AMDGPU;ARM;BPF;Hexagon;LoongArch;MSP430;Mips;NVPTX;PowerPC;RISCV;Sparc;SystemZ;WebAssembly;X86"

llvm.experimental-targets

string

default:"AVR;M68k;CSKY"

Experimental LLVM targets (not built by default).

llvm.link-jobs

number

default:"0"

Cap parallel linker invocations when compiling LLVM.Useful when building with debug info. 0 = unlimited.

Build Configuration

build.build

string

Build triple for the pre-compiled snapshot compiler.Defaults to output of rustc --version --verbose or platform detection.

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

build.host

string[]

default:"[build.build]"

Host triples to build a compiler toolchain for.These are machines that will RUN the compiler.

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

build.target

string[]

default:"build.host"

Target triples to build libraries for.These are machines the compiler will CROSS-COMPILE to.

[build]
target = [
  "x86_64-unknown-linux-gnu",
  "wasm32-wasip1",
  "aarch64-apple-darwin"
]

build.build-dir

string

default:"build"

Directory to store build artifacts.Paths are relative to the repository root.

[build]
build-dir = "build"

build.cargo / build.rustc

build.cargo

path

Path to cargo binary to use instead of downloading stage0.

build.rustc

path

Path to rustc binary to use instead of downloading stage0.

[build]
cargo = "/usr/local/bin/cargo"
rustc = "/usr/local/bin/rustc"

If you set rustc, you should also set cargo to use a matching toolchain.

build.docs

boolean

default:"true"

Whether to build documentation by default.You can still build docs with ./x.py doc library/std when this is false.

build.docs-minification

boolean

default:"true"

Minify CSS, JavaScript, and HTML in generated docs.

build.compiler-docs

boolean

default:"false"

Build compiler documentation by default.

build.library-docs-private-items

boolean

default:"false"

Include private items in library documentation.

build.submodules

boolean

default:"true"

Automatically manage and update git submodules.

build.verbose

number

default:"0"

Verbosity level:

0 - Not verbose
1 - Verbose
2 - Very verbose
3 - Print environment variables on each rustc invocation

[build]
verbose = 1

build.extended

boolean

default:"false"

Build extended Rust tool set (Cargo, rustfmt, clippy, etc.).

[build]
extended = true

build.tools

string[]

Tools to include in installation when extended = true.

[build]
tools = [
  "cargo",
  "clippy",
  "rustdoc",
  "rustfmt",
  "rust-analyzer",
  "rust-analyzer-proc-macro-srv",
  "analysis",
  "src"
]

build.sanitizers

boolean

default:"false"

Build sanitizer runtimes (AddressSanitizer, ThreadSanitizer, etc.).

build.profiler

boolean

default:"false"

Build profiler runtime (required for -C profile-generate and -C instrument-coverage).

build.full-bootstrap

boolean

default:"false"

Perform full bootstrap without uplifting artifacts.Useful for verifying reproducible builds.

build.locked-deps

boolean

default:"false"

Force Cargo to check that Cargo.lock is up-to-date.

build.vendor

boolean

Use vendored sources for Rust dependencies.Auto-detected for tarball sources.

build.jobs

number

default:"0"

Number of parallel jobs. 0 = number of CPU cores.

[build]
jobs = 8

Stage Defaults

build.build-stage

number

default:"1"

Default stage for build subcommand.

build.test-stage

number

default:"1"

Default stage for test subcommand.

build.doc-stage

number

default:"0"

Default stage for doc subcommand.

build.dist-stage

number

default:"2"

Default stage for dist subcommand.

build.install-stage

number

default:"2"

Default stage for install subcommand.

build.bench-stage

number

default:"2"

Default stage for bench subcommand.

[build]
build-stage = 2
test-stage = 1
doc-stage = 0

Rust Compilation Options

rust.optimize

boolean | number | string

default:"true"

Optimization level for compiler and standard library:

true or 3 - All optimizations
false or 0 - No optimizations (NOT SUPPORTED)
1 - Basic optimizations
2 - Some optimizations
"s" - Optimize for binary size
"z" - Optimize for size, disable loop vectorization

[rust]
optimize = true

Building with optimize = false is NOT SUPPORTED and will cause build failures or extreme slowness.

rust.debug

boolean

default:"false"

Configure build for debugging Rust.Enables debug assertions and other debug-only features.

[rust]
debug = false

rust.debug-assertions

boolean

Enable debug assertions in compiler and standard library.Defaults to rust.debug value.

rust.debug-assertions-std

boolean

Enable debug assertions specifically in standard library.Overrides debug-assertions.

rust.overflow-checks

boolean

Enable overflow checks in compiler and standard library.Defaults to rust.debug value.

rust.debuginfo-level

number

default:"0 or 1"

Debuginfo level (corresponds to -C debuginfo=N):

0 - No debug info
1 - Line tables only
2 - Full debug info (generates gigabytes, slows linking)

Defaults to 1 if rust.debug = true, otherwise 0.

[rust]
debuginfo-level = 1

rust.debuginfo-level-rustc / std / tools / tests

rust.debuginfo-level-rustc

number

Debuginfo level for the compiler.

rust.debuginfo-level-std

number

Debuginfo level for the standard library.

rust.debuginfo-level-tools

number

Debuginfo level for tools.

rust.debuginfo-level-tests

number

default:"0"

Debuginfo level for compiletest tests.

rust.incremental

boolean

default:"false"

Use incremental compilation when building rustc.

[rust]
incremental = true

rust.channel

string

default:"dev"

Release channel: stable, beta, nightly, dev, or auto-detect.Stable/beta only allow stable features. Nightly/dev allow unstable features.

[rust]
channel = "nightly"

rust.download-rustc

boolean | string

default:"false"

Download stage 1 and 2 compilers from CI:

true - Always download
false - Never download
"if-unchanged" - Download if compiler hasn’t changed

Useful for tool/library development.

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

rust.codegen-backends

string[]

default:"[\"llvm\"]"

Codegen backends to build and include in sysroot.Available: llvm, cranelift, gcc

[rust]
codegen-backends = ["llvm", "cranelift"]

rust.lld

boolean

default:"false"

Compile and make LLD available in sysroot.

rust.llvm-tools

boolean

default:"true"

Make LLVM tools available in sysroot (llvm-objdump, llvm-nm, etc.).

rust.deny-warnings

boolean

default:"true"

Deny warnings when compiling rustc and libraries.

rust.backtrace-on-ice

boolean

default:"false"

Print backtrace on internal compiler errors during bootstrap.

rust.rpath

boolean

default:"true"

Build rustc with rpath enabled.Makes rustc usable directly from build directory.

rust.jemalloc

boolean

default:"false"

Link compiler against jemalloc instead of system allocator.Only tested on Linux and macOS.

rust.lto

string

default:"thin-local"

LTO mode for rustc compilation:

"thin-local" - Thin LTO within single crate
"thin" - Thin LTO across crates
"fat" - Fat LTO
"off" - No LTO

[rust]
lto = "thin"

Installation Options

install.prefix

path

default:"/usr/local"

Installation prefix (must be absolute path).

[install]
prefix = "/usr/local"

install.sysconfdir

path

default:"/etc"

System configuration directory.

install.docdir

path

default:"share/doc/rust"

Documentation installation directory (relative to prefix).

install.bindir

path

default:"bin"

Binary installation directory (relative to prefix).

install.libdir

path

default:"lib"

Library installation directory (relative to prefix).

install.mandir

path

default:"share/man"

Man page installation directory (relative to prefix).

Target-Specific Options

Configure options for specific target triples:

[target.x86_64-unknown-linux-gnu]
cc = "clang"
cxx = "clang++"
linker = "clang"
ar = "llvm-ar"
ranlib = "llvm-ranlib"

[target.wasm32-wasip1]
wasi-root = "/path/to/wasi-sdk"

Compiler Toolchain

target.<triple>.cc

path

default:"cc"

C compiler for this target.

target.<triple>.cxx

path

default:"c++"

C++ compiler for this target (host targets only).

target.<triple>.ar

path

default:"ar"

Archiver for this target.

target.<triple>.ranlib

path

default:"ranlib"

Ranlib for this target.

target.<triple>.linker

path

default:"cc"

Linker for bootstrapping Rust code.

Target Configuration

target.<triple>.llvm-config

path

Path to llvm-config for custom LLVM installation.When specified, LLVM won’t be built for this target.

target.<triple>.llvm-filecheck

path

Path to LLVM FileCheck utility.

target.<triple>.llvm-libunwind

string

default:"no"

LLVM libunwind configuration:

"no" - Link to libgcc_s.so
"in-tree" - Static link to in-tree llvm-libunwind
"system" - Link to system libunwind

target.<triple>.musl-root

path

Root of musl installation for musl targets.

target.<triple>.wasi-root

path

Root of WASI SDK for wasm32-wasip1 targets.

target.<triple>.qemu-rootfs

path

QEMU rootfs location for testing.

target.<triple>.no-std

boolean

Skip building std library for this target.Auto-enabled for *-none-*, nvptx*, and *-uefi targets.

target.<triple>.sanitizers

boolean

Build sanitizer runtimes for this target.

target.<triple>.profiler

boolean | path

Build profiler runtime for this target, or use existing one at path.

target.<triple>.rpath

boolean

Enable rpath for this target.

target.<triple>.crt-static

boolean

Force static/dynamic linkage of standard library.

target.<triple>.runner

string

Test runner for compiletest (e.g., QEMU, wasmtime).

Distribution Options

dist.sign-folder

path

Folder containing artifacts to sign with GPG.

dist.upload-addr

url

Remote address for artifact uploads.

dist.compression-formats

string[]

default:"[\"gz\", \"xz\"]"

Compression formats for dist tarballs.

[dist]
compression-formats = ["gz", "xz"]

dist.compression-profile

string

default:"fast"

Compression profile: fast, balanced, or best.

Example Configurations

profile = "compiler"

[llvm]
download-ci-llvm = true
assertions = true

[build]
verbose = 1
build-stage = 1

[rust]
debug = false
incremental = true

Bootstrap System

Learn about bootstrap architecture

x.py Reference

Explore x.py commands

Compiler Internals

Build System

Resources

​Overview

​Configuration Files

bootstrap.toml

config.toml

bootstrap.example.toml

Profiles

​Getting Started

​Global Settings

​profile

​include

​change-id

​LLVM Configuration

​llvm.download-ci-llvm

​llvm.optimize

​llvm.thin-lto

​llvm.assertions

​llvm.tests

​llvm.enzyme

​llvm.ninja

​llvm.targets

​llvm.experimental-targets

​llvm.link-jobs

​Build Configuration

​build.build

​build.host

​build.target

​build.build-dir

​build.cargo / build.rustc

​build.docs

​build.docs-minification

​build.compiler-docs

​build.library-docs-private-items

​build.submodules

​build.verbose

​build.extended

​build.tools

​build.sanitizers

​build.profiler

​build.full-bootstrap

​build.locked-deps

​build.vendor

​build.jobs

​Stage Defaults

​Rust Compilation Options

​rust.optimize

​rust.debug

​rust.debug-assertions

​rust.debug-assertions-std

​rust.overflow-checks

​rust.debuginfo-level

​rust.debuginfo-level-rustc / std / tools / tests

​rust.incremental

​rust.channel

​rust.download-rustc

​rust.codegen-backends

​rust.lld

​rust.llvm-tools

​rust.deny-warnings

​rust.backtrace-on-ice

​rust.rpath

​rust.jemalloc

​rust.lto

​Installation Options

​install.prefix

​install.sysconfdir

​install.docdir

​install.bindir

​install.libdir

​install.mandir

​Target-Specific Options

​Compiler Toolchain

​Target Configuration

​Distribution Options

​dist.sign-folder

​dist.upload-addr

​dist.compression-formats

​dist.compression-profile

Overview

Configuration Files

Getting Started

Global Settings

profile

include

change-id

LLVM Configuration

llvm.download-ci-llvm

llvm.optimize

llvm.thin-lto

llvm.assertions

llvm.tests

llvm.enzyme

llvm.ninja

llvm.targets

llvm.experimental-targets

llvm.link-jobs

Build Configuration

build.build

build.host

build.target

build.build-dir

build.cargo / build.rustc

build.docs

build.docs-minification

build.compiler-docs

build.library-docs-private-items

build.submodules

build.verbose

build.extended

build.tools

build.sanitizers

build.profiler

build.full-bootstrap

build.locked-deps

build.vendor

build.jobs

Stage Defaults

Rust Compilation Options

rust.optimize

rust.debug

rust.debug-assertions

rust.debug-assertions-std

rust.overflow-checks

rust.debuginfo-level

rust.debuginfo-level-rustc / std / tools / tests

rust.incremental

rust.channel

rust.download-rustc

rust.codegen-backends

rust.lld

rust.llvm-tools

rust.deny-warnings

rust.backtrace-on-ice

rust.rpath

rust.jemalloc

rust.lto

Installation Options

install.prefix

install.sysconfdir

install.docdir

install.bindir

install.libdir

install.mandir

Target-Specific Options

Compiler Toolchain

Target Configuration

Distribution Options

dist.sign-folder

dist.upload-addr

dist.compression-formats

dist.compression-profile

Example Configurations

Related Documentation