comprehensive-rust Documentation

This is the Rust course used by the Android team at Google. It provides you the material to quickly teach Rust.

33,276 stars Rust Rust 1 file · ~3,449 tokens #android#classroom#course#google#guide#rust#training#training-materials
RAW Doc

File: README.md

Comprehensive Rust 🦀



This repository has the source code for Comprehensive Rust 🦀, a multi-day Rust
course developed by the Android team. The course covers all aspects of Rust,
from basic syntax to generics and error handling. It also includes deep dives on
Android, Chromium, bare-metal, and concurrency.

Read the course at https://google.github.io/comprehensive-rust/.

Course Format and Target Audience

The course is used internally at Google to teach Rust to experienced software
engineers, typically with a background in C++ or Java.

The course is taught in a classroom setting, and we hope it will be useful for
others who want to teach Rust to their team. The course is less ideal for
self-study, since you would miss out on classroom discussions. You would not see
the questions and answers, nor the compiler errors we trigger when going through
the code samples. We hope to improve the self-study experience via
speaker notes and by
publishing videos.

Press

Articles and blog posts from around the web which cover Comprehensive Rust:

Setup

The course is built using a few tools:

First, install Rust by following the instructions on https://rustup.rs/. Next,
install Bazel via the
Bazelisk version manager. Then clone
this repository:

shell
git clone https://github.com/google/comprehensive-rust/
cd comprehensive-rust

Then run the following command to install the correct versions of all tools
mentioned above:

shell
cargo xtask install-tools

You will find the tools in your ~/.cargo/bin/ directory afterwards.

Commands

Here are some of the commonly used commands you can run in the project. Run
cargo xtask to view all available commands.

Command Description
cargo xtask install-tools Install all the tools the project depends on.
cargo xtask serve Start a web server with the course. You'll find the content on http://localhost:3000. To serve any of the translated versions of the course, add the language flag (--language or -l) followed by xx, where xx is the ISO 639 language code (e.g. cargo xtask serve -l da for the Danish translation).
cargo xtask rust-tests Test the included Rust snippets.
cargo xtask web-tests Run the web driver tests in the tests directory.
cargo xtask build Create a static version of the course in the book/ directory. Note that you have to separately build and zip exercises and add them to book/html. To build any of the translated versions of the course, add the language flag (--language or -l) followed by xx, where xx is the ISO 639 language code (e.g. cargo xtask build -l da for the Danish translation). TRANSLATIONS.md contains further instructions.

Note On Windows, you need to enable symlinks
(git config --global core.symlinks true) and Developer Mode.

Contributing

We welcome contributions. Please see CONTRIBUTING.md for
details.

License

This project is licensed under a mix of the Apache License 2.0 and the Creative
Commons Attribution 4.0 International License.

Contact

For questions or comments, please contact
Martin Geisler or start a
discussion on GitHub.
We would love to hear from you.

File: mdbook-course/README.md

mdbook-course

This is an mdBook preprocessor to handle some specific details of Comprehensive
Rust.

It provides three binaries:

  • mdbook-course -- the actual preprocessor
  • course-schedule -- prints the course schedule with timings
  • course-content -- dumps all course content to stdout, in order

Frontmatter

The preprocessor parses "frontmatter" -- YAML between --- at the beginning of
a Markdown file -- and removes it from the rendered result.

Frontmatter is optional, and can contain any of the following fields, defined
below:

yaml
minutes: NNN
target_minutes: NNN
course: COURSE NAME
session: SESSION NAME

Course Structure

A book can contain multiple courses. Each course is made up of sessions,
which are blocks of instructional time (and include breaks). Typically two
sessions are taught per day, morning and afternoon.

Each session is comprised of segments, which are slides on a related theme.
Breaks are scheduled between segments.

Each segment is comprised of slides. A slide can be made up of one or more
mdBook chapters.

