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! If you encounter a bug, we welcome contributions! 🧪⚠️

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 --locked --version 0.3.4
rustup toolchain install nightly-2023-08-25 -c rust-src rustc-dev llvm-tools-preview miri
cargo +nightly-2023-08-25 install aquascope_front --git https://github.com/cognitive-engineering-lab/aquascope --tag v0.3.4 --locked
cargo +nightly-2023-08-25 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.

Local Playground

Running the provided playground locally is also easy. First, you'll need to follow the above from source installation instructions. Then, you can launch the server by running cargo make playground and navigate to localhost:5173 to explore.

Note, the local playground does not run the tool within a sandbox. This makes the local version quicker, but don't run any malicious programs.

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

Citation

Aquascope was developed as a part of our academic research on how people learn Rust. If you use Aquascope as a part of your research, please cite this paper:

@article{cgk:aquascope,
  author = {Crichton, Will and Gray, Gavin and Krishnamurthi, Shriram},
  title = {A Grounded Conceptual Model for Ownership Types in Rust},
  year = {2023},
  issue_date = {October 2023},
  publisher = {Association for Computing Machinery},
  address = {New York, NY, USA},
  volume = {7},
  number = {OOPSLA2},
  url = {https://doi.org/10.1145/3622841},
  doi = {10.1145/3622841},
  journal = {Proc. ACM Program. Lang.},
  month = {oct},
  articleno = {265},
  numpages = {29},
  keywords = {Rust, concept inventory, ownership types, program state visualization}
}