miden-debug 0.9.0

An interactive debugger for Miden VM programs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# lit / FileCheck debugger tests

End-to-end tests that drive `miden-debug` over small Miden Assembly programs and
check its output with [`litcheck`](https://crates.io/crates/litcheck) (a
pure-Rust implementation of LLVM `lit` + `FileCheck`).

The debugger only loads compiled packages. The lit harness builds the local
`compile-masm` helper and uses it to assemble each `.masm` fixture into a
temporary `.masp` package before running `miden-debug`.

## Layout

```
tests/lit/
  lit.suite.toml     # suite config: only *.test files are test entry points
  add.masm           # a MASM program ...
  add.test           # ... and the test that debugs it
  breakpoint.masm
  breakpoint.test
  error.masm
  error.test
```

## How a test works

A `.test` file is, at once:

1. A **command script** for the debugger. `miden-debug --commands <file>` runs
   each non-`#` line as a REPL command (gdb's `-x` / lldb's `-s`). Lines starting
   with `#` are ignored by the debugger.
2. A **FileCheck input**. `filecheck` reads the `# CHECK:` lines and matches them
   against the debugger's output.
3. A **lit test**. The `# RUN:` line tells lit what to execute.

For example, `add.test`:

```text
# RUN: compile-masm %S/add.masm -o %t.masp
# RUN: miden-debug --commands %s %t.masp 2>&1 | filecheck %s

continue
stack

# CHECK: Program terminated successfully
# CHECK: [0] 7
```

`%s` is the test file, `%S` its directory, and `%t` is a per-test temporary file.
The first `RUN` line compiles `add.masm`; the second loads the resulting program
in the debugger, runs the `continue` and `stack` commands, and pipes the output
to `filecheck`, which verifies the program finished and left `7` on top of the
operand stack.

## Running

```sh
cargo make test-lit
```

This installs the lit tools, builds `miden-debug` with the `repl` feature
(needed for `--commands`), builds the local MASM-to-package helper, installs the
binaries into `./bin`, and runs the suite via `litcheck lit run`.

## Adding a test

Drop a new `<name>.masm` program under `tests/lit/` and a `<name>.test` beside it
with the `RUN`/`CHECK` directives and debugger commands. Two MASM facts to keep
in mind:

- The operand stack starts as 16 padding zeros and is always shown padded.
- The VM requires at most 16 elements at program end — fold results into a
  padding zero (e.g. a trailing `add`) to terminate cleanly, or assert on the
  resulting error like `error.test`.

Prefer asserting on stable facts (a known computed result) over incidental
formatting.