drruisseau / aquascope

Interactive visualizations of Rust at compile-time and run-time

Aquascope: Look Beneath the Surface of Rust

Aquascope is a tool that generates interactive visualizations of Rust programs. These visualizations show how Rust's borrow checker "thinks" about a program, and how a Rust program actually executes. Here is a sample output of Aquascope:

Click here for a live demo. Want to learn more about what the diagram means? Read the new ownership chapter in our Rust Book Experiment.

⚠️ Aquascope is research software and under active development! ⚠️

Installation

We provide an mdBook preprocessor that embeds Aquascope diagrams into an mdBook. To use it, you need to install the mdbook-aquascope and cargo-aquascope binaries as follows:

cargo install mdbook-aquascope
rustup toolchain install nightly-2022-12-07 -c rust-src rustc-dev llvm-tools-preview miri
cargo +nightly-2022-12-07 install --git https://github.com/cognitive-engineering-lab/aquascope aquascope_front
cargo +nightly-2022-12-07 miri setup

Note that cargo-aquascope is installed via aquascope_front and must be installed via git and with a specific nightly toolchain. The miri setup command is a necessary prerequisite to running the Aquascope interpreter.

From Source

If you want to install from source, you will first need Cargo and npm installed, then you can run:

git clone https://github.com/cognitive-engineering-lab/aquascope.git
cd aquascope
npm install -g graco
cargo make init-bindings
cd frontend && graco prepare
cargo install --path crates/aquascope_front
cargo install --path crates/mdbook-aquascope

Usage

First, enable mdbook-aquascope in your mdBook's book.toml like so:

# book.toml
[preprocessor.aquascope]

Then add an Aquascope code block to one of your Markdown source files like this:

```aquascope,interpreter
#fn main() {
let mut s = String::from("hello ");`[]`
s.push_str("world");`[]`
#}
```

Further documentation on the syntax and configuration of Aquascope blocks will be provided once the interface is more stable.

Having trouble?

If you want to use Aquascope but are having trouble finding the relevant information, please leave an issue or email us at [email protected] and [email protected].