summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-08-25 16:16:15 -0300
committerGabriel Schneider <[email protected]>2026-08-25 16:17:41 -0300
commit0b11540923d5ec2de57fc199c4c9309f838133f5 (patch)
tree81c93e1c34b41fba5d20b7706a8ccb05ee1d0c4e /README.md
parent6b176c598e55a48572e5e508a213491eec122bf4 (diff)
downloadesp32p4-0b11540923d5ec2de57fc199c4c9309f838133f5.tar.gz
esp32p4-0b11540923d5ec2de57fc199c4c9309f838133f5.zip
Move the console into its own binary; the step was fighting the progress display
`zig build interact` shredded the editor's screen with fragments of `[11/13] steps +- console`. The cause is structural, not cosmetic: an interactive step lives for as long as the human does, and `std.Progress` redraws the build runner's step tree on stderr every 80 ms for all of it. std already solves this, and the solution is a lock rather than a flag. `Step.Run` with `stdio == .inherit` holds `io.lockStderr()` for the entire lifetime of the child (std/Build/Step/Run.zig:1588-1592) - the same lock `Progress` must take to draw. A hand-rolled step gets none of that unless it takes the lock itself, and `ConsoleStep` did not. So the console is now a real host program, `tools/console_main.zig`, and `console`/`interact` are `Run` steps on it. `--color off` is not needed and is no longer suggested anywhere. Measured under a real pty (a pipe hides the bug, because progress only draws to a terminal - which is why every earlier end-to-end test here looked clean): zero bytes of progress output across an 11-second session, 3 frames, the editor's `^` modified-marker landing at row 2 after two keystrokes. The second reason for a program is that "just connect" should not imply a build. Once the firmware is in flash the board runs it across resets, so the common case during use is to open the port and nothing else: zig-out/bin/p4-console # the board is already programmed zig-out/bin/p4-console --no-reset # ...and leave a live session running `--no-reset` is the interesting one and it is proven on the die: attaching to the running editor produced 309 bytes with no ESP-ROM banner and zero `boot:` lines, then a `^` frame in response to typing. The session survived a detach and reattach with no repaint, which is exactly what a 11.9 KB/s link wants. `zig build console` is 4 steps and builds no image, no app and no object. It installs `p4-console` itself rather than going through `installArtifact`, so `zig build` alone still lands exactly one file in `zig-out` - verified from an empty tree. Also here: * `tools/console.zig`'s `ModeWatch` tests were reachable by nothing. `zig build test` runs them now; the matcher has to resynchronise when the byte that broke a match is the next match's ESC, which is worth a regression test. * The port-permission advice existed twice, in `failPort` and in the new program. It now lives once, in `tools/serial.zig` beside the code that opens ports, and says nothing about the path so each caller can name its own on the first line.
Diffstat (limited to 'README.md')
-rw-r--r--README.md16
1 files changed, 15 insertions, 1 deletions
diff --git a/README.md b/README.md
index abb94d7..7ccc7b9 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ zig build # compile, link, and emit a flashable image
zig build flash # ...then write it to the chip and run it
zig build run # flash, then print the console (ordered; `flash monitor` is not)
zig build monitor # reset the board and print its console
-zig build console # attach an interactive terminal: keystrokes in, screen out (Ctrl-] detaches)
+zig build console # attach a terminal to whatever is already on the board (Ctrl-] detaches)
zig build interact # flash, then attach that terminal (ordered, like `run`)
zig build reset # just pulse the reset line
zig build size # where every byte of the image went
@@ -19,6 +19,20 @@ against a linker script this `build.zig` generates; the image builder and the se
ordinary Zig code in `tools/`, imported straight into `build.zig`, so they leave no artefacts of
their own. What lands in `zig-out` is one file: the image.
+One exception, and it earns it: `zig build console` also installs `zig-out/bin/p4-console`, a host
+binary that opens the port and nothing else. Run it directly and there is no build runner in the
+picture — which matters, because an interactive step lives for as long as the human does, and
+`std.Progress` would otherwise redraw the build tree over the screen every 80 ms. std solves that
+for child processes by holding `io.lockStderr()` for the child's whole lifetime
+(`std/Build/Step/Run.zig:1588-1592`), which is the same lock `Progress` needs to draw, so both
+spellings are clean; the binary is simply the one that assumes the board is already flashed.
+
+```
+zig-out/bin/p4-console # the board is already programmed; just connect
+zig-out/bin/p4-console --no-reset # ...and do not pulse reset, so a live session survives
+zig-out/bin/p4-console --port /dev/ttyUSB1 --baud 115200
+```
+
## Why it exists
| | ESP-IDF blink | earlier Zig proof-of-concept | this |