Building on Unix-Like Systems

Quick Start

For experienced developers who want to get started quickly:

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

For a detailed explanation and configuration options, continue reading below.

Prerequisites

Before building, ensure you have all required dependencies installed.

Step-by-Step Build Process

Clone the Repository

Clone the Rust source code from GitHub:

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

The repository is large (several GB), so cloning may take some time.

For faster cloning, use a shallow clone:

git clone --depth 1 https://github.com/rust-lang/rust.git

However, this is not recommended if you plan to contribute.

Configure the Build

Choose one of the following configuration methods:

Interactive Setup (Recommended)
Configure Script
Manual Configuration

Run the interactive setup to configure your build profile:

./x.py setup

You’ll be prompted to select a profile:

library - For contributing to the standard library
compiler - For contributing to the compiler
codegen - For contributing to code generation
tools - For contributing to tools like Clippy or rustfmt
user - For general usage and experimentation

The setup will also configure:

LSP (Language Server Protocol) with rust-analyzer
Git hooks for commit validation
Editor integration

Use the configure script for programmatic configuration:

./configure \
  --enable-full-tools \
  --enable-profiler \
  --enable-sanitizers \
  --set llvm.download-ci-llvm=true

This generates a bootstrap.toml file with your settings.

Create bootstrap.toml manually:

bootstrap.toml

[build]
# Use all CPU cores
jobs = 0

# Build extended tools
extended = true
tools = ["cargo", "clippy", "rustfmt", "rust-analyzer"]

[llvm]
# Download LLVM instead of building (much faster)
download-ci-llvm = "if-unchanged"

[rust]
# Development channel
channel = "dev"

# Enable debug assertions for better error messages
debug-assertions = true

Build the Compiler

Build Rust using the x.py script:

Standard Build
Stage 2 Build
Specific Components
Parallel Build

./x.py build

This builds:

The stage 1 compiler
The standard library
Core tools (if extended = true)

First-time builds can take 30 minutes to several hours depending on your hardware and whether you’re downloading or building LLVM.

./x.py build --stage 2

Builds the final, fully optimized compiler. This is slower but produces a production-ready compiler.

# Build only the standard library
./x.py build library/std

# Build the compiler
./x.py build compiler

# Build a specific tool
./x.py build tools/cargo

# Use specific number of jobs
./x.py build -j 4

# Use all available cores (default)
./x.py build -j 0

Install (Optional)

Install the built compiler to your system:

./x.py install

By default, this installs to /usr/local. Customize the installation directory:

Using DESTDIR
Using Configure
Using bootstrap.toml

export DESTDIR=/path/to/install
./x.py install

./configure \
  --set install.prefix=/opt/rust \
  --set install.sysconfdir=/opt/rust/etc
./x.py install

bootstrap.toml

[install]
prefix = "/opt/rust"
sysconfdir = "/opt/rust/etc"
bindir = "bin"
libdir = "lib"

Then run:

./x.py install

The installation includes:

rustc - The Rust compiler
rustdoc - Documentation generator
cargo - Package manager (if extended = true)
Additional tools based on your configuration

When DESTDIR is set, the prefix and sysconfdir values are combined with the DESTDIR path.

Advanced Configuration Examples

Cross-Compilation Setup

Example configuration for cross-compiling to ARM64 Linux:

./configure \
  --build=x86_64-unknown-linux-gnu \
  --target=aarch64-unknown-linux-gnu \
  --set target.aarch64-unknown-linux-gnu.linker=aarch64-linux-gnu-gcc

Or in bootstrap.toml:

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

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

Optimized Development Build

Configuration optimized for fast rebuilds during development:

bootstrap.toml

[llvm]
download-ci-llvm = true

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

[build]
# Use ccache for faster rebuilds
ccache = true

# Don't build documentation
docs = false

Production Release Build

Configuration for building a production release:

./configure \
  --enable-full-tools \
  --enable-profiler \
  --enable-sanitizers \
  --enable-compiler-docs \
  --set rust.debug-assertions=false \
  --set rust.debuginfo-level=0 \
  --set rust.codegen-units=1 \
  --set llvm.thin-lto=true

Custom LLVM Build

Building with custom LLVM settings:

bootstrap.toml

[llvm]
# Build LLVM from source
download-ci-llvm = false

# Use Ninja for faster builds
ninja = true

# Enable ThinLTO for LLVM
thin-lto = true

# Link LLVM dynamically
link-shared = true

# Enable specific targets
targets = "X86;ARM;AArch64"

# Optimize LLVM build
optimize = true
release-debuginfo = false

Using Configure and Make

For those familiar with traditional Unix build systems:

./configure --prefix=/usr/local
make && sudo make install

The Makefile is a wrapper around x.py. We recommend using x.py directly for better control and error messages.

Testing Your Build

After building, verify everything works:

./x.py check

Building Documentation

Build the Rust documentation:

# Build all documentation
./x.py doc

# Build standard library docs
./x.py doc library/std

# Build compiler docs
./x.py doc compiler

Documentation is generated in build/<target>/doc directory.

Troubleshooting

Build Fails: Out of Memory

LLVM compilation is memory-intensive. Solutions:

Use pre-built LLVM:

[llvm]
download-ci-llvm = true

Reduce parallel jobs:

./x.py build -j 1

Limit linker jobs:

[llvm]
link-jobs = 1

Build is Very Slow

Speed up builds:

Download LLVM instead of building
Use Ninja instead of Make for LLVM
Enable ccache
Disable documentation builds
Use incremental compilation

bootstrap.toml

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

[build]
ccache = true
docs = false

[rust]
incremental = true

Submodule Errors

Update git submodules:

git submodule update --init --recursive

Or let bootstrap manage them:

[build]
submodules = true

Getting Started

Building from Source

Architecture

Compiler

Standard Library

Tooling

Building on Unix-Like Systems

Quick Start

Prerequisites

Step-by-Step Build Process

Advanced Configuration Examples

Using Configure and Make

Testing Your Build

Building Documentation

Troubleshooting

Next Steps

Configuration Options

Rustc Dev Guide

Build docs developers (and LLMs) love

Getting Started

Building from Source

Architecture

Compiler

Standard Library

Tooling

​Quick Start

​Prerequisites

​Step-by-Step Build Process

​Advanced Configuration Examples

​Using Configure and Make

​Testing Your Build

​Building Documentation

​Troubleshooting

​Next Steps

Configuration Options

Rustc Dev Guide

Build docs developers (and LLMs) love

Quick Start

Prerequisites

Step-by-Step Build Process

Advanced Configuration Examples

Using Configure and Make

Testing Your Build

Building Documentation

Troubleshooting

Next Steps