What Is This Thing?
A quick tour of Microsoft's open-source Rust training — seven books, seven on-ramps, one language.
The Big Picture
Imagine you want to learn Rust — a programming language that companies like Microsoft, Google, and Amazon use for their most demanding software. Where do you start?
If you search online, you will find hundreds of tutorials. Most of them assume you are starting from zero. But what if you already know Python, or C#, or C++? You do not need someone to explain what a variable is — you need someone to explain how Rust thinks differently from the language you already know.
That is exactly what Microsoft built. The RustTraining project is a collection of seven free training books, each designed for people coming from different programming backgrounds. Think of it like a music school with different departments: every department teaches the same instrument, but a guitarist learns differently from a pianist, even though they are both learning drums.
Three of the books are called Bridge books — they connect what you already know to Rust:
Ownership as an upgrade from manual memory management. If you think in pointers and malloc, this book speaks your language.
From garbage collection to ownership. Maps familiar .NET patterns — LINQ, async/await, generics — to their Rust equivalents.
From dynamic typing to static guarantees. Shows how Rust replaces duck typing with traits, and why that is a feature, not a limitation.
The Learning Paths
Beyond the three Bridge books, the project offers four more books that go deeper into specific areas of Rust. Here is the full lineup:
Bridge — 16 chapters mapping systems-level concepts to Rust's ownership model.
Bridge — 15 chapters connecting .NET patterns to Rust idioms.
Bridge — 15 chapters translating dynamic Python thinking into static Rust thinking.
Deep Dive — futures, Tokio, streams, and cancellation safety in 15 chapters.
Advanced — design patterns, idiomatic APIs, and architectural best practices.
Expert — encoding business rules in the type system so invalid states are unrepresentable.
Practices — CI/CD, testing strategies, project structure, and team workflows.
This project inverts traditional education. Instead of "learn everything, then build," it meets you where you are. Each Bridge book assumes you are already a competent programmer — it just shows you how Rust does things differently from the language you already think in.
What Makes These Books Special
These are not ordinary PDFs or blog posts. Every book is built with mdbook, a tool that turns plain Markdown files into interactive websites. Here are the four features that make them stand out:
Ownership graphs, async state machines, type hierarchies — all rendered as clean diagrams right inside the chapter, generated from simple text descriptions.
Every code example is editable. Change a line, click Run, and see the output instantly — no local Rust installation needed.
Each chapter ends with hands-on exercises that reinforce the concepts you just learned, giving you a chance to practice before moving on.
Need to find where traits are discussed? The built-in search indexes every chapter, so you can jump directly to the concept you need.
Here is how the playground feature is configured. This snippet comes from the book.toml file — the configuration file that controls how each book is built:
[output.html.playground]
editable = true
line-numbers = true
Check Your Understanding
Meet the Cast
The actors, stage crew, and director behind the scenes
The Cast of Characters
Every codebase has characters — pieces of software that each play a specific role. Let's meet the stars of this show.
The engine that transforms plain Markdown text files into beautiful, searchable book websites
The stage manager. A custom Rust program that orchestrates building all 7 books and serves them locally
The shipping container. Packages everything into a portable box that runs anywhere
The automation robot. Deploys the books to the web whenever code changes (CI/CD)
The Directory Map
Let's look at how the files are organized.
How They Work Together
When you run cargo xtask serve, here is what happens behind the scenes:
The Workspace Glue
The root Cargo.toml ties the whole project together. Let's read it line by line.
[workspace]
resolver = "2"
members = ["xtask"]This file defines a workspace — a way to group related Rust projects together under one roof
Use the modern dependency resolution strategy (version 2 is smarter about avoiding conflicts). The resolver handles all of that automatically.
The only actual Rust program in this workspace is xtask — the build tool that manages everything
The 7 books aren't Rust programs — they're Markdown text files. The only actual code is the xtask build tool that transforms them into websites.
Check Your Understanding
You want to change how code examples look in the books. Which actor handles that transformation?
You notice the landing page (the page listing all 7 books) looks broken. Where would you look to fix it?
What is the relationship between the 7 book folders and the xtask folder?
The Build Pipeline
How plain text becomes a beautiful website
From Text to Website
You have met the cast. Now let us watch them perform. When someone types cargo xtask build, a chain reaction begins.
Think of it like a printing press: raw manuscripts (Markdown files) go in, beautifully typeset books (HTML websites) come out. The press operator (xtask) feeds each manuscript through the press (mdbook) one by one, then arranges them all in a bookshop window (the landing page).
The Book Registry
How does xtask know which books to build? It uses a hardcoded constant called BOOKS — a list of every book in the project. Each entry stores four pieces of information: the folder name (slug), the human-readable title, a short description, and a category.
Here is what the first entry looks like:
const BOOKS: &[(&str, &str, &str, &str)] = &[
(
"c-cpp-book",
"Rust for C/C++ Programmers",
"Move semantics, RAII, FFI, embedded, no_std",
"bridge",
),
The Build Loop
Once xtask knows about every book, it loops through them one by one. For each book, it runs mdbook as an external Command — the same way you would type mdbook build in your terminal, but automated.
for &(slug, _, _, _) in BOOKS {
let book_dir = root.join(slug);
let dest = out.join(slug);
let status = Command::new("mdbook")
.args(["build", "--dest-dir"])
.arg(&dest)
.current_dir(&book_dir)
.status()
.expect("failed to run mdbook");
The Custom Web Server
After building the books, you need a way to preview them locally. Most projects reach for an existing tool — but xtask includes its own built-in HTTP server.
Most projects use existing tools like python -m http.server. But the xtask team built their own to add security features — like blocking hackers from reading files outside the website folder.
The custom server includes three layers of defense against path traversal attacks:
Blocks attempts to access files outside the site/ folder using tricks like ../../../etc/passwd
Rejects requests containing null bytes — a classic hacking technique that tricks programs into misreading file paths
Verifies that the final file path is actually inside the site folder, even if symlinks try to redirect elsewhere
Check Your Understanding
From Code to Cloud
How the books travel from source code to your browser
The Two Deployment Paths
The books are built. Now how do they reach readers? This project has two paths to the web — one automated, one containerized.
Free, automatic. Every push to the main branch triggers a workflow that builds and publishes the books. Zero server maintenance.
Self-hosted. Package everything into a container and run it anywhere — your own server, a cloud provider, behind a corporate firewall.
The GitHub Actions Workflow
When a developer pushes code to the main branch, a fully automated pipeline takes over. GitHub Actions orchestrates every step — no human intervention required.
Code is pushed to the main branch
GitHub Actions checks out the code and installs Rust
It caches dependencies so builds are faster next time
It installs mdbook and mdbook-mermaid
It runs cargo xtask deploy (same build process, outputs to docs/)
GitHub Pages publishes docs/ as a live website
The deployment uses the exact same xtask tool as local development. The only difference is the output folder: site/ for local preview, docs/ for GitHub Pages. Same code, different destination.
The Docker Recipe
The second deployment path uses Docker to package the books into a self-contained unit. The key technique is a multi-stage build — one stage builds the books, and a second, much smaller stage serves them.
FROM rust:1-slim-bookworm AS builder
RUN cargo install mdbook mdbook-mermaid
COPY . /src
WORKDIR /src
RUN cargo xtask build
FROM nginxinc/nginx-unprivileged:1.27-alpine
COPY --from=builder /src/site/ /usr/share/nginx/html/
EXPOSE 8080
Why Two Stages?
The builder stage includes Rust, cargo, mdbook, and all compilation tools — over 1 GB of software. The final stage is just nginx + static HTML files — under 50 MB. Multi-stage builds keep the final image small and secure by throwing away everything that was only needed for building.
The final nginx stage is not just small — it is also hardened for production. Here are the three key security and performance features baked into the configuration:
X-Content-Type-Options, X-Frame-Options, and Referrer-Policy headers protect against common web attacks
The container runs as a non-root user (uid 101) — even if someone breaks in, they cannot harm the system
Static files are cached for 1 day, with gzip compression for CSS, JS, and SVG — faster page loads for readers
Check Your Understanding
The Teaching Toolkit
The interactive tools that make learning stick
More Than Just Text
Most programming tutorials are walls of text with occasional code blocks. These books pack interactive tools into every chapter.
Visualize complex flows — like how async code executes or how data moves between components. Written as text, rendered as beautiful SVGs.
Code examples you can edit and run directly in the browser. Change a variable, hit Run, see what happens. No setup required.
Every chapter is tagged with difficulty: green for easy, yellow for intermediate, red for hard. You always know what you are getting into.
Search across all chapters in a book instantly. Forgot where ownership was explained? Search and jump right there.
How Diagrams Are Born
The books use Mermaid to create diagrams. Instead of drawing in an image editor, you write plain text — and a preprocessor converts it into a clean SVG diagram during the build. Here is a real example from the async book showing how futures are polled:
sequenceDiagram
participant E as Executor
participant F as Future (Task)
participant OS as Operating System
participant R as Reactor (Runtime)
E->>F: Calls poll(cx)
F->>OS: Syscall (e.g., read TCP socket)
OS-->>F: Returns Error: Not Ready
F-->>E: Returns Poll::Pending
The Book Configuration
Every book in the project has a book.toml file — a TOML configuration that tells mdbook how to build it. Here is a simplified version from the async book:
[book]
title = "Async Rust"
authors = ["Rust Training Team"]
language = "en"
[preprocessor.mermaid]
command = "mdbook-mermaid"
[output.html]
default-theme = "light"
preferred-dark-theme = "ayu"
The Curriculum Architecture
Each book follows a consistent three-part structure. This is not random — it mirrors how experts actually learn: start with what you know, go deep on the hard parts, then prove you can build something real.
The basics, connecting Rust concepts to what you already know
Focused exploration of major topics (concurrency, async, systems)
Best practices, migration guides, and a capstone project to tie it all together
Every bridge book ends with a capstone project — a real, complete application. The C# book builds a CLI weather tool. The Python book builds a task manager. You do not just learn concepts — you build something real.
The Big Picture
Let us zoom out and see how everything fits together. The entire system has three layers: content goes in, the build system transforms it, and the delivery layer gets it to readers.