RustViz Tutorial

A short visual introduction to Rust, with interactive ownership and borrowing diagrams generated by RustViz. The tutorial is built as an mdBook — each chapter embeds RustViz visualizations alongside the prose.

Building locally

The book is built by the mdbook-rustviz mdBook preprocessor, which compiles each visualization snippet through the RustViz compiler plugin and inlines the resulting SVGs into the rendered HTML.

You'll need:

1. The Rust nightly in rustviz/rustviz's rust-toolchain.toml (the RustViz plugin links against rustc_private, which pins the toolchain). Today that is nightly-2026-05-01; check the current value and substitute it below.

   rustup toolchain install nightly-2026-05-01 \
       --component rust-src,rustc-dev,llvm-tools-preview

2. mdBook 0.5+. mdBook 0.5 needs Rust ≥ 1.88, which the project nightly above already provides:

   cargo +nightly-2026-05-01 install mdbook --version "^0.5"

3. The RustViz plugin and the mdBook preprocessor, both built from the rustviz repo:

   git clone https://github.com/rustviz/rustviz
   cd rustviz
   cargo install --path rustviz-plugin
   cargo install --path mdbook-rustviz

Then, in this repo:

RV_RUNNER=local mdbook serve --open

RV_RUNNER=local runs the plugin in-process, which is fast and doesn't need Docker. The default RV_RUNNER=docker runs each snippet in a sandboxed rustviz/rustviz-runner container — useful if you're authoring a public site and don't want to trust arbitrary snippets, but heavier to set up.

Authoring

Code blocks tagged ```rv are picked up by the preprocessor and turned into a side-by-side code panel + timeline visualization. For example:

```rv
fn main() {
    let s = String::from("hello");
    println!("{}", s);
}
```

To keep a helper function out of a figure, end its signature line with // rustviz: hide. The function's definition is dropped from the rendered code panel, along with its parameters' timelines, while the calls to it in main are still drawn. The marker only works on fn lines (free functions and methods); on a struct or use line it is ignored (rustviz/rustviz#814). When you hide a function, say in the prose what it does, since readers can no longer see its body.

See mdbook-rustviz's README for configuration options.