Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cognitive-engineering-lab/aquascope
Interactive visualizations of Rust at compile-time and run-time
https://github.com/cognitive-engineering-lab/aquascope
Last synced: 25 days ago
JSON representation
Interactive visualizations of Rust at compile-time and run-time
- Host: GitHub
- URL: https://github.com/cognitive-engineering-lab/aquascope
- Owner: cognitive-engineering-lab
- License: mit
- Created: 2022-09-15T21:53:40.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-29T01:10:31.000Z (about 1 month ago)
- Last Synced: 2024-10-01T23:44:08.944Z (about 1 month ago)
- Language: Rust
- Homepage: https://cognitive-engineering-lab.github.io/aquascope/
- Size: 70.7 MB
- Stars: 1,966
- Watchers: 18
- Forks: 45
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-rust - Aquascope - Interactive visualizations of Rust at compile-time and run-time (Resources / Web programming)
- trackawesomelist - Aquascope (⭐2k) - Interactive visualizations of Rust at compile-time and run-time (Recently Updated / [Sep 27, 2024](/content/2024/09/27/README.md))
README
# Aquascope: Look Beneath the Surface of Rust
[](https://github.com/cognitive-engineering-lab/aquascope/actions/workflows/ci.yml)
[](https://crates.io/crates/mdbook-aquascope)
[](https://cognitive-engineering-lab.github.io/aquascope/doc/aquascope/)
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.](https://cognitive-engineering-lab.github.io/aquascope/) Want to learn more about what the diagram means? [Read the new ownership chapter in our Rust Book Experiment.](https://rust-book.cs.brown.edu/ch04-01-what-is-ownership.html)
⚠️🔬 **Aquascope is research software! If you encounter a bug, we welcome contributions!** 🧪⚠️
## Installation
We provide an [mdBook](https://rust-lang.github.io/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.
```sh
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](https://github.com/sagiegurari/cargo-make), a Rust build tool, like this:
```
cargo install cargo-make --locked
```
Then you need to install [Depot](https://github.com/cognitive-engineering-lab/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:
```sh
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:
```toml
# 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](https://cognitive-engineering-lab.github.io/aquascope/) 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`](http://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 and .
## Citation
Aquascope was developed as a part of our academic research on [how people learn Rust](https://dl.acm.org/doi/10.1145/3622841). If you use Aquascope as a part of your research, please cite this paper:
```bibtex
@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}
}
```