Krolyxon
Commit 1504706

Branches

Tags

Refs →

bench511504706

README: document the GUI; add CI for Linux, Windows and macOS

Author
krolyxon
Date
2026-10-31 23:33 +0530
Parent
42b14d3
Commit
1504706137579aee6a40e39410825b713d8a0aac

+126 −11

7 files changed

Browse files Patch
−Context 3+
  1. A .github/workflows/ci.yml +31 −0
  2. M README.md +95 −11
  3. A docs/screenshots/gui_breakpoint_light.png
  4. A docs/screenshots/gui_debug.png
  5. A docs/screenshots/gui_edit.png
  6. A docs/screenshots/gui_errors.png
  7. A docs/screenshots/gui_peripherals.png
A .github/workflows/ci.yml View
@@ -0,0 +1,31 @@
1+name: CI
2+
3+on:
4+ push:
5+ pull_request:
6+
7+env:
8+ CARGO_TERM_COLOR: always
9+
10+jobs:
11+ build:
12+ name: ${{ matrix.os }}
13+ strategy:
14+ fail-fast: false
15+ matrix:
16+ os: [ubuntu-latest, windows-latest, macos-latest]
17+ runs-on: ${{ matrix.os }}
18+ steps:
19+ - uses: actions/checkout@v4
20+ - uses: dtolnay/rust-toolchain@stable
21+ with:
22+ components: clippy
23+ - name: Install Linux GUI dependencies
24+ if: runner.os == 'Linux'
25+ run: |
26+ sudo apt-get update
27+ sudo apt-get install -y libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev
28+ - uses: Swatinem/rust-cache@v2
29+ - run: cargo build --workspace --release
30+ - run: cargo test --workspace
31+ - run: cargo clippy --workspace --all-targets -- -D warnings
M README.md View
@@ -1,11 +1,14 @@
1−# bench51 — a TUI 8051 assembler, simulator & debugger
1+# bench51 — an 8051 assembler, simulator & debugger
22
3−A small, Keil µVision-style IDE for the Intel 8051 that runs in your terminal.
4−Write assembly in the built-in editor, assemble it, inspect the listing and
5−Intel HEX output, then run, pause and single-step the program while watching
6−registers, SFRs, memory, ports, timers, interrupts and the serial port.
3+A small, Keil µVision-style IDE for the Intel 8051, in two flavours: a TUI
4+that runs in your terminal, and a desktop GUI (`bench51-gui`) laid out like
5+µVision. Write assembly in the built-in editor, assemble it, inspect the
6+listing and Intel HEX output, then run, pause and single-step the program
7+while watching registers, SFRs, memory, ports, timers, interrupts and the
8+serial port.
79
8−Built in Rust with [ratatui](https://ratatui.rs). It is a learning tool, not a
10+Built in Rust with [ratatui](https://ratatui.rs) and
11+[egui](https://github.com/emilk/egui). It is a learning tool, not a
912 cycle-exact replacement for a vendor simulator.
1013
1114 ![Debugging serial_hello.asm: source, registers, peripherals, IRAM and the UART console](docs/screenshots/debug_serial.png)
@@ -81,6 +84,82 @@ cargo run --release -- --assemble prog.asm -o out.hex --lst out.lst
8184 `--clock <MHz>` sets the oscillator frequency used for the elapsed-time display
8285 (default 11.0592).
8386
87+## Desktop GUI
88+
89+`bench51-gui` is the same assembler and simulator behind a µVision-style
90+window: menus and toolbar, a Project window, the editor with breakpoint
91+gutter, Build Output, and in a debug session the Registers, Disassembly,
92+Memory, Symbols, UART #1, Ports, Timers and Interrupts windows. Every window
93+docks and tabs wherever you drag it; the edit and debug layouts are
94+remembered separately, as in µVision. It follows a monochrome,
95+dot-matrix design (Space Grotesk, Space Mono and Doto, bundled) in a dark and
96+a light theme.
97+
98+![Debug session in the GUI: registers, source with the PC, disassembly, memory and UART #1](docs/screenshots/gui_debug.png)
99+
100+<table>
101+ <tr>
102+ <td width="50%"><img src="docs/screenshots/gui_edit.png" alt="Editor and Keil-style build output"></td>
103+ <td width="50%"><img src="docs/screenshots/gui_breakpoint_light.png" alt="Stopped at a breakpoint in a timer ISR, light theme"></td>
104+ </tr>
105+ <tr>
106+ <td align="center"><sub>Editor + build output</sub></td>
107+ <td align="center"><sub>Breakpoint in a timer ISR, light theme</sub></td>
108+ </tr>
109+ <tr>
110+ <td width="50%"><img src="docs/screenshots/gui_peripherals.png" alt="Ports, timers and interrupts windows docked side by side"></td>
111+ <td width="50%"><img src="docs/screenshots/gui_errors.png" alt="Assembler errors in the gutter and Build Output"></td>
112+ </tr>
113+ <tr>
114+ <td align="center"><sub>Peripheral windows, rearranged</sub></td>
115+ <td align="center"><sub>Assembler errors</sub></td>
116+ </tr>
117+</table>
118+
119+```bash
120+cargo install --path crates/bench51-gui # installs `bench51-gui`
121+
122+cargo run --release -p bench51-gui # welcome screen
123+cargo run --release -p bench51-gui -- examples/*.asm # open several files
124+cargo run --release -p bench51-gui -- --theme light firmware.hex
125+```
126+
127+`--theme system|dark|light` overrides the theme chosen in View → Theme, and
128+`--clock <MHz>` the Xtal set in Project → Options for Target.
129+
130+The keys are µVision's, with the TUI's as aliases:
131+
132+| Key | Action |
133+| --- | --- |
134+| F7 | build target (also writes `.lst` and `.hex` next to a saved file) |
135+| Ctrl-F5 / F4 | start / stop the debug session |
136+| F5 | run / stop |
137+| F11 / F10 | step into / step over |
138+| Ctrl-F11 / F12 | step out |
139+| Ctrl-F10 / F8 | run to the cursor line |
140+| F9 / Ctrl-Shift-F9 | toggle breakpoint / remove all breakpoints |
141+| F6 | reset the CPU |
142+| Ctrl-N / Ctrl-O / Ctrl-S / Ctrl-W | new / open / save / close |
143+| Ctrl-F | find |
144+| F1 | all shortcuts |
145+
146+Click the gutter to toggle a breakpoint, double-click a byte in Memory to
147+change it, click a pin in Ports to hold it low from outside, and click the
148+bit chips in Registers, Timers and Interrupts to flip SFR bits. Files can be
149+dropped onto the window.
150+
151+On Linux it runs on Wayland and X11 and uses the XDG desktop portal for file
152+dialogs. To add it to your application launcher:
153+
154+```bash
155+install -Dm644 crates/bench51-gui/assets/bench51-gui.desktop ~/.local/share/applications/bench51-gui.desktop
156+install -Dm644 crates/bench51-gui/assets/bench51-gui.svg ~/.local/share/icons/hicolor/scalable/apps/bench51-gui.svg
157+```
158+
159+It also builds for Windows and macOS. On Debian or Ubuntu, first install the
160+packages egui needs: `libxcb-render0-dev libxcb-shape0-dev
161+libxcb-xfixes0-dev libxkbcommon-dev libssl-dev`.
162+
84163 ## Keys
85164
86165 | Key | Action |
@@ -133,10 +212,15 @@ Letter shortcuts work too, for terminals that swallow function keys:
133212 ## Development
134213
135214 ```bash
136−cargo test # assembler, CPU, peripheral and example-program tests
137−cargo clippy
215+cargo test --workspace # assembler, CPU, peripheral, session and example-program tests
216+cargo clippy --workspace --all-targets
138217 ```
139218
140−Code layout: `src/isa.rs` (opcode table shared by everything), `src/asm/`
141−(assembler, listing, Intel HEX), `src/sim/` (CPU, peripherals, disassembler),
142−`src/ui/` (ratatui front end).
219+Code layout:
220+
221+- `crates/bench51-core/`, shared by both front ends: `isa.rs` (opcode
222+ table), `asm/` (assembler, listing, Intel HEX), `sim/` (CPU, peripherals,
223+ disassembler), `session.rs` (build, run, step and breakpoints),
224+ `syntax.rs` (highlighting tokens), `files.rs` (HEX loading)
225+- `src/` is the `bench51` TUI (ratatui).
226+- `crates/bench51-gui/` is the `bench51-gui` desktop app (egui).
A docs/screenshots/gui_breakpoint_light.png View

[Binary file]

A docs/screenshots/gui_debug.png View

[Binary file]

A docs/screenshots/gui_edit.png View

[Binary file]

A docs/screenshots/gui_errors.png View

[Binary file]

A docs/screenshots/gui_peripherals.png View

[Binary file]