summaryrefslogtreecommitdiff
path: root/build.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 01:13:36 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit1ce323f2f21b94f9c4fc4e7a6986612cf30cf183 (patch)
tree87342ff0ca8bf9e08ba8060ffddd6a64bfca7adf /build.zig
parent62cce7f3d96aa054b2bc2055dce86dd8e4205256 (diff)
downloadsketchbook-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.zig99
1 files changed, 40 insertions, 59 deletions
diff --git a/build.zig b/build.zig
index 0367809..72b7714 100644
--- a/build.zig
+++ b/build.zig
@@ -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;