Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Toolchain setup

A C++ toolchain is something you assemble: a compiler (or three), a build system, a package manager, a debugger, a formatter, a linter and a test framework, each from a different vendor. Rust ships almost all of that as one install. This chapter gets it onto your machine and maps each piece to what you already use.

Installing with rustup

Install Rust with rustup, the official toolchain manager. On Linux and macOS:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, download and run rustup-init.exe from the same site. Rust on Windows uses the MSVC linker and Windows SDK by default, so install the "Desktop development with C++" workload of Visual Studio (or the Build Tools) first. You almost certainly have it already.

rustup installs into your home directory (~/.cargo and ~/.rustup) and puts these on your PATH:

ToolWhat it isC++ equivalent
rustcThe compilerclang++, g++, cl.exe
cargoBuild system, package manager, test runnerCMake + vcpkg/Conan + CTest
rustupInstalls and switches toolchains and targetsInstalling several compilers side by side
rustfmt / cargo fmtFormatterclang-format
clippy / cargo clippyLinterclang-tidy
rustdoc / cargo docDocumentation generatorDoxygen
rust-analyzerLanguage server for editorsclangd

Toolchains and targets

Rust releases a new stable compiler every six weeks, and new releases are backward compatible: code that compiles today keeps compiling. There is no reason to stay on an old compiler the way C++ projects often must.

rustup update                 # move to the newest stable compiler
rustup toolchain install nightly
rustup default stable
rustc --version

A project can pin a toolchain by committing a rust-toolchain.toml file, the equivalent of pinning a compiler version in your CI images:

[toolchain]
channel = "1.91"
components = ["rustfmt", "clippy"]

Cross-compilation is built in. A target triple is the name of the platform you compile for. It is the same naming scheme Clang and GCC use (clang --target=aarch64-linux-android), inherited from LLVM and GNU autoconf. The general form is:

<architecture>-<vendor>-<operating system>-<environment/ABI>

Despite the name, it often has four parts, and a part that does not apply is either written as unknown/none or left out:

TripleArchitectureVendorOSEnvironment / ABI
x86_64-pc-windows-msvcx86_64pcwindowsmsvc (links with MSVC, MSVC C++ ABI)
x86_64-pc-windows-gnux86_64pcwindowsgnu (MinGW)
x86_64-unknown-linux-gnux86_64unknownlinuxgnu (glibc)
aarch64-apple-darwinaarch64 (ARM64)appledarwin (macOS)
aarch64-apple-iosaarch64appleios
aarch64-linux-androidaarch64(omitted)linuxandroid (Bionic libc, Android ABI)
wasm32-unknown-unknownwasm32unknownunknown (no OS: the browser)
thumbv7em-none-eabihfThumb-2 (Cortex-M4/M7)none (bare metal)eabihf (hardware float)

So aarch64-linux-android reads "64-bit ARM, Linux kernel, Android environment": the vendor field is simply dropped, as Android's own toolchain does. The last part matters more than it looks: windows-msvc and windows-gnu produce binaries that cannot link against each other's C++ libraries, exactly as with MSVC and MinGW builds in C++.

rustc -vV prints your host triple (the host: line), and rustc --print target-list lists every triple the compiler knows. To build for another one, install its standard library with rustup and pass --target:

rustup target add aarch64-linux-android wasm32-unknown-unknown x86_64-pc-windows-msvc
cargo build --target wasm32-unknown-unknown

The standard library for each target is downloaded prebuilt. You still need a linker for the target platform (the Android NDK, for example), just as in C++.

Editors

Install rust-analyzer. It provides completion, go-to-definition, inline type hints and the compiler's errors as you type.

  • VS Code: install the rust-analyzer extension. For debugging, add CodeLLDB (Linux/macOS) or use the C/C++ extension's debugger (Windows).
  • JetBrains: RustRover, or the Rust plugin for CLion.
  • Visual Studio: no first-class support; most Windows developers use VS Code or RustRover for Rust and keep Visual Studio for debugging mixed C++ and Rust.
  • Vim, Emacs, Helix, Zed: all speak the language server protocol.
Inline type hints

rust-analyzer shows the inferred type of every let binding in grey. Leave this on while you learn. Rust infers more than C++ auto does (types flow backward from later uses too), and the hints show you what the compiler decided.

Debuggers and profilers you already know

Rust compiles to native code with standard debug info (DWARF on Linux and macOS, PDB on Windows), so your existing tools work:

  • GDB and LLDB work directly. rust-gdb and rust-lldb are wrappers that add pretty-printers for Vec, String, Option and friends.
  • Visual Studio's debugger and WinDbg read the PDBs, with natvis visualizers for standard types.
  • RenderDoc, Nsight Graphics, PIX and Radeon GPU Profiler do not care what language issued the API calls.
  • perf, VTune, Superluminal, Tracy, Instruments all work. Tracy has a Rust client (the tracy-client crate).

Your first project

cargo new hello
cd hello
cargo run

cargo new creates:

hello/
├── Cargo.toml      # project manifest: name, version, dependencies
├── .gitignore
└── src/
    └── main.rs     # the binary's entry point

src/main.rs:

fn main() {
    println!("Hello, world!");
}

cargo run compiles in debug mode into target/debug/hello and runs it. The commands you will use every day:

CommandWhat it does
cargo buildDebug build into target/debug/
cargo build --releaseOptimized build into target/release/
cargo run / cargo run --releaseBuild and run
cargo checkType-check only, no code generation (much faster)
cargo testBuild and run all tests
cargo fmtFormat the whole project
cargo clippyLint
cargo doc --openBuild API docs for your crate and all dependencies
C++ habit to unlearn

Do not benchmark debug builds. Rust's debug builds are much slower than C++ -O0 builds in relative terms, because so much of Rust (iterators, Option, small methods) relies on inlining. For games, set opt-level = 1 for your own code in debug and opt-level = 3 for dependencies. The Cargo chapter shows how.

The Playground

For quick experiments you do not need a project at all. The Rust Playground compiles and runs code in the browser, can show assembly, LLVM IR and MIR, and has the 100 most popular crates available. Every runnable example in this book uses it.

Exercises

  1. Install Rust, create a project with cargo new, and run it in debug and release mode. Find both binaries under target/.
  2. Set a breakpoint on the println! line in your debugger of choice and step into it. What do you see?
  3. Run cargo build -v and read the rustc command line Cargo runs. Compare it with what CMake passes to your C++ compiler.