From 2ddceb90430806905988ae9bef4b3d921f75515e Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 00:03:25 -0300 Subject: README: the incremental reload loop and its limits `zig build lib --watch -fincremental --debounce 0` brings edit to frame from 0.53 s to 43 ms on a small sketch and from about 1.2 s to 55 ms on drat-meout (medians of 10 on a loaded machine; compile 7-10 ms instead of 0.3-1 s). The hot-reload paragraph says so, and what it costs on Zig 0.17.1: a new linker behind a host workaround, what to do if a reload runs the wrong code, a larger library, resident compilers, and a multi-file save that may build twice. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- README.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 626a4e4..d7a2838 100644 --- a/README.md +++ b/README.md @@ -597,7 +597,18 @@ object. - **Hot reload.** It watches the library file and loads each new build through a symlink with a fresh name (a build must replace the file, as `zig build` - does, not rewrite it in place). + does, not rewrite it in place). `zig build lib --watch -fincremental + --debounce 0` makes a reload take tens of milliseconds instead of a second: + Zig recompiles only what the edit changed, and starts as soon as a file is + saved instead of 50 ms later. Its limits, with Zig 0.17.1: the incremental + linker is new, and a library of it that does not link libc loads only + through a host workaround that Zig 0.18 makes unnecessary; if a reload ever runs code other than what you + wrote, stop the watch and rebuild without `-fincremental`. The library is + larger (27 MB instead of 10 for a small sketch), the watching compilers + stay in memory (about 300 MB for a small sketch, 1.3 GB for a game with C + and shaders), and a save that touches several files may build more than + once. The cache grows with each start of the watch (65 MB for a game), + not with edits. - **State file.** `.state` holds the live state plus 7 snapshot slots, shared via `MAP_SHARED`. Its header carries the reflected layout, so a layout change migrates every slot field by field, with enums matched by tag -- cgit v1.3