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:
| Tool | What it is | C++ equivalent |
|---|---|---|
rustc | The compiler | clang++, g++, cl.exe |
cargo | Build system, package manager, test runner | CMake + vcpkg/Conan + CTest |
rustup | Installs and switches toolchains and targets | Installing several compilers side by side |
rustfmt / cargo fmt | Formatter | clang-format |
clippy / cargo clippy | Linter | clang-tidy |
rustdoc / cargo doc | Documentation generator | Doxygen |
rust-analyzer | Language server for editors | clangd |
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:
| Triple | Architecture | Vendor | OS | Environment / ABI |
|---|---|---|---|---|
x86_64-pc-windows-msvc | x86_64 | pc | windows | msvc (links with MSVC, MSVC C++ ABI) |
x86_64-pc-windows-gnu | x86_64 | pc | windows | gnu (MinGW) |
x86_64-unknown-linux-gnu | x86_64 | unknown | linux | gnu (glibc) |
aarch64-apple-darwin | aarch64 (ARM64) | apple | darwin (macOS) | |
aarch64-apple-ios | aarch64 | apple | ios | |
aarch64-linux-android | aarch64 | (omitted) | linux | android (Bionic libc, Android ABI) |
wasm32-unknown-unknown | wasm32 | unknown | unknown (no OS: the browser) | |
thumbv7em-none-eabihf | Thumb-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.
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-gdbandrust-lldbare wrappers that add pretty-printers forVec,String,Optionand 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-clientcrate).
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:
| Command | What it does |
|---|---|
cargo build | Debug build into target/debug/ |
cargo build --release | Optimized build into target/release/ |
cargo run / cargo run --release | Build and run |
cargo check | Type-check only, no code generation (much faster) |
cargo test | Build and run all tests |
cargo fmt | Format the whole project |
cargo clippy | Lint |
cargo doc --open | Build API docs for your crate and all dependencies |
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
- Install Rust, create a project with
cargo new, and run it in debug and release mode. Find both binaries undertarget/. - Set a breakpoint on the
println!line in your debugger of choice and step into it. What do you see? - Run
cargo build -vand read therustccommand line Cargo runs. Compare it with what CMake passes to your C++ compiler.