microsoft/RustTraining: Seven Rust Books, Grouped by Your Previous Language

Seven books, sorted by the language you already know

The problem this addresses is not a shortage of Rust material. It is the order of it. Someone who has written C++ for a decade and someone who has written Python for a decade hit different walls on day one, and a single introductory book serves both badly. RustTraining splits the entry point by prior language. Three bridge books cover Rust for C/C++ programmers (move semantics, RAII, FFI, embedded, no_std), for C# programmers (the README also lists Swift and Java in that row, aimed at ownership and the type system), and for Python programmers (dynamic to static typing, GIL-free concurrency). Four more titles sit above that: Async Rust, Rust Patterns, Type-Driven Correctness and Rust Engineering Practices.

The audience is therefore narrow and specific. It is a working programmer in one of those languages who wants Rust, and a reader who prefers a curated curriculum to assembling one from blog posts. The README states the goal plainly: to weave knowledge scattered across books, blogs, conference talks and video series into a cohesive, pedagogically structured experience. It also names its influences, from The Rust Programming Language through Jon Gjengset, withoutboats, Mara Bos, matklad and Niko Matsakis. That list is worth reading as a scope statement. Where a topic is not covered by those sources, it is probably not covered here.

How the books are built: mdBook, Mermaid, and an xtask workspace

Each book is a directory at the repository root: c-cpp-book/, csharp-book/, python-book/, async-book/, rust-patterns-book/, type-driven-correctness-book/ and engineering-book/. They are rendered with mdBook, and the README says each has 15 to 16 chapters with Mermaid diagrams, editable Rust playgrounds, exercises and full-text search. The diagrams are the reason mdbook-mermaid is a separate install; plain mdBook would render the diagram source as text.

The build is driven by an xtask crate. The root Cargo.toml is a two-line workspace that declares resolver 2 and a single member, xtask. So the repository is a Cargo workspace whose only compiled artifact is the build tool, not a library or a binary you would ship. That is a deliberate shape: the books are content, and the tooling is small enough to live in one crate. The README documents four subcommands, build, serve, deploy and clean, and notes that deploy writes into docs/ for GitHub Pages while build writes into site/ for local preview. The separation matters because it keeps preview output out of the published tree.

Publishing is automated. The README states the site auto-deploys to GitHub Pages on push to main via .github/workflows/pages.yml, with no manual steps. The rendered books are also reachable directly at microsoft.github.io/RustTraining, and each book has its own path under that root.

Installing the toolchain and serving a book locally

The README's local preview path assumes Rust is already installed via rustup. It then pins the two mdBook tools to exact versions in the maintainer section, [email protected] and [email protected]. Use those versions if you want the build the maintainers describe; the README does not claim other versions work.

cargo install [email protected] [email protected]

Clone the repository and enter it. The README gives this as a plain git clone, so no submodules or extra fetch steps are involved.

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

From the repository root, the xtask subcommands build or serve every book. serve is the one to use for reading: the README says it builds and serves at http://localhost:3000.

cargo xtask serve    # http://localhost:3000

If you only care about one book, the README shows the shorter route: change into that book's directory and run mdbook directly. The example uses the C/C++ book and the --open flag.

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

What you should see is a served site with sidebar navigation and search, the same structure as the GitHub Pages version. The README also documents cargo xtask build for a local site/ preview, cargo xtask deploy to write docs/, and cargo xtask clean to remove both directories. Note the port: both routes use 3000, so do not run them at the same time.

It is teaching material, and the README says so

The most useful sentence in the README is the disclaimer. These books are training material, not an authoritative reference, and readers are told to verify critical details against the official Rust documentation and the Rust Reference. Take that at face value. If you are checking whether a trait bound is required, whether a method is stable, or what the exact semantics of a standard library type are, this repository is the wrong place to look. It is a curriculum, and curricula go stale while references are versioned.

The second limitation is the entry points. There is no book for someone coming from Go, Ruby, JavaScript or no programming background at all. The bridge tier assumes C/C++, C#, Java, Swift or Python. A beginner with no prior language is not the target, and the README does not offer a starting path for them.

The third is the maintenance signal. The repository is not archived, which is the only status fact stated; the README documents no release process and no versioned editions of the books, and the pinned mdbook versions are the only version numbers mentioned anywhere. So there is no way to tell how often the prose is revised as Rust changes. If you are standardizing a team on this, that is the open question, and the repository does not answer it.

RustTraining compared with The Rust Programming Language

The README names The Rust Programming Language as the foundation everything builds on, so the honest comparison is not which is better but which job each does. The official book is a single linear path through the language, written for a reader who may not have programmed before, and it is maintained alongside the language itself. RustTraining is a set of parallel paths, each assuming you already think in another language's idioms, and it is maintained as a repository of books.

The practical difference shows up in what you read first. With the official book you start at chapter one regardless of background. With RustTraining you start in c-cpp-book or csharp-book or python-book, and the material can spend its pages on the delta between your language and Rust instead of on what a variable is. The cost is coverage: seven books of 15 to 16 chapters each is a large surface, and nothing in the README claims they are kept in sync with each other or with a specific Rust edition. For a reader who wants one authoritative text, the official book is the safer choice. For a reader who wants the C++ to Rust translation specifically, no single-book alternative does that job as directly.

Licence, forks, and what the dual licence actually covers

The README states the project is dual-licensed under the MIT License and Creative Commons Attribution 4.0 International (CC-BY-4.0), and the repository carries both LICENSE and LICENSE-DOCS files. The split is visible in the names: MIT for the code, which here means the xtask build tooling, and CC-BY-4.0 for the documentation, which is the books. If you fork this to teach an internal course, the attribution requirement attaches to the prose and diagrams, not just to the source files. This is a description of what the files say, not legal advice; read both licences before redistributing.

The trademark notice is the other constraint worth reading before you reuse anything. The README states that authorized use of Microsoft trademarks or logos is subject to Microsoft's Trademark & Brand Guidelines, and that use in modified versions must not cause confusion or imply Microsoft sponsorship. A fork that keeps the Microsoft name in a way that suggests endorsement is exactly the case the notice addresses. Strip or adjust branding in derivatives, and note that third-party trademarks appearing in the books are governed by their owners' policies.

Contributing and running the build yourself

The repository carries CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md at the top level, along with a docker/ directory and a .dockerignore, which suggests a containerized build path exists even though the README does not document one. The README's contributor instructions are the same as the reader instructions: install Rust via rustup, install the two pinned mdBook tools, clone, then use the xtask subcommands. There is no separate contributor toolchain and no test command documented for the prose.

The upgrade cost is therefore low and concentrated. The only versioned dependencies named anywhere are [email protected] and [email protected], so a toolchain bump is a one-line change to the install command plus whatever the mdBook release notes require. The books themselves are Markdown and Mermaid, which means a contributor edits text rather than code, and cargo xtask serve gives immediate feedback at http://localhost:3000. If you want to add a chapter to an existing book, the README's per-book route (cd into the book directory and run mdbook serve) is the shortest loop.

Editorial conclusion

Adopt it if you already program in C/C++, C#, Java, Swift or Python and want a reading path that starts from the mental model you have. Do not adopt it as a reference: the README calls the books training material and tells you to verify critical details against the official Rust documentation and the Rust Reference. Before committing, open the GitHub Pages site, pick the bridge book for your language, and check whether the chapter list matches what you need; if you only want the language itself, read The Rust Programming Language instead, which this project names as its foundation.

Frequently asked questions

Official sources

1. Official README
2. Project repository