mirror of
https://github.com/google/comprehensive-rust.git
synced 2025-01-10 00:44:21 +02:00
963c6979ed
Reverts google/comprehensive-rust#1975 Using `mdbook-pandoc` requires more than just installing the `mdbook` plugin: it requires - A whole LaTeX installation - A Pandoc installation - Some fonts This is essentially why the output is configured as optional in `book.toml`: the assumption is that people won't have `mdbook-pandoc` installed without the necessary supporting tools. @henrif75, I assume you added this because you didn't like the warning `mdbook build` prints: ``` % mdbook build 2024-04-16 10:45:56 [WARN] (mdbook::book): The output.html.curly-quotes field has been renamed to output.html.smart-punctuation. Use the new name in book.toml to remove this warning. 2024-04-16 10:45:56 [INFO] (mdbook::book): Book building has started 2024-04-16 10:45:57 [INFO] (mdbook::book): Running the exerciser backend 2024-04-16 10:45:57 [INFO] (mdbook::renderer): Invoking the "exerciser" renderer 2024-04-16 10:45:57 [INFO] (mdbook::book): Running the html backend 2024-04-16 10:45:58 [INFO] (mdbook::book): Running the pandoc backend 2024-04-16 10:45:58 [INFO] (mdbook::renderer): Invoking the "pandoc" renderer 2024-04-16 10:45:58 [WARN] (mdbook::renderer): The command `mdbook-pandoc` for backend `pandoc` was not found, but was marked as optional. ``` I don't have the necessary dependencies on my local system and this is what I get after installing `mdbook-pandoc`: ``` 2024-04-16 10:47:30 [INFO] (mdbook::renderer): Invoking the "pandoc" renderer Unable to run `pandoc -v`: No such file or directory (os error 2) 2024-04-16 10:47:30 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code. 2024-04-16 10:47:30 [ERROR] (mdbook::utils): Error: Rendering failed 2024-04-16 10:47:30 [ERROR] (mdbook::utils): Caused By: The "pandoc" renderer failed ``` This also means that `mdbook serve` doesn't work unless all dependencies are installed. As an alternative, we could remove the `output.pandoc` settings from the `book.toml` file and use a small shell script to add them when needed. We actually have the same problem for the `mdbook-xgettext` output format which generates the POT files: we only want to run this occasionally. This is currently done by overriding `output` from the command line using the `MDBOOK_OUTPUT` environment variable: ```shell MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot", "granularity": 0}}' \ mdbook build -d po ``` It's a bit ugly and it results in people missing/forgetting some of the configuration options we want them to use (the `granularity` setting). So I would like to move this configuration to the `book.toml` file — but I'm reluctant since I don't think we need to generate POT files on every build (it takes ~1 second and would slow down `mdbook serve`). Cc @max-heller in case you have ideas here.
103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
# Comprehensive Rust 🦀
|
|
|
|
[](https://github.com/google/comprehensive-rust/actions/workflows/build.yml?query=branch%3Amain)
|
|
[](https://github.com/google/comprehensive-rust/graphs/contributors)
|
|
[](https://github.com/google/comprehensive-rust/stargazers)
|
|
|
|
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].
|
|
|
|
[Android]: https://google.github.io/comprehensive-rust/android.html
|
|
[Chromium]: https://google.github.io/comprehensive-rust/chromium.html
|
|
[bare-metal]: https://google.github.io/comprehensive-rust/bare-metal.html
|
|
[concurrency]: https://google.github.io/comprehensive-rust/concurrency.html
|
|
|
|
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](https://github.com/google/comprehensive-rust/issues/53) and by
|
|
[publishing videos](https://github.com/google/comprehensive-rust/issues/52).
|
|
|
|
## Press
|
|
|
|
Articles and blog posts from around the web which cover Comprehensive Rust:
|
|
|
|
- 2023-09-08:
|
|
_[Teaching Rust in 5 days](https://mo8it.com/blog/teaching-rust/)_.
|
|
Comprehensive Rust was used as a base for a 5-day university class on Rust.
|
|
- 2023-09-21:
|
|
_[Scaling Rust Adoption Through Training](https://security.googleblog.com/2023/09/scaling-rust-adoption-through-training.html)_.
|
|
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](https://www.darkreading.com/application-security/google-microsoft-take-refuge-in-rust-languages-better-security)_.
|
|
About how Microsoft, Google, and others are training people in Rust.
|
|
|
|
## Building
|
|
|
|
The course is built using a few tools:
|
|
|
|
- [mdbook](https://github.com/rust-lang/mdBook)
|
|
- [mdbook-svgbob](https://github.com/boozook/mdbook-svgbob)
|
|
- [mdbook-i18n-helpers](https://github.com/google/mdbook-i18n-helpers)
|
|
- [mdbook-exerciser](mdbook-exerciser/)
|
|
- [mdbook-course](mdbook-course/)
|
|
|
|
First install Rust by following the instructions on https://rustup.rs/. Then
|
|
clone this repository:
|
|
|
|
```shell
|
|
git clone https://github.com/google/comprehensive-rust/
|
|
cd comprehensive-rust
|
|
```
|
|
|
|
Then install these tools with:
|
|
|
|
```shell
|
|
cargo install mdbook
|
|
cargo install --locked mdbook-svgbob
|
|
cargo install --locked mdbook-i18n-helpers
|
|
cargo install --locked --path mdbook-exerciser
|
|
cargo install --locked --path mdbook-course
|
|
```
|
|
|
|
Run
|
|
|
|
```shell
|
|
mdbook test
|
|
```
|
|
|
|
to test all included Rust snippets. Run
|
|
|
|
```shell
|
|
mdbook serve
|
|
```
|
|
|
|
to start a web server with the course. You'll find the content on
|
|
<http://localhost:3000>. You can use `mdbook build` to 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](TRANSLATIONS.md) contains further instructions.
|
|
|
|
> **Note** On Windows, you need to enable symlinks
|
|
> (`git config --global core.symlinks true`) and Developer Mode.
|
|
|
|
## Contact
|
|
|
|
For questions or comments, please contact
|
|
[Martin Geisler](mailto:mgeisler@google.com) or start a
|
|
[discussion on GitHub](https://github.com/google/comprehensive-rust/discussions).
|
|
We would love to hear from you.
|