Skip to content
rustvizPublic

About

Interactive Visual Introduction to Rust, generated by RustViz.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

108 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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 RustViz CLI, which installs the plugin and its toolchain. The RustViz plugin links against rustc_private, so it needs one specific nightly (today nightly-2026-05-01, the rust-toolchain.toml of rustviz/rustviz). rustviz init installs that nightly (with rust-src, rustc-dev and llvm-tools-preview) and the plugin:

    cargo install rustviz
    rustviz init
  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 mdBook preprocessor:

    cargo install 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.

Working on RustViz itself

To try plugin or preprocessor changes in this book, install from a checkout of rustviz/rustviz instead of crates.io. That repo's rust-toolchain.toml picks the nightly, so the toolchain from rustviz init (or cargo xtask setup) still applies:

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

cargo xtask setup also installs the plugin and the toolchain, but not mdbook-rustviz, so run the second command either way. After every change to the plugin or the preprocessor, reinstall (the book runs the installed binaries, not your source tree) and rebuild here with RV_RUNNER=local mdbook serve --open. See the "Building from this checkout" section of the rustviz README for details.

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.

The deploy workflow (.github/workflows/deploy.yml) instead builds the plugin and preprocessor from rustviz/rustviz's main, so the published book always renders with the latest RustViz. Pushes to master deploy it to https://rustviz.github.io/tutorial/.

See mdbook-rustviz's README for configuration options.

About

Interactive Visual Introduction to Rust, generated by RustViz.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Contributors