mirror of https://github.com/google/comprehensive-rust.git synced 2026-06-11 18:37:59 +02:00

Files

T

History

Martin Geisler c092c383ad bazel: Build and cache local tools with Bazel (#3197 )

This PR is the first step of several aiming at introducing better
caching and reproducibility with Bazel. It will eventually fix #1168.

I have been introducing Bazel for a large polyglot build at work, and
this gave me hands on experience with building Rust with Bazel. In this
project, we have so far been using shell scripts. YAML files, and a bit
of `cargo xtask` to keep the build here going.

However, it's time to admit that we have a non-trivial build process:

- we build several `mdbook` plugins, some from our repository, some from
external repositories (we install them globally with `cargo install`).

- we use `build.sh` to backdate the sources for translations (we leave
behnd a dirty working copy).

- we have end-to-end tests which rely on NodeJS being installed on the
system.

All this complexity can be rained in with Bazel: we can build our
`mdbook` plugins hermetically and put them on the `PATH` only for the
final `mdbook build` invocation. We can put our backdated sources into
temporary directories and keep the working copy clean. This will let us
skip building translations that haven't changed, thus speeding up local
and CI builds.

I have not yet looked at the NodeJS parts, but I'm sure that can be
integrated with Bazel as well.

The approach used lets `rules_rust` read the `Cargo.lock` file:

```python
crate = use_extension("@rules_rust//crate_universe:extensions.bzl", "crate")
crate.from_cargo(
    name = "crates",
    cargo_lockfile = "//:Cargo.lock",
    manifests = ["//:Cargo.toml"],
)
use_repo(crate, "crates")
```

This is the documented on
https://bazelbuild.github.io/rules_rust/crate_universe_bzlmod.html.

It build on the existing Cargo setup and is thus compatible with it. We
can discuss later if we want to keep Cargo compatibility or move
completely to Bazel.

2026-06-09 21:20:58 +02:00

src

build: add SPDX-License-Identifier to Apache 2.0 licensed files (#3095 )

2026-02-16 12:33:41 +01:00

BUILD.bazel

bazel: Build and cache local tools with Bazel (#3197 )

2026-06-09 21:20:58 +02:00

Cargo.toml

cargo: bump the patch group with 7 updates (#3194 )

2026-06-01 10:17:27 +00:00

README.md

…

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:

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:

- [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:

{{%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.