-
Notifications
You must be signed in to change notification settings - Fork 40
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: add
triton-tui
, a TUI for debugging programs in Triton assembly
- Loading branch information
Showing
33 changed files
with
4,350 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
{ | ||
"keybindings": { | ||
"Home": { | ||
"<q>": "Quit", | ||
"<Ctrl-c>": "Quit", | ||
"<Ctrl-z>": "Suspend", | ||
|
||
"<h>": "Mode::Help", | ||
"<m>": "Mode::Memory", | ||
|
||
"<c>": "Continue", | ||
"<s>": "Step", | ||
"<n>": "Next", | ||
"<f>": "Finish", | ||
"<u>": "Undo", | ||
"<r>": "Reset", | ||
|
||
"<t><a>": "ToggleAll", | ||
"<t><t>": "ToggleTypeHintDisplay", | ||
"<t><c>": "ToggleCallStackDisplay", | ||
"<t><s>": "ToggleSpongeStateDisplay", | ||
"<t><i>": "ToggleInputDisplay" | ||
}, | ||
"Help": { | ||
"<q>": "Quit", | ||
"<Ctrl-c>": "Quit", | ||
"<Ctrl-z>": "Suspend", | ||
|
||
"<h>": "HideHelpScreen", | ||
"<m>": "Mode::Memory", | ||
"<esc>": "Mode::Home" | ||
}, | ||
"Memory": { | ||
"<q>": "Quit", | ||
"<Ctrl-c>": "Quit", | ||
"<Ctrl-z>": "Suspend", | ||
|
||
"<h>": "Mode::Help", | ||
"<m>": "Mode::Home", | ||
"<esc>": "Mode::Home" | ||
} | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
export TRITON_TUI_CONFIG=$(pwd)/.config | ||
export TRITON_TUI_DATA=$(pwd)/.data | ||
export TRITON_TUI_LOG_LEVEL=debug |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
[package] | ||
name = "triton-tui" | ||
description = "A TUI that helps debugging programs written for Triton VM." | ||
|
||
version.workspace = true | ||
edition.workspace = true | ||
authors.workspace = true | ||
license.workspace = true | ||
homepage.workspace = true | ||
documentation.workspace = true | ||
repository.workspace = true | ||
|
||
[dependencies] | ||
arbitrary.workspace = true | ||
better-panic = "0.3" | ||
clap = { version = "4", features = ["derive", "cargo", "wrap_help", "unicode", "string", "unstable-styles"] } | ||
color-eyre = "0.6" | ||
config = "0.13" | ||
crossterm = { version = "0.27", features = ["serde", "event-stream"] } | ||
derive_deref = "1" | ||
directories = "5" | ||
fs-err = "2.0" | ||
futures = "0.3" | ||
human-panic = "1" | ||
itertools.workspace = true | ||
lazy_static.workspace = true | ||
libc = "0.2" | ||
num-traits.workspace = true | ||
ratatui = { version = "0.25", features = ["serde", "macros"] } | ||
serde.workspace = true | ||
serde_json = "1.0" | ||
signal-hook = "0.3" | ||
strip-ansi-escapes = "0.2" | ||
strum.workspace = true | ||
tokio = { version = "1", features = ["full"] } | ||
tokio-util = "0.7" | ||
tracing = "0.1" | ||
tracing-error = "0.2" | ||
tracing-subscriber = { version = "0.3", features = ["env-filter", "serde"] } | ||
triton-vm = { path = "../triton-vm" } | ||
tui-textarea = "0.4" | ||
|
||
[dev-dependencies] | ||
assert2.workspace = true | ||
pretty_assertions.workspace = true | ||
proptest.workspace = true | ||
proptest-arbitrary-interop.workspace = true | ||
rexpect = "0.5" | ||
test-strategy.workspace = true | ||
|
||
[[bin]] | ||
name = "triton-tui" | ||
path = "src/main.rs" | ||
|
||
[[test]] | ||
name = "integration" | ||
path = "tests/tests.rs" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
# Triton TUI | ||
|
||
A TUI to run and debug programs written for Triton VM. | ||
|
||
<img alt="Example run of Triton TUI" src="./examples/triton-tui.gif" width="800" /> | ||
|
||
## Getting Started | ||
|
||
Triton TUI tries to be helpful 🙂. List possible (and required) arguments with `triton-tui --help`. In the TUI, press `h` to access the help screen. | ||
|
||
The [example program](./examples/program.tasm), serving as the tutorial, can be run with | ||
|
||
```sh | ||
triton-tui --program examples/program.tasm | ||
``` | ||
|
||
## Installation | ||
|
||
Through [crates.io](https://crates.io/crates/triton-tui): | ||
|
||
```sh | ||
cargo install triton-tui | ||
``` | ||
|
||
Locally: | ||
|
||
```sh | ||
cargo install --path . | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,62 @@ | ||
fn main() { | ||
let git_dir = maybe_get_git_dir(); | ||
trigger_rebuild_if_head_or_some_relevant_ref_changes(git_dir); | ||
|
||
let git_output = std::process::Command::new("git") | ||
.args(["describe", "--always", "--tags", "--long", "--dirty"]) | ||
.output() | ||
.ok(); | ||
let git_info = git_output | ||
.as_ref() | ||
.and_then(|output| std::str::from_utf8(&output.stdout).ok().map(str::trim)); | ||
let cargo_pkg_version = env!("CARGO_PKG_VERSION"); | ||
|
||
// Default git_describe to cargo_pkg_version | ||
let mut git_describe = String::from(cargo_pkg_version); | ||
|
||
if let Some(git_info) = git_info { | ||
// If the `git_info` contains `CARGO_PKG_VERSION`, we simply use `git_info` as it is. | ||
// Otherwise, prepend `CARGO_PKG_VERSION` to `git_info`. | ||
if git_info.contains(cargo_pkg_version) { | ||
// Remove the 'g' before the commit sha | ||
let git_info = &git_info.replace('g', ""); | ||
git_describe = git_info.to_string(); | ||
} else { | ||
git_describe = format!("v{cargo_pkg_version}-{git_info}"); | ||
} | ||
} | ||
|
||
println!("cargo:rustc-env=TRITON_TUI_GIT_INFO={git_describe}"); | ||
} | ||
|
||
fn maybe_get_git_dir() -> Option<String> { | ||
let git_output = std::process::Command::new("git") | ||
.args(["rev-parse", "--git-dir"]) | ||
.output() | ||
.ok(); | ||
git_output.as_ref().and_then(|output| { | ||
std::str::from_utf8(&output.stdout) | ||
.ok() | ||
.and_then(|s| s.strip_suffix('\n').or_else(|| s.strip_suffix("\r\n"))) | ||
.map(str::to_string) | ||
}) | ||
} | ||
|
||
fn trigger_rebuild_if_head_or_some_relevant_ref_changes(git_dir: Option<String>) { | ||
if let Some(git_dir) = git_dir { | ||
let git_path = std::path::Path::new(&git_dir); | ||
let refs_path = git_path.join("refs"); | ||
if git_path.join("HEAD").exists() { | ||
println!("cargo:rerun-if-changed={git_dir}/HEAD"); | ||
} | ||
if git_path.join("packed-refs").exists() { | ||
println!("cargo:rerun-if-changed={git_dir}/packed-refs"); | ||
} | ||
if refs_path.join("heads").exists() { | ||
println!("cargo:rerun-if-changed={git_dir}/refs/heads"); | ||
} | ||
if refs_path.join("tags").exists() { | ||
println!("cargo:rerun-if-changed={git_dir}/refs/tags"); | ||
} | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
{ | ||
"individual_tokens" : [497, 598, 699], | ||
"digests" : [[3, 4, 5, 6, 7], [4, 5, 6, 7, 8]], | ||
"ram" : {"5": 50, "6": 60, "7": 70} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
//! Demonstrates use and functionality of the Triton VM TUI. | ||
//! | ||
//! Serves as the tutorial: execution intentionally fails at first, hopefully | ||
//! encouraging you to play around. :) The inline comments should make matters trivial. | ||
//! | ||
//! Press `h` in Triton VM TUI to show the help screen. | ||
|
||
// Let's start! | ||
push 3 | ||
hint loop_counter = stack[0] // Current stack can be annotated to help debugging. | ||
break | ||
|
||
call my_loop | ||
hint numbers: array = stack[1..4] // Annotations also work with ranges. | ||
|
||
call check_result | ||
call write_to_memory | ||
call read_from_secret_input | ||
call sponge_instructions | ||
halt | ||
|
||
my_loop: | ||
dup 0 push 0 eq skiz return | ||
read_io 3 // call with `--input ./public_input.txt` | ||
mul mul | ||
break | ||
dup 0 write_io 1 | ||
swap 1 push -1 add recurse | ||
|
||
check_result: // Try enabling | ||
// pop 1 // <- this line for | ||
assert // <- this assertion to work. | ||
return // Hot reload & reset of the VM is `r`. | ||
|
||
write_to_memory: | ||
push 42 | ||
write_mem 2 // You can inspect memory with `m`. | ||
pop 1 | ||
return | ||
|
||
read_from_secret_input: | ||
divine 3 // flag `--non-determinism ./non_determinism.json` | ||
mul mul | ||
swap 5 | ||
divine_sibling pop 5 | ||
divine_sibling hash | ||
return | ||
|
||
sponge_instructions: | ||
sponge_init // Show the Sponge state with `t,s`. | ||
sponge_squeeze | ||
return |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
2 3 5 | ||
17 19 42 | ||
1 1 1 |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
Output triton-tui.gif | ||
|
||
Set Shell zsh | ||
Set Width 2000 | ||
Set Height 1000 | ||
|
||
Sleep 1s | ||
Hide | ||
Type "triton-tui -p ./program.tasm -i public_input.txt -n non_determinism.json" | ||
Show | ||
Sleep 1s | ||
Enter | ||
Sleep 3s | ||
|
||
Type "c" | ||
Sleep 2s | ||
Type "c" | ||
Sleep 2s | ||
Type "c" | ||
Sleep 2s | ||
Type "ti" | ||
Type "tc" | ||
Sleep 2s | ||
Type "ff" | ||
Sleep 3s | ||
|
||
Type "m" | ||
Sleep 3s | ||
Enter | ||
Type "30" | ||
Enter | ||
Sleep 3s | ||
|
||
Hide | ||
Type "q" | ||
Ctrl+D |
Oops, something went wrong.