Development Setup

This document describes building Rust from source. This is not recommended if you don’t know what you’re doing. If you just want to install Rust, check out the official installation guide.

Prerequisites

Before you begin, ensure you have the necessary tools installed on your system.

Core Dependencies

All platforms require these basic tools:

Python 3

Python 3 (or Python 2.7 as a fallback) is required to run the build system

python3 --version

Git

Version control to clone the repository

git --version

C Compiler

When building for the host, cc is sufficient. Cross-compiling may need additional compilers

Additional Tools (Unix)

curl (not needed on Windows)
pkg-config (Linux only, when targeting Linux)
libiconv (included with glibc on Debian-based distros)

Cargo Dependencies

To build Cargo, you’ll also need OpenSSL:

Debian/Ubuntu: libssl-dev
Fedora/RHEL: openssl-devel
macOS: Included by default

LLVM Build Tools (Optional)

If building LLVM from source, you’ll need additional tools. However, using pre-built LLVM is recommended for most contributors.

Required tools if building LLVM from source:

C++ Compiler: g++, clang++, or MSVC (see LLVM requirements)
Build System: ninja (recommended, especially on Windows) or GNU make 3.81+
CMake: Version per LLVM documentation
Linux Only: libstdc++-static (Fedora, Ubuntu)

On tier 1 or tier 2 platforms with host tools, you can download pre-built LLVM by setting llvm.download-ci-llvm = true in your config. This significantly speeds up build times.

Platform-Specific Setup

Unix-like (Linux/macOS)
Windows (MSVC)
Windows (MinGW)

Clone the Repository

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

Configure the Build

The interactive setup is recommended for new contributors:

./x.py setup

This will guide you through:

Selecting a config profile (user, compiler, library, etc.)
Setting up LSP for your editor
Configuring Git hooks
Other development preferences

Advanced: Using the configure script

For complex configurations, use the configure script:

./configure --build=x86_64-unknown-linux-gnu \
  --enable-full-tools \
  --enable-profiler \
  --enable-sanitizers \
  --set llvm.download-ci-llvm=true \
  --set rust.debug-assertions=true

This generates a bootstrap.toml file with your settings.

Build and Install

./x.py build && ./x.py install

When complete, ./x.py install will place several programs into $PREFIX/bin:

rustc: The Rust compiler
rustdoc: The API documentation tool
cargo: The package manager (unless disabled with --set build.extended=false)

Install Dependencies

Using winget:

winget install -e Python.Python.3
winget install -e Kitware.CMake
winget install -e Git.Git

Add C:\Program Files\CMake\bin to your system PATH.

Install Visual Studio

MSVC builds require:

Visual Studio 2022 (or later) build tools
C++ build tools package
Recent Windows 10 or 11 SDK

Download Visual Studio and check “C++ build tools” during installation.

Be careful that “C++ CMake tools for Windows” doesn’t get included under “Individual components” if installing CMake separately.

Build the Compiler

In cmd.exe:

python x.py setup user
python x.py build

Troubleshooting: Visual Studio version issues

If you have multiple Visual Studio versions and the build system doesn’t understand your version, manually call the appropriate vcvars file:

CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
python x.py build

Install MSYS2

Download MSYS2

Get the latest MSYS2 installer and run through the installation

Install Git for Windows

Download Git for Windows and ensure it’s in your PATHEdit the relevant mingw[32|64].ini file in your MSYS2 installation directory and uncomment:

MSYS2_PATH_TYPE=inherit

Start MINGW Shell

Launch MINGW64 or MINGW32 shell from your start menu or by running mingw64.exe/mingw32.exe

Install Build Tools

# Update package mirrors
pacman -Sy pacman-mirrors

# Install build tools (replace x86_64 with i686 for 32-bit)
pacman -S make \
            diffutils \
            tar \
            mingw-w64-x86_64-python \
            mingw-w64-x86_64-cmake \
            mingw-w64-x86_64-gcc \
            mingw-w64-x86_64-ninja

Do not use the python2, cmake, and ninja packages from the msys2 subsystem. The build has historically been known to fail with these packages.

Build Rust

cd /path/to/rust
python x.py setup dist && python x.py build && python x.py install

