diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 01:13:36 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | 1ce323f2f21b94f9c4fc4e7a6986612cf30cf183 (patch) | |
| tree | 87342ff0ca8bf9e08ba8060ffddd6a64bfca7adf /build.zig | |
| parent | 62cce7f3d96aa054b2bc2055dce86dd8e4205256 (diff) | |
| download | sketchbook-1ce323f2f21b94f9c4fc4e7a6986612cf30cf183.tar.gz sketchbook-1ce323f2f21b94f9c4fc4e7a6986612cf30cf183.zip | |
The present lives in the save: one file a sketch, the state file gone
A sketch kept its live State in a mapped state file and its history in
a sessions database beside it. Now the database is the save, the one
file: the present is its newest keyframe and the frames logged after
it, and a run starts there (Sessions.present: the newest session with a
keyframe, its last keyframe loaded and the frames after it read). Host
restores it (migrating across a layout change, as a seek does) and
replays the frames through `update`, unlogged, `started` as it was fed
(true only from a session's first frame); played by another build, they
are not replayed, and the run says how many frames that was. The run's
first keyframe then starts from the present's pages, so a session costs
what changed since the last one. --fresh still starts from defaults,
the save untouched.
State is process memory (memory.State: one page-aligned allocation, its
layout, and its layout header for the stretches); a reload's adopt
allocates the new layout's defaults and migrates the old bytes into it,
and returns null when unchanged. Gone: StateFile, its slots, used bits,
resize, dropSnapshots and the adopt that rewrote a file's header; the
sketch-facing `Host.state` keeps `layout`; Timeline restores into
`state.live()`. `adopt` no longer runs `init`: openPresent does when
there is no present.
Every run saves: the database is opened in a file for every run but a
scripted one from fresh state (memory, nothing on disk) and an export
(none). So release builds keep their State as before, and marks and
clips work there; `.record` keeps or trims history (next change).
The save is `<stem>.xitdb`, `<stem>` being --state without `.xitdb` or
`.state`: `--state x.state` and `--state x.xitdb` name the same save.
Defaults: `.sketchbook/<name>.xitdb` under zig build run, and
`$XDG_DATA_HOME/<name>/<name>.xitdb`. A sketch's appended files are
`<stem>.<name>` (micscope's takes: `.sketchbook/micscope.take-3.f32`,
where Phase 1 wrote `micscope.state.take-3.f32`; that naming never left
this workspace, so nothing of the user's is renamed). A scripted run
from fresh state or an export appends to `<stem>.<pid>.<name>` and
removes those at exit; the private state file and the exit's moving of
files by prefix are gone from root.zig.
Old state files: in a new save, `<stem>.state` (one slot or eight, any
of the three formats) is imported once: slot 0 becomes the present (in
today's layout), slots 1-7 marks "1".."7" (migrated to it, as before);
the file is read through a read-only mapping and left exactly as it
was. It is never read again: the save then has a session. A file that
is no state file is said and left. .sketchbook/'s move of an older
build's `<stem>.state` from beside it stays, now by stem.
sketchbook-probe is deleted (86 lines, its build step, Sketchbook's
probe_exe, App.addProbe): it mapped the state file. Reading the save
instead would show State as of the newest keyframe, up to a minute old,
never the frames after it, which only `update` can turn into State;
and it would need a read-only open the host has no other use for. The
planned 9P state/ tree reads live State from the process.
A kill -9 now loses what the session log always lost: the frames not
yet committed (under a second: in test-kill 15 of 255 frames, the
next run starting from frame 240's State), keyframes and marks queued
since the last commit (a mark commits at once, synced), the session's
end time and an open clip's end. The mapped file lost nothing to a
kill. A power loss reopens at the last commit the disk holds whole
(`mend`); commits are fsynced only for marks and at exit, so what the
OS had not written back is lost (not measured); the mapped file, never
synced, could tear page by page.
Measured: drat-meout's State, 20 extra jump keyframes in a 2,400-frame
script, 100,708 B more than the same frames without them: about 5 KB
a keyframe, where the whole State (17.7-20 KiB) was written each time.
Tests: zig build test, 168/168 steps. test-kill runs for a recording
and a non-recording build, and the second run checks `updates` is 240
(replayed), not only the session's frame count. test-paths: the XDG
directory holds `replay.xitdb` alone; .sketchbook/ holds `.gitignore`
and `replay.xitdb`; the next run's State is the one the last left; an
older `old.state` beside .sketchbook/ is moved in once, never over a
file, and left as it was when it is no state file. test-same: a run
from fresh state leaves no file at all. Rewritten: memory.zig's state
file tests as State's (migrate, unchanged) and OldState's (refused
untouched; drat-meout's v1 fixture imports every value, the file
unchanged), Host's snapshot import as importOld (State live, two marks,
the file byte for byte as it was), Host's setup test without a file,
the timeline test on a State. micscope 67/67, 10/10; spheres 75/75,
3/3; noc e2e 292/292; the drat-meout copy 87/87, 30/30.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'build.zig')
| -rw-r--r-- | build.zig | 99 |
1 files changed, 40 insertions, 59 deletions
@@ -6,7 +6,7 @@ //! //! const sb = sketchbook.init(b, .{ .target = target, .optimize = optimize }); //! const app = sb.app(.{ .name = "demo", .root_source_file = b.path("src/main.zig") }); -//! _ = app.addSteps(.{}); // run, lib, probe, e2e, test, install; +//! _ = app.addSteps(.{}); // run, lib, e2e, test, install; //! // web and serve with `.web = .{}` //! //! or pick the pieces: `app.addLibrary()`, `app.addExecutable()`, @@ -110,18 +110,7 @@ pub fn build(b: *Build) void { }); b.installArtifact(host_exe); - const probe = b.addExecutable(.{ - .name = "sketchbook-probe", - .root_module = b.createModule(.{ - .root_source_file = b.path("src/host/probe.zig"), - .target = target, - .optimize = optimize, - .imports = &.{.{ .name = "abi", .module = abi }}, - }), - }); - b.installArtifact(probe); - - var sb: Sketchbook = .{ .b = b, .target = target, .optimize = optimize, .modules = .{ .abi = abi, .sketch = sketch, .host = host, .tracy = tracy, .vector = undefined, .scope = undefined, .anim = undefined, .gltf = gltf }, .host_exe = host_exe, .probe_exe = probe, .gltf_generator = gltf_generator, .web = b.path("web"), .glsl = b.path("src/glsl.zig"), .tools = b.path("tools"), .anim_dir = b.path("src/anim"), .gltf_render_dir = b.path("src/gltf_render"), .script_optimize = optimize, .shared = .create(b) }; + var sb: Sketchbook = .{ .b = b, .target = target, .optimize = optimize, .modules = .{ .abi = abi, .sketch = sketch, .host = host, .tracy = tracy, .vector = undefined, .scope = undefined, .anim = undefined, .gltf = gltf }, .host_exe = host_exe, .gltf_generator = gltf_generator, .web = b.path("web"), .glsl = b.path("src/glsl.zig"), .tools = b.path("tools"), .anim_dir = b.path("src/anim"), .gltf_render_dir = b.path("src/gltf_render"), .script_optimize = optimize, .shared = .create(b) }; // Vector graphics: built with the same shader step apps use. Both forms // of its shaders are exported, so apps' web builds can swap them too. @@ -389,17 +378,22 @@ pub fn build(b: *Build) void { test_step.dependOn(&reload.step); // A session survives a kill -9 up to its last commit: 255 frames - // played, four commits of 60 made, the fifth lost with the process. - // Its sketch records in every mode, so the test does in release builds too. + // played, four commits of 60 made, the fifth lost with the process; the + // next run starts from frame 240's State, replayed. Its sketch records + // in every mode, so the test does in release builds too; and a sketch + // that does not record keeps its present all the same. const recorded = sb.app(.{ .name = "replay", .root_source_file = b.path("test/replay.zig"), .record = true }).addLibrary(); + const unrecorded = sb.app(.{ .name = "replay", .root_source_file = b.path("test/replay.zig"), .record = false }).addLibrary(); const killed = b.addSystemCommand(&.{ "sh", "-c", \\set -e \\db="${3%.state}.xitdb" - \\rm -f "$3" "$db" - \\if "$0" --headless --script "$1" --state "$3" "$4"; then echo "killed run exited"; exit 1; else test $? = 137; fi - \\"$0" --headless --script "$2" --state "$3" "$4" + \\for lib in "$4" "$5"; do + \\rm -f "$db" + \\if "$0" --headless --script "$1" --state "$3" "$lib"; then echo "killed run exited"; exit 1; else test $? = 137; fi + \\"$0" --headless --script "$2" --state "$3" "$lib" \\test "$(stat -c %s "$db")" -lt 1048576 - \\rm -f "$3" "$db" + \\rm -f "$db" + \\done }); killed.setName("a session survives kill -9"); killed.addArtifactArg(host_exe); @@ -407,6 +401,7 @@ pub fn build(b: *Build) void { killed.addFileArg(b.path("test/killed.script")); _ = killed.addOutputFileArg("kill.state"); killed.addArtifactArg(recorded); + killed.addArtifactArg(unrecorded); killed.has_side_effects = true; killed.expectExitCode(0); test_step.dependOn(&killed.step); @@ -468,7 +463,7 @@ pub fn build(b: *Build) void { // A script run twice records the same database but for the wall clock's // times: the log and the keyframes follow from the script alone. From - // fresh state it records in memory: no database at all. + // fresh state it records in memory: no file at all. const same_sessions = b.addExecutable(.{ .name = "same_sessions", .root_module = b.createModule(.{ .root_source_file = b.path("test/same_sessions.zig"), .target = target, @@ -482,7 +477,7 @@ pub fn build(b: *Build) void { \\"$0" --headless --script "$1" --state "$d/b.state" "$4" \\"$2" "$d/a.xitdb" "$d/b.xitdb" \\"$0" --headless --fresh --script "$1" --state "$d/c.state" "$4" - \\test -e "$d/c.state"; test ! -e "$d/c.xitdb" + \\test ! -e "$d/c.state"; test ! -e "$d/c.xitdb" \\rm -f "$d"/* }); twice.setName("a script recorded twice"); @@ -496,34 +491,36 @@ pub fn build(b: *Build) void { test_step.dependOn(&twice.step); b.step("test-same", "A script run twice records the same database but for times").dependOn(&twice.step); - // Where files go. Without --state: the XDG data directory, state and - // sessions. In .sketchbook/ (`zig build run`'s): a .gitignore, and an - // older build's state moved in, once, never over a file there. + // Where files go. Without --state: the XDG data directory, one file. In + // .sketchbook/ (`zig build run`'s): a .gitignore and the save, whose + // present the next run starts from; an older build's state file beside + // it is moved in, once, never over a file there, and never deleted. const paths = b.addSystemCommand(&.{ "sh", "-c", \\set -e \\exe=$(realpath "$0"); lib=$(realpath "$1"); mkdir -p "$2"; d=$(realpath "$2") \\rm -rf "$d"/* "$d"/.sketchbook; cd "$d" \\XDG_DATA_HOME="$d/data" "$exe" --headless --console quit "$lib" - \\test -s data/replay/replay.state; test -s data/replay/replay.xitdb - \\"$exe" --headless --state replay.state --console "set updates 7" --console quit "$lib" - \\"$exe" --headless --state .sketchbook/replay.state --console quit "$lib" 2>err - \\grep -q moved err; test ! -e replay.state; grep -qx '*' .sketchbook/.gitignore + \\test "$(ls -A data/replay)" = replay.xitdb + \\"$exe" --headless --state .sketchbook/replay.xitdb --console "set updates 7" --console quit "$lib" + \\test "$(ls -A .sketchbook | tr '\n' ' ')" = ".gitignore replay.xitdb "; grep -qx '*' .sketchbook/.gitignore \\printf 'expect updates 7\n' >check.script - \\"$exe" --headless --state .sketchbook/replay.state --script check.script "$lib" - \\"$exe" --headless --state replay.state --console quit "$lib" - \\"$exe" --headless --state .sketchbook/replay.state --console quit "$lib" 2>err - \\grep -q 'both exist' err; test -e replay.state - \\"$exe" --headless --state .sketchbook/replay.state --script check.script "$lib" + \\"$exe" --headless --state .sketchbook/replay.xitdb --script check.script "$lib" + \\printf 'not a state file' >old.state + \\"$exe" --headless --state .sketchbook/old.xitdb --console quit "$lib" 2>err + \\grep -q moved err; test ! -e old.state; test "$(cat .sketchbook/old.state)" = 'not a state file' + \\printf 'not a state file' >old.state + \\"$exe" --headless --state .sketchbook/old.xitdb --console quit "$lib" 2>err + \\grep -q 'both exist' err; test -e old.state \\rm -rf "$d"/* "$d"/.sketchbook }); - paths.setName("state and sessions paths"); + paths.setName("where the save goes"); paths.addArtifactArg(host_exe); paths.addArtifactArg(recorded); _ = paths.addOutputDirectoryArg("paths"); paths.has_side_effects = true; paths.expectExitCode(0); test_step.dependOn(&paths.step); - b.step("test-paths", "Check where state and sessions files go").dependOn(&paths.step); + b.step("test-paths", "Check where the save goes").dependOn(&paths.step); // Recorded input replays to the same state: played, seeked, stepped, // and after a live pointer move (core host behaviour, not an API). @@ -719,7 +716,6 @@ pub fn init(b: *Build, options: Options) Sketchbook { .optimize = options.optimize, .modules = .{ .abi = dep.module("abi"), .sketch = dep.module("sketch"), .host = dep.module("host"), .tracy = dep.module("tracy"), .vector = dep.module("vector"), .scope = dep.module("scope"), .anim = dep.module("anim"), .gltf = dep.module("gltf") }, .host_exe = dep.artifact("sketchbook"), - .probe_exe = dep.artifact("sketchbook-probe"), .gltf_generator = dep.artifact("gltf-bindings"), .web = dep.path("web"), .glsl = dep.path("src/glsl.zig"), @@ -771,8 +767,6 @@ pub const Sketchbook = struct { modules: struct { abi: *Build.Module, sketch: *Build.Module, host: *Build.Module, tracy: *Build.Module, vector: *Build.Module, scope: *Build.Module, anim: *Build.Module, gltf: *Build.Module }, /// The generic host: loads and hot-reloads a sketch library. host_exe: *Build.Step.Compile, - /// Prints any sketch's state file. - probe_exe: *Build.Step.Compile, /// `host.js` and the `index.html` template. web: Build.LazyPath, /// The GLSL declaration generator (see `addGlslLayouts`). @@ -1432,9 +1426,8 @@ pub const App = struct { } pub const RunOptions = struct { - /// State file, relative to the working directory; - /// `.sketchbook/<name>.state` by default, where the host keeps the - /// sessions database beside it, all ignored by git and jj. + /// The save, relative to the working directory; + /// `.sketchbook/<name>.xitdb` by default, ignored by git and jj. state: ?[]const u8 = null, /// Where relative asset paths resolve; the project root by default. cwd: ?Build.LazyPath = null, @@ -1447,7 +1440,7 @@ pub const App = struct { const install = b.addInstallArtifact(library, .{}); const run = b.addRunArtifact(app.sb.host_exe); run.step.dependOn(&install.step); - run.addArgs(&.{ "--state", options.state orelse b.fmt(".sketchbook/{s}.state", .{app.name}) }); + run.addArgs(&.{ "--state", options.state orelse b.fmt(".sketchbook/{s}.xitdb", .{app.name}) }); run.addFileArg(b.graph.path(.install_lib, library.out_filename)); run.setCwd(options.cwd orelse b.path(".")); run.stdio = .inherit; @@ -1461,7 +1454,7 @@ pub const App = struct { cwd: ?Build.LazyPath = null, }; - /// Plays a script headless, with a throwaway state file, against + /// Plays a script headless, from fresh state and saving nothing, against /// `artifact`: the executable (`addExecutable`), or the hot-reloadable /// library (`addLibrary`) through the generic host, which scripts can /// `reload`. Fails when an expectation or a console line does. @@ -1473,7 +1466,7 @@ pub const App = struct { run.addFileArg(script); run.addArg("--state"); // Named per script: runs of one app may share an output directory. - _ = run.addOutputFileArg(b.fmt("{s}-{s}.state", .{ app.name, std.fs.path.stem(script.getDisplayName()) })); + _ = run.addOutputFileArg(b.fmt("{s}-{s}.xitdb", .{ app.name, std.fs.path.stem(script.getDisplayName()) })); for (options.defines) |pair| run.addArgs(&.{ "--define", b.fmt("{s}={s}", .{ pair[0], pair[1] }) }); if (library) run.addArtifactArg(artifact); run.setCwd(options.cwd orelse b.path(".")); @@ -1503,7 +1496,7 @@ pub const App = struct { const b = app.sb.b; const run = b.addRunArtifact(exe); run.addArg("--state"); - _ = run.addOutputFileArg(b.fmt("{s}-export.state", .{app.name})); + _ = run.addOutputFileArg(b.fmt("{s}-export.xitdb", .{app.name})); run.addArg("--export"); const frames = run.addOutputDirectoryArg("frames"); run.addArgs(&.{ "--fps", b.fmt("{d}", .{options.fps}) }); @@ -1514,17 +1507,6 @@ pub const App = struct { return .{ .run = run, .frames = frames }; } - /// Prints the app's live state; `zig build probe -- --watch` follows it. - pub fn addProbe(app: App, state: ?[]const u8) *Build.Step.Run { - const b = app.sb.b; - const run = b.addRunArtifact(app.sb.probe_exe); - run.addArg(state orelse b.fmt(".sketchbook/{s}.state", .{app.name})); - run.setCwd(b.path(".")); - run.stdio = .inherit; - run.addPassthruArgs(); - return run; - } - /// Tests in `root_source_file` (the app's root by default), with the /// app's imports and the app itself importable as `app`. pub fn addTest(app: App, options: struct { root_source_file: ?Build.LazyPath = null }) *Build.Step.Compile { @@ -1769,7 +1751,7 @@ pub const App = struct { /// The conventional wiring. Installs the executable, and adds: /// `run` (host + hot reload), `lib` (rebuild the library; use `--watch`), - /// `web` and `serve` (with `web` options), `probe`, `export` (frames + /// `web` and `serve` (with `web` options), `export` (frames /// for ffmpeg), `e2e` (scripts) and `test`. pub fn addSteps(app: App, options: StepsOptions) Steps { const b = app.sb.b; @@ -1780,7 +1762,6 @@ pub const App = struct { const run = app.addRun(library, .{}); b.step("run", "Run with hot reload (rebuild with `zig build lib --watch`)").dependOn(&run.step); b.step("lib", "Build and install the hot-reloadable library").dependOn(&b.addInstallArtifact(library, .{}).step); - b.step("probe", "Print the live state (-- --watch to follow)").dependOn(&app.addProbe(null).step); const web = if (options.web) |web_options| blk: { const web = app.addWeb(web_options); @@ -1792,7 +1773,7 @@ pub const App = struct { // `--export` takes the first argument after `--`. const exporting = b.addRunArtifact(exe); - exporting.addArgs(&.{ "--state", b.fmt(".sketchbook/{s}.state", .{app.name}), "--export" }); + exporting.addArgs(&.{ "--state", b.fmt(".sketchbook/{s}.xitdb", .{app.name}), "--export" }); exporting.addPassthruArgs(); exporting.setCwd(b.path(".")); exporting.stdio = .inherit; |
