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-2023-04-12 -c rust-src rustc-dev llvm-tools-preview miri
cargo +nightly-2023-04-12 install --git https://github.com/cognitive-engineering-lab/aquascope aquascope_front
cargo +nightly-2023-04-12 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 first need to install cargo-make, a Rust build tool, like this:

cargo install cargo-make --locked

Then you need to install Depot, a Javascript build tool, like this:

curl https://raw.githubusercontent.com/cognitive-engineering-lab/depot/main/scripts/install.sh | sh

Then you can install Aquascope from source like this:

git clone https://github.com/cognitive-engineering-lab/aquascope.git
cd aquascope
cargo make install-mdbook

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].