Using Git for Windows is often much faster than MSYS2’s git. Turning off real-time protection in Windows Virus & Threat Protection settings can also help with long run times.

The Build System: x.py

The Rust build system uses a Python script called x.py to build the compiler and manage the bootstrapping process.

Basic Usage

./x.py <subcommand> [flags]

Common subcommands:

./x.py build

Configuration Files

The build system looks for bootstrap.toml in the project root. You can also specify a custom config:

./x.py build --config path/to/custom-config.toml

See bootstrap.example.toml for a full list of configuration options with detailed comments.

Common Build Profiles

The ./x.py setup command offers several profiles:

Profile	Description	Use Case
user	Basic profile for trying out changes	Casual contributors
compiler	Optimized for compiler development	Working on rustc
library	Optimized for std library work	Standard library development
dist	Full build with all tools	Creating distributions

Building Documentation

To build the documentation:

./x.py doc

The generated documentation will appear under doc in the build directory for your target ABI. For example, if the ABI is x86_64-pc-windows-msvc, the directory will be build/x86_64-pc-windows-msvc/doc.

Specifying Build Targets

You can specify the target triple using:

./x.py build --build=<triple>

Or by configuring in bootstrap.toml:

./configure --set build.build=<triple>

Available Windows Build Triples

GNU ABI (using GCC):

i686-pc-windows-gnu
x86_64-pc-windows-gnu

MSVC ABI:

i686-pc-windows-msvc
x86_64-pc-windows-msvc

Bootstrap Process

Since the Rust compiler is written in Rust, it must be built by a precompiled “snapshot” version of itself (made in an earlier stage of development). As such, source builds require an Internet connection to fetch snapshots.

Only “host tools” platforms have a pre-compiled snapshot binary available. To compile for a platform without host tools, you must cross-compile. See the platform support documentation for a list of supported platforms.

Optimizing Build Times

Use CI LLVM

Set llvm.download-ci-llvm = true to download pre-built LLVM instead of building it

Reduce Debuginfo

Set rust.debuginfo-level = 1 for faster builds with basic debugging capability

Use Incremental

Set rust.incremental = true to enable incremental compilation

Limit Codegen Units

Set rust.codegen-units = 0 to use the default (faster builds, slower runtime)

Next Steps

Learn the Workflow

Now that your environment is set up, learn how to make contributions and submit changes

Contributing Guide

Development

Development Setup

Prerequisites

Core Dependencies

Cargo Dependencies

LLVM Build Tools (Optional)

Platform-Specific Setup

Clone the Repository

Configure the Build

Build and Install

Install Dependencies

Install Visual Studio

Build the Compiler

Install MSYS2

The Build System: x.py

Basic Usage

Configuration Files

Common Build Profiles

Building Documentation

Specifying Build Targets

Available Windows Build Triples

Bootstrap Process

Optimizing Build Times

Use CI LLVM

Reduce Debuginfo

Use Incremental

Limit Codegen Units

Next Steps

Learn the Workflow

Build docs developers (and LLMs) love

Contributing Guide

Development

​Prerequisites

​Core Dependencies

​Cargo Dependencies

​LLVM Build Tools (Optional)

​Platform-Specific Setup

​Clone the Repository

​Configure the Build

​Build and Install

​Install Dependencies

​Install Visual Studio

​Build the Compiler

​Install MSYS2

​The Build System: x.py

​Basic Usage

​Configuration Files

​Common Build Profiles

​Building Documentation

​Specifying Build Targets

​Available Windows Build Triples

​Bootstrap Process

​Optimizing Build Times

Use CI LLVM

Reduce Debuginfo

Use Incremental

Limit Codegen Units

​Next Steps

Learn the Workflow

Build docs developers (and LLMs) love

Prerequisites

Core Dependencies

Cargo Dependencies

LLVM Build Tools (Optional)

Platform-Specific Setup

Clone the Repository

Configure the Build

Build and Install

Install Dependencies

Install Visual Studio

Build the Compiler

Install MSYS2

The Build System: x.py

Basic Usage

Configuration Files

Common Build Profiles

Building Documentation

Specifying Build Targets

Available Windows Build Triples

Bootstrap Process

Optimizing Build Times

Next Steps