RustTraining Documentation

Technical Documentation: microsoft/RustTraining

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

License This project is dual-licensed under the MIT License and Creative Commons Attribution 4.0 International (CC-BY-4.0).

Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Rust Training Books

Seven training courses covering Rust from different programming backgrounds, plus deep-dives on async, advanced patterns, and engineering practices.

This material combines original content with ideas and examples inspired by some of the best resources in the Rust ecosystem. The goal is to present an in-depth, technically accurate curriculum that weaves together knowledge scattered across books, blogs, conference talks, and video series into a cohesive, pedagogically structured experience.

Disclaimer: These books are training material, not an authoritative reference. While we strive for accuracy, always verify critical details against the official Rust documentation and the Rust Reference.

Inspirations & Acknowledgments Copy Section

• The Rust Programming Language — the foundation everything builds on
• Jon Gjengset — deep-dive streams on advanced Rust internals, Crust of Rust series
• withoutboats — async design, Pin, and the futures model
• fasterthanlime (Amos) — systems programming from first principles, engaging long-form explorations
• Mara Bos — Rust Atomics and Locks, concurrency primitives
• Aleksey Kladov (matklad) — Rust analyzer insights, API design, error handling patterns
• Niko Matsakis — language design, borrow checker internals, Polonius
• Rust by Example and Rustonomicon — practical patterns and unsafe deep-dives
• This Week in Rust — community discoveries that shaped many examples
• Binary Musings - Tag(Rust) — Deep dive into Rust internals
• …and many others in the Rust community at large whose blog posts, conference talks, RFCs, and forum discussions have informed this material — too numerous to list individually, but deeply appreciated

📖 Start Reading Copy Chapter

Pick the book that matches your background. Books are grouped by complexity so you can chart a learning path:

Each book has 15–16 chapters with Mermaid diagrams, editable Rust playgrounds, exercises, and full-text search.

Tip: Browse the rendered books with sidebar navigation and search at the GitHub Pages site.

Local preview: For offline reading or while contributing (install Rust first):

text Copy

git clone https://github.com/microsoft/RustTraining.git
cd RustTraining
cargo install mdbook mdbook-mermaid
cargo xtask serve    # http://localhost:3000

🔧 For Maintainers Copy Chapter

Building, serving, and editing the books locally

Prerequisites Copy Section

Install Rust via rustup if you haven't already, then:

cargo install [email protected] [email protected]

Clone the repo Copy Section

git clone https://github.com/microsoft/RustTraining.git
cd RustTraining

Build & serve Copy Section

cargo xtask build               # Build all books into site/ (local preview)
cargo xtask serve               # Build and serve at http://localhost:3000
cargo xtask deploy              # Build all books into docs/ (for GitHub Pages)
cargo xtask clean               # Remove site/ and docs/

To build or serve a single book:

cd c-cpp-book && mdbook serve --open    # http://localhost:3000

Deployment Copy Section

The site auto-deploys to GitHub Pages on push to main via .github/workflows/pages.yml. No manual steps needed.

Overview (`docker/README.md`) Copy Section

Containerized deployment

Optional, opt-in way to self-host the book collection without GitHub Pages —
useful behind a firewall or on an internal network.

This is not the local development path. For writing and previewing, use
cargo xtask serve, which rebuilds and serves at http://localhost:3000 with
no container involved.

Usage Copy Chapter

From the repository root:

docker compose -f docker/compose.yaml up --build

Then open http://localhost:3000. Override the host port with PORT:

PORT=8080 docker compose -f docker/compose.yaml up --build

Without Compose:

docker build -f docker/Dockerfile -t rust-training .
docker run --rm -p 3000:8080 rust-training

Note the build context is the repository root in both cases — the build needs
the book sources and the xtask crate.

How it works Copy Chapter

Two stages:

1. builder (rust:1-slim-bookworm) installs mdbook and mdbook-mermaid,
   then runs cargo xtask build, which builds all seven books into site/
   along with the generated landing page.
2. runtime (nginxinc/nginx-unprivileged:alpine) serves site/ on port
   8080. No Rust toolchain, no mdbook, no book sources in the final image.

xtask build is used rather than xtask deploy because the two produce
identical content — deploy only differs in writing to docs/ and printing
GitHub Pages instructions, which are irrelevant in a container.

Pinned versions Copy Chapter

MDBOOK_VERSION and MDBOOK_MERMAID_VERSION are build args in the Dockerfile.
CI (pages.yml) currently installs both unpinned via cargo install, so the
container may lag or lead the published site after an upstream mdbook release.
Bump the args when that matters.

Prebuilt release binaries are used where upstream publishes them, falling back
to cargo install otherwise. As of the pinned versions, mdbook-mermaid has no
published arm64 Linux binary, so arm64 builds compile it from source and take
noticeably longer.

Notes Copy Chapter

• The container runs as uid 101 and binds an unprivileged port, so it needs no
  root and no added capabilities.
• Adding read_only: true to the service is possible but requires tmpfs mounts
  for nginx's cache and pid paths; it is left off by default rather than shipped
  untested.
• Content is baked in at build time. Rebuild the image to pick up book changes.

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~2170 tokens
• Canonical Reference: https://codewiki.google/github.com/microsoft/RustTraining