README.md

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. Rust nightly-2025-08-20 (the RustViz plugin links against rustc_private, which pins the toolchain).

   rustup toolchain install nightly-2025-08-20 \
       --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-2025-08-20 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 rustviz2-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);
}
```

See mdbook-rustviz's README for configuration options.