Skip to content

Commit

Permalink
v0.3.5 (#149)
Browse files Browse the repository at this point in the history 
* Bump version and move local playground instructions to CONTRIBUTING

* Fix syntax error in action

* Fix syntax error in action
  • Loading branch information
@gavinleroy
gavinleroy authored Jan 9, 2025
1 parent f830872 commit fd7a99b
Show file tree
Hide file tree
Showing 6 changed files with 24 additions and 154 deletions.
30 changes: 16 additions & 14 deletions .github/workflows/standalone.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,25 @@ on:
branches: [standalone-wasm]
types: [labeled,closed]

jobs:
jobs:
update-frontend:
needs: publish-crates
runs-on: ubuntu-latest
if: false # disable for now
steps:
- uses: actions/checkout@v3
- uses: DeterminateSystems/nix-installer-action@main
- uses: DeterminateSystems/magic-nix-cache-action@main
- uses: DeterminateSystems/flake-checker-action@main
- name: Skipping action
run: echo "TODO--bring back frontend tests"

- name: Build Docs and Standalone
run: nix develop .#minimal --command ci-build-pages
# - uses: actions/checkout@v3
# - uses: DeterminateSystems/nix-installer-action@main
# - uses: DeterminateSystems/magic-nix-cache-action@main
# - uses: DeterminateSystems/flake-checker-action@main

- uses: JamesIves/[email protected]
with:
branch: gh-pages
folder: ./frontend/packages/aquascope-standalone/dist
clean: true
clean-exclude: dev
# - name: Build Docs and Standalone
# run: nix develop .#minimal --command ci-build-pages

# - uses: JamesIves/[email protected]
# with:
# branch: gh-pages
# folder: ./frontend/packages/aquascope-standalone/dist
# clean: true
# clean-exclude: dev
4 changes: 4 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ End-to-end testing is done with snapshot testing via [insta](https://github.com/

### Debugging

We use the local playground to debug Aquascope. In one terminal, run `cargo run`, to run the local server. In a separate terminal, navigate to the `frontend` directory and run `depot --no-fullscreen build --watch`. The playground is live at `localhost:5173`, the server will log debug information about the programs you analyze.

> Note, the local playground **does not** run within a sandbox.
To see the full permissions analysis and get all debug output start a server with `cargo make watch`. Then, start an instance of the frontend by running `depot build -w` from the `frontend` directory. The page is served on `localhost:5173`.

## Asking questions
Expand Down
13 changes: 1 addition & 12 deletions Makefile.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ script = "cargo watch -i frontend -x 'install --path crates/aquascope_front --of
script = "cargo watch -w crates/mdbook-aquascope/src -w frontend/packages/aquascope-embed/dist --no-vcs-ignores -x 'install --path crates/mdbook-aquascope --debug --offline'"

[tasks.watch-server]
script = "cargo run --features=no-docker"
script = "cargo run"

[tasks.watch.run_task]
name = ["watch-front", "watch-server", "watch-mdbook"]
Expand All @@ -37,14 +37,3 @@ cargo install --path crates/aquascope_front --locked
[tasks.install-mdbook]
dependencies = ["install-aquascope"]
script = "cargo install --path crates/mdbook-aquascope --locked"

[tasks.playground-front]
script = """
export MIRI_SYSROOT=$(cargo miri setup --print-sysroot)
cd frontend && depot --no-fullscreen build --watch
"""

[tasks.playground.run_task]
dependencies = ["install-aquascope"]
name = ["watch-server", "playground-front"]
parallel = true
125 changes: 0 additions & 125 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,131 +67,6 @@ Then add an Aquascope code block to one of your Markdown source files like this:

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.
<!--
### Available visualizations
Currently, Aquascope supports three types of visualizations:
#### Permission boundaries
Aquascope will determine the permission expected for a path usage and display this along with the actual permissions on the path. Unsatisfied permissions provide additional information on hover to help explain the discrepancy.
<table>
<tr>
<td>
<pre>
<code style="display: block;">
```aquascope,boundaries
fn main() {
let mut x = 1;
let y = &mut x;
println!("{} = {}", x, *y);
}```
</code>
</pre>
</td>
<td>
<img src="https://user-images.githubusercontent.com/20209337/215321806-bba27857-70ed-4371-98bd-5e7b5dfd884f.png" />
</td>
</tr>
</table>
#### Permission steps
Tracking how permissions change throughout a program is difficult, especially when factors such as [liveness](https://en.wikipedia.org/wiki/Live-variable_analysis) influence the static analysis. Aquascope will insert _steps_ that show how and _why_ permissions change.
<table>
<tr>
<td>
<pre>
<code style="display: block;">
```aquascope,stepper
fn main() {
let mut x = 1;
let y = &mut x;
println!("{} = {}", x, *y);
}```
</code>
</pre>
</td>
<td>
<img src="https://user-images.githubusercontent.com/20209337/215321846-377f3adb-9e4b-4d9c-8223-fd344296b32d.png" />
</td>
</tr>
</table>
#### Runtime execution
Program state visualization is a well-known tool that visualizes the runtime execution of a program. With Aquascope, you can specify which states of a program you'd like to show, and even run programs that don't pass the borrow checker!
<table>
<tr>
<td>
<pre>
<code style="display: block;">
```aquascope,interpreter,concreteTypes=true
fn main() {
let m1 = String::from("Hello");
let m2 = String::from("world");`[]`
greet(&m1, &m2); // note the ampersands
let s = format!("{} {}", m1, m2);
}
fn greet(g1: &String, g2: &String) { // note the ampersands
`[]`println!("{} {}!", g1, g2);
}```
</code>
</pre>
</td>
<td>
<img src="https://user-images.githubusercontent.com/20209337/215325005-6c613d98-8b69-45f3-879a-c68c86940f83.png" />
</td>
</tr>
</table>
### Aquascope annotations
Aquascope provides a set of annotations for simple customization. Similar to mdBook, any line of code with a preceding `#` is _hidden_. Additionally, each visualization may provide its own set of specific annotations, these are outlined below.
#### Permission steps
Visualizing permission steps can be quite intrusive but oftentimes you may want to just focus on a handful of lines, or even specific paths. This can be achieved by providing a _step annotation_ at the end of a line. For example, the annotation `` `(focus,paths:x)` `` indicates that this line should be focused (shown by default) and all paths except `x` are hidden in a dropdown.
> Note, these annotations are line specific. The default is to show _all_ lines and paths unless something is specified.
<table>
<tr>
<td>
<pre>
<code style="display: block;">
```aquascope,stepper
# fn main() {
let mut x = 1;
let y = &x; `(focus,paths:x)`
let z = *y; `(focus,paths:x)`
x += z;
# }```
</code>
</pre>
</td>
<td>
<kbd>
<img src="https://user-images.githubusercontent.com/20209337/215325679-5ffc4ea8-6246-4d2e-965c-3baddfc26ad4.gif" />
</kbd>
</td>
</tr>
</table>
-->

## 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]>.
Expand Down
4 changes: 2 additions & 2 deletions crates/aquascope_workspace_utils/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ authors = [
"Will Crichton <[email protected]>",
"Gavin Gray <[email protected]>"
]
version = "0.3.4"
version = "0.3.5"
license = "MIT"
edition = "2021"
description = "Handy utilities for working in the Aquascope workspace"
Expand All @@ -20,4 +20,4 @@ include = [
[dependencies]
toml = "0.5"
anyhow = "1"
serde = { workspace = true }
serde = { workspace = true }
2 changes: 1 addition & 1 deletion crates/mdbook-aquascope/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ authors = [
]
description = "Interactive Aquascope editor for your mdBook"
license = "MIT"
version = "0.3.4"
version = "0.3.5"
edition = "2021"
include = [
"src/**/*",
Expand Down

0 comments on commit fd7a99b

Please sign in to comment.