The course structure is derived from the mdBook structure. Each top-level mdBook
"section" is treated as a segment, and may optionally begin a new session or
course. Within each section, the first chapter and subsequent second-level
chapters are each treated as a slide. Any further-nested chapters are treated as
parts of the parent slide. For example:

ignore
- [Frobnication](frobnication.md)
  - [Integer Frobnication](frobnication/integers.md)
  - [Frob Expansion](frobnication/expansion.md)
    - [Structs](frobnication/expansion-structs.md)
    - [Enums](frobnication/expansion-structs.md)
  - [Exercise](frobnication/exercise.md)
    - [Solution](frobnication/Solution.md)

In this segment, there are four slides: "Frobnication", "Integer Frobnication",
"Frob Expansion", and "Exercise". The last two slides are made up of multiple
chapters.

The first chapter of a segment can use the course and session fields in its
frontmatter to indicate that it is the first segment in a session or course.

Timing

Each chapter should specify an estimate of the instructional time it will
require in the minutes field. This information is summed, with breaks
automatically added between segments, to give time estimates for segments,
sessions, and courses.

Each session should list a target_minutes that is the target duration of the
session.

Directives

Within the course material, the following directives can be used:

text
{{%segment outline}}
{{%session outline}}
{{%course outline}}
{{%course outline COURSENAME}}

These will be replaced with a markdown outline of the current segment, session,
or course. The last directive can refer to another course by name and is used in
the "Running the Course" section.

Course-Schedule Comments

The course-schedule binary generates Markdown output that is included in a
GitHub pull request comment, based on the information provided in the above
format.

File: mdbook-exerciser/README.md

exerciser

This is an mdBook renderer to generate templates for exercises from the Markdown
source. Given a Markdown file example.md with one or more sections like:

markdown
```rust,compile_fail
{{#include example/src/main.rs:main}}

fn some_more_code() {
    // TODO: Write some Rust code here.
}
```

and mdbook configuration in book.toml like:

toml
[output.exerciser]
output-directory = "comprehensive-rust-exercises"

It will create a file
book/exerciser/comprehensive-rust-exercises/example/src/main.rs with the
appropriate contents.

File: src/README.md

Course Content

The files in this directory make up the content of the course. The files here
can include third-party content from ../third_party/ as well.

When we publish a translation of the course, we git restore the src/ and
third_party/ directories at the repository root back to the date listed in the
POT-Creation-Date header of the translation. It is crucial, that all
translatable content lives in those two directories. The other files (such as
book.toml and theme/) are not restored and we always use the latest version
of them.

File: third_party/mdbook/README.md

mdBook

This directory contains files copied from mdBook. Please see
https://github.com/rust-lang/mdBook/ for the full project.

License

mdBook is licensed under the Mozilla Public License v2.0 (LICENSE).

File: third_party/cxx/README.md

CXX

This directory contains files copied from CXX. Please see
https://github.com/dtolnay/cxx for the full project.

License

CXX is licensed under either of

at your option.

File: third_party/README.md

Third-party Course Content

The files in this directory are included in the course via the {{#include ..}}
syntax. All third-party content must be placed here to clearly indicate its
origin.

When we publish a translation of the course, we git restore the src/ and
third_party/ directories at the repository root back to the date listed in the
POT-Creation-Date header of the translation. It is crucial, that all
translatable content lives in those two directories. The other files (such as
book.toml and theme/) are not restored and we always use the latest version
of them.

File: xtask/README.md

xtask

The purpose of the xtask binary is to enable cross platform task automation
within the project (somewhat similar to how npm run is used in Node.js
projects to run scripts). Please see
cargo xtask for more information.

To add support for a new task, add a new arm to the match in the
execute_task function, and add a new handler function that contains the logic.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#android Browse android catalog → #classroom Browse classroom catalog → #course Browse course catalog → #google Browse google catalog → #guide Browse guide catalog → #rust Browse rust catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →