22d6af4abd
Adds the start of an unsafe deep dive to Comprehensive Rust. The `unsafe` keyword is easy to type, but hard to master. When used appropriately, it forms a useful and indeed essential part of the Rust programming language. By the end of this deep dive, you'll know how to work with `unsafe` code, review others' changes that include the `unsafe` keyword, and produce your own. What you'll learn: - What the terms undefined behavior, soundness, and safety mean - Why the `unsafe` keyword exists in the Rust language - How to write your own code using `unsafe` safely - How to review `unsafe` code Here is a tentative outline of a 10h (2 day) treatment: Day 1: Using and Reviewing Unsafe - Welcome - Motivations: explain why the `unsafe` keyword exists - Foundations: provide background knowledge; what is soundness? what is undefined behavior? what is validity in respect to pointers? - Mechanics: what a safe `unsafe` block should look like - Representations and Interoperability: explore how data is laid out in memory and how that can be sent across the wire and/or stored on disk. - Reviewing unsafe - Patterns for safer unsafe: Encapsulating unsafe code in safe-to-use abstractions, such as marking a type's constructor as `unsafe` so that invariants only need to be enforced once by the programmer. Day 2: Deploying Unsafe to Build Abstractions - Welcome - Validity in detail: A refresher. Emphasis on the details of the invariants that are being upheld by a “typical” unsafe block, such as aliasing, alignment, data validity, padding. - Concurrency and thread safety: understanding `Send` and `Sync`, knowing how to implement them on a user-defined type - Case study: Small string optimization - Case study: Zero-copy parsing - Review --------- Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com>
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 when teaching Rust to experienced software engineers. They typically have 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 will be less useful for self-study since you miss out on the discussions happening in the classroom. You don't see the questions and answers and you don't see the compiler errors we trigger when going through the code samples. We hope to improve on this via speaker notes and by publishing videos.
Press
Articles and blog posts from around the web which cover Comprehensive Rust:
- 2023-09-08: Teaching Rust in 5 days. Comprehensive Rust was used as a base for a 5-day university class on Rust.
- 2023-09-21: Scaling Rust Adoption Through Training. We published a blog post with details on the development of the course.
- 2023-10-02: In Search of Rust Developers, Companies Turn to In-House Training. About how Microsoft, Google, and others are training people in Rust.
- 2024-10-18: Rust Training at Scale | Rust Global @ RustConf 2024. What Google learnt from teaching Comprehensive Rust for more than two years.
Setup
The course is built using a few tools:
- mdbook
- mdbook-svgbob
- mdbook-i18n-helpers and i18n-report
- mdbook-exerciser
- mdbook-course
- mdbook-linkcheck2
First install Rust by following the instructions on https://rustup.rs/. Then clone this repository:
git clone https://github.com/google/comprehensive-rust/
cd comprehensive-rust
Then install these tools with:
cargo xtask install-tools
Commands
Here is a summary of the various commands you can run in the project.
| Command | Description |
|---|---|
cargo install-tools |
Install all the tools the project depends on. |
cargo serve |
Start a web server with the course. You'll find the content on http://localhost:3000. |
cargo rust-tests |
Test the included Rust snippets. |
cargo web-tests |
Run the web driver tests in the tests directory. |
cargo build-book |
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, run MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xx where xx is the ISO 639 language code (e.g. 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.
Note
Previous versions this README recommended that you use
cargo xtool <tool>, i.e.cargo xtool install-tools. This causes issues with pre-existing installations ofcargo-xtooland is now deprecated.The new syntax is almost a 1:1 mapping, although
cargo xtool buildhas becomecargo build-bookto avoid conflicting with the built-in Cargo subcommand.
cargo xtool build->cargo build-bookcargo xtool install-tools->cargo install-toolscargo xtool serve->cargo servecargo xtool run-tests->cargo run-testscargo xtool web-tests->cargo web-tests
Contributing
We would like to receive your contributions. Please see CONTRIBUTING.md for details.
Contact
For questions or comments, please contact Martin Geisler or start a discussion on GitHub. We would love to hear from you.