summaryrefslogtreecommitdiff
path: root/gui/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-12 13:19:32 -0300
committerGabriel Schneider <[email protected]>2026-11-13 00:41:47 -0300
commit4b4113a0217ee27c78e7efddb66ff5a455d49083 (patch)
treeb848dc1e92c3126dec11da8547e8033ff3990140 /gui/README.md
parenteab50d1c040774351f332a1568fa332c377860bd (diff)
downloadcomputeranim-4b4113a0217ee27c78e7efddb66ff5a455d49083.tar.gz
computeranim-4b4113a0217ee27c78e7efddb66ff5a455d49083.zip
debugger: add a native GUI with live V8 JIT debugging
Diffstat (limited to 'gui/README.md')
-rw-r--r--gui/README.md124
1 files changed, 124 insertions, 0 deletions
diff --git a/gui/README.md b/gui/README.md
new file mode 100644
index 0000000..3bd7d3f
--- /dev/null
+++ b/gui/README.md
@@ -0,0 +1,124 @@
+# ztrace GUI
+
+A separate native application using **ztrace** for control and recordings and
+**canim / Sketchbook** for the view. The libraries stay where they are. It launches
+a real Linux x86-64 process, stops at breakpoints, steps, and browses recorded
+machine state. No gdb subprocess or browser frontend.
+
+The fixed view uses the animation library's instruction cells, operand values,
+flag marks, pointer colors, telescope chains, stack roles and frame spans.
+The current-instruction marker moves between rows; changed registers and stack
+words strike in vermilion, cool, then retain a corner marker. Those changes are
+computed from adjacent recorded moments.
+
+Build with the same Zig toolchain as the rest of computeranim; the sibling
+`sketchbook` and `pardes` checkouts are the existing renderer dependencies:
+
+```sh
+cd gui
+zig build -Doptimize=ReleaseFast
+zig build test -Doptimize=ReleaseFast
+zig build run -Doptimize=ReleaseFast -- --fresh
+```
+
+The build installs `ztrace` alongside `ztrace-gui`; keep the two together.
+Backtick opens the renderer's console:
+
+```text
+launch /absolute/path/to/program arguments
+break main
+continue
+break *0x12345678
+clear 1
+signal 0
+interrupt
+stepi
+nextline
+```
+
+`break` accepts the library's function, file:line and `*address` forms. Its reply
+includes the breakpoint ID. F5 toggles continue/pause, F10 steps one instruction,
+F11 steps to another source line (one instruction when source is unavailable).
+The corresponding buttons work with the mouse. Left/right browse recorded
+moments; End returns to the latest stop. Browsing history does not rewind the
+process. Continuing returns the view to live state. Source stepping can stay in
+a loop on one source line; F5 interrupts it.
+
+The renderer already uses `pause` and `step` for its own timeline. The debugger's
+console names are `interrupt` and `nextline` to keep those separate. Do not use
+renderer playback to replay debugger commands.
+
+Without a launched target, `open /path/to/file.ztrace` views an existing recording.
+Live recordings remain at `/tmp/ztrace-gui-PID-TIMESTAMP.ztrace` after closing.
+Closing the GUI terminates the target it launched. Target stdin is `/dev/null`;
+its stdout and stderr go to the GUI's stderr. There is no terminal emulation.
+
+## How it fits
+
+The GUI starts `ztrace serve RECORDING -- PROGRAM [ARGS]` with private pipes.
+A single controller thread owns every ptrace operation. A `std.Io.concurrent`
+reader feeds a bounded `std.Io.Queue`; `Debugger.on_wait` services that mailbox
+while the target runs. `Debugger.interrupt` requests SIGSTOP and suppresses its
+redelivery. Idle waits use `std.Io.sleep`, while fast steps briefly poll.
+Existing synchronous debugger callers retain their blocking wait.
+
+Replies are small newline-delimited JSON values (`src/trace/control.zig`). A
+`std.Io` task in the GUI reads replies into one mutex-protected latest snapshot.
+The draw loop never waits for ptrace. Each completed command flushes the existing
+recorder before publishing its stop; the GUI reopens that committed snapshot and
+queries `Trace.moment`. File I/O, subprocesses, queues, tasks, locks and timing use
+`std.Io`. Raw Linux calls remain at the ptrace/signal and descriptor boundaries.
+
+New executable mappings are refreshed when a stop's PC is previously unknown,
+so code produced by a JIT is recorded without tracing every syscall. Entering
+code without source lines clears the previous source location in the recording. The GUI
+uses bounded moment queries rather than indexing an entire animation recording.
+It draws the existing canim components without requiring an animation timeline.
+
+## Debug V8
+
+Build V8 on `chaincli-box`, using the `v8-remote-build` skill. Copy d8 together
+with its shared libraries, data/snapshots and build flags to the workstation.
+See [the measured run](bench/RESULTS.md) for the exact revision and limitations.
+
+For the deterministic JIT fixture:
+
+```sh
+./zig-out/bin/ztrace-gui --fresh \
+ --console 'launch /tmp/computeranim-v8-debug-remote/d8 --allow-natives-syntax --no-concurrent-recompilation --no-maglev --print-opt-code --print-opt-code-filter=jitWork /absolute/path/to/computeranim/gui/targets/jit.js' \
+ --console continue 2>/tmp/ztrace-jit.log
+```
+
+`%SystemBreak()` first stops in V8's native runtime after optimizing `jitWork`.
+Find the address of `addl r8,r11` in its printed TurboFan loop body. In the GUI
+console, enter `signal 0`, `break *ADDRESS`, then `continue`. This second stop is
+a software breakpoint inside the generated JavaScript code, not the runtime
+trap. F10 steps through that machine code. Addresses change on each launch.
+The benchmark checks both RIP and that it belongs to an anonymous executable map.
+
+```sh
+# From the repository root, after building gui/:
+python3 gui/bench/steps.py --d8 /tmp/computeranim-v8-debug-remote/d8
+```
+
+The script builds a small C control, tests the JIT breakpoint, steps each target
+1,000 times with identical capture settings, and writes recordings, target logs
+and `results.json` under `/tmp/ztrace-step-bench`. `capture` includes ptrace,
+register/stack/telescope/disassembly capture and recording flush; `roundtrip`
+also includes pipe transport and the Python driver. Neither measures display
+presentation latency. First-break timing includes target startup and initial
+symbol work. Debugger builds use ReleaseFast; target builds remain Debug.
+
+## First-pass boundaries
+
+Fixed layout, one launched target, selected stopped thread, address/function
+breakpoints, and machine-state history. There is no attach UI, thread picker,
+expression evaluator, reverse execution or JavaScript source-map integration.
+Launch arguments are whitespace-separated (no shell quoting). V8 JIT names/code
+movement are not registered automatically: this fixture obtains the address from
+V8's own disassembly and stops before using it. Breakpoints are not relocated if
+V8 moves or discards generated code.
+
+Split DWARF files and V8 source must be retrieved separately for full C++ local
+inspection. The current renderer is a canvas with keyboard controls; it does not
+yet expose debugger rows through a native accessibility tree.