{"id":13469389,"url":"https://github.com/cognitive-engineering-lab/aquascope","last_synced_at":"2025-05-13T17:14:09.247Z","repository":{"id":61855303,"uuid":"537217688","full_name":"cognitive-engineering-lab/aquascope","owner":"cognitive-engineering-lab","description":"Interactive visualizations of Rust at compile-time and run-time","archived":false,"fork":false,"pushed_at":"2025-05-05T18:00:18.000Z","size":82356,"stargazers_count":2568,"open_issues_count":29,"forks_count":53,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-05-05T19:22:36.469Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cel.cs.brown.edu/aquascope/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cognitive-engineering-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-15T21:53:40.000Z","updated_at":"2025-05-05T18:00:22.000Z","dependencies_parsed_at":"2024-07-19T06:05:34.910Z","dependency_job_id":"858c4c2e-ee6f-4c28-89d5-7465167d37d8","html_url":"https://github.com/cognitive-engineering-lab/aquascope","commit_stats":{"total_commits":232,"total_committers":2,"mean_commits":116.0,"dds":"0.14224137931034486","last_synced_commit":"7c2bc0a00bb17e40107bc348b9312384dc40264e"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitive-engineering-lab%2Faquascope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitive-engineering-lab%2Faquascope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitive-engineering-lab%2Faquascope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitive-engineering-lab%2Faquascope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cognitive-engineering-lab","download_url":"https://codeload.github.com/cognitive-engineering-lab/aquascope/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253990499,"owners_count":21995776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:01:37.235Z","updated_at":"2025-05-13T17:14:04.235Z","avatar_url":"https://github.com/cognitive-engineering-lab.png","language":"Rust","funding_links":[],"categories":["Rust","Resources","Recently Updated","\u003ca name=\"Rust\"\u003e\u003c/a\u003eRust"],"sub_categories":["Web programming","[Sep 27, 2024](/content/2024/09/27/README.md)"],"readme":"# \u003cspan\u003eAquascope: Look Beneath the Surface of Rust\u003c/span\u003e\u003cimg src=\"https://user-images.githubusercontent.com/663326/219528078-e8792f31-02b3-447f-97ed-f3c0fbb4f557.png\" style=\"float: right; border: 1px solid #555;\" height=\"250\" /\u003e\u003c/p\u003e\n\n[![tests](https://github.com/cognitive-engineering-lab/aquascope/actions/workflows/ci.yml/badge.svg)](https://github.com/cognitive-engineering-lab/aquascope/actions/workflows/ci.yml)\n[![crates.io](https://img.shields.io/crates/v/mdbook-aquascope.svg)](https://crates.io/crates/mdbook-aquascope)\n[![docs](https://img.shields.io/badge/docs-built-blue)](https://cel.cs.brown.edu//aquascope/doc/aquascope/)\n\nAquascope 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:\n\n\u003cimg alt=\"Example Aquascope output\" src=\"https://user-images.githubusercontent.com/663326/219532624-a9605540-dac9-4d9b-a5f2-8a3d1ca81f50.png\" height=\"550\" /\u003e\n\n[Click here for a live demo.](https://cel.cs.brown.edu/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)\n\n⚠️🔬 **Aquascope is research software! If you encounter a bug, we welcome contributions!** 🧪⚠️\n\n## Installation\n\nWe 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.\n\n```sh\ncargo install mdbook-aquascope --locked --version 0.3.5\nrustup toolchain install nightly-2024-12-15 -c rust-src -c rustc-dev -c llvm-tools-preview -c miri\ncargo +nightly-2024-12-15 install aquascope_front --git https://github.com/cognitive-engineering-lab/aquascope --tag v0.3.5 --locked\ncargo +nightly-2024-12-15 miri setup\n```\n\nNote 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.\n\n### From Source\n\nIf 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:\n\n```\ncargo install cargo-make --locked\n```\n\nThen you need to install [Depot](https://github.com/cognitive-engineering-lab/depot/), a Javascript build tool, like this:\n\n```\ncurl https://raw.githubusercontent.com/cognitive-engineering-lab/depot/main/scripts/install.sh | sh\n```\n\nThen you can install Aquascope from source like this:\n\n```sh\ngit clone https://github.com/cognitive-engineering-lab/aquascope.git\ncd aquascope\ncargo make install-mdbook\n```\n\n## Usage\n\nFirst, enable `mdbook-aquascope` in your mdBook's `book.toml` like so:\n\n```toml\n# book.toml\n[preprocessor.aquascope]\n```\n\nThen add an Aquascope code block to one of your Markdown source files like this:\n\n    ```aquascope,interpreter\n    #fn main() {\n    let mut s = String::from(\"hello \");`[]`\n    s.push_str(\"world\");`[]`\n    #}\n    ```\n\nFurther documentation on the syntax and configuration of Aquascope blocks will be provided once the interface is more stable.\n\n## Having trouble?\n\nIf you want to use Aquascope but are having trouble finding the relevant information, please leave an issue or email us at \u003cwcrichto@brown.edu\u003e and \u003cgavinleroy@brown.edu\u003e.\n\n## Citation\n\nAquascope 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:\n\n```bibtex\n@article{cgk:aquascope,\n  author = {Crichton, Will and Gray, Gavin and Krishnamurthi, Shriram},\n  title = {A Grounded Conceptual Model for Ownership Types in Rust},\n  year = {2023},\n  issue_date = {October 2023},\n  publisher = {Association for Computing Machinery},\n  address = {New York, NY, USA},\n  volume = {7},\n  number = {OOPSLA2},\n  url = {https://doi.org/10.1145/3622841},\n  doi = {10.1145/3622841},\n  journal = {Proc. ACM Program. Lang.},\n  month = {oct},\n  articleno = {265},\n  numpages = {29},\n  keywords = {Rust, concept inventory, ownership types, program state visualization}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcognitive-engineering-lab%2Faquascope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcognitive-engineering-lab%2Faquascope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcognitive-engineering-lab%2Faquascope/lists"}