summaryrefslogtreecommitdiff
path: root/anim/build.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 14:48:26 -0300
committerGabriel Schneider <[email protected]>2026-11-10 15:14:31 -0300
commit7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb (patch)
treea6add92cd4dcbbf4c31cd1ce989d99b190258353 /anim/build.zig
parented46c51fe127377eb1fde8dee83da984e0f61860 (diff)
downloadcomputeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.tar.gz
computeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.zip
canim: animations of recordings, as a debugger's whole context with a lens beside it
A package of its own (anim/), on sketchbook's anim module and pardes's syntax. A scene opens a recording, takes a cursor into it, and declares blocks that read the moment the cursor is at: the state column (registers each followed as a pointer and inked by where it points, the stack telescope, the backtrace), the program column (the whole source, the disassembly in address order, and the scene's lens: a node-link list over a hexdump of its heap, array cells, a call tree, a syscall crossing), and ties between them. Motion is a step told as a sentence (the line fires, its effects cascade a level at a time, the mark moves on last), timed by what the step contains; walk, hurry and sprint pace a loop. Five scenes from real recordings of fib, a linked list, a sort and syscalls. First drafts, by the agent's own handover: the frame of the design's second revision, the hexdump lens and the ties; no disassembly annotations, no gallery, scenes not yet reviewed against the mocks.
Diffstat (limited to 'anim/build.zig')
-rw-r--r--anim/build.zig204
1 files changed, 204 insertions, 0 deletions
diff --git a/anim/build.zig b/anim/build.zig
new file mode 100644
index 0000000..f410fb9
--- /dev/null
+++ b/anim/build.zig
@@ -0,0 +1,204 @@
+//! canim: the animation library (`src/`, the module `canim`), the small C
+//! programs it records (`tools/`), and its scenes (`scenes/`), each a
+//! player built by sketchbook.
+//!
+//! zig build record the recordings, into zig-out/recordings
+//! zig build run -Dscene=list a scene in a window, with hot reload
+//! zig build export -Dscene=list -- DIR its frames (see sketchbook's README)
+//! zig build videos -Doptimize=ReleaseFast every scene as out/NAME-1080.mp4 and -2160
+//! zig build test unit tests and the scripted runs
+//! zig build bench what a recording costs a frame
+//! zig build motion -Dscene=list -Doptimize=ReleaseFast how a scene moves: contact sheets and change plots in out/motion/list
+//!
+//! Needs, besides what sketchbook and ztrace need: `setarch`, and for
+//! `videos`, `ffmpeg`.
+const std = @import("std");
+const sketchbook = @import("sketchbook");
+
+const scenes = [_][]const u8{ "title", "fib", "list", "sort", "syscalls", "zoom" };
+
+pub fn build(b: *std.Build) void {
+ const target = b.standardTargetOptions(.{});
+ const optimize = b.standardOptimizeOption(.{});
+ const chosen = b.option([]const u8, "scene", "The scene `run`, `lib` and `export` are about (default fib)") orelse "fib";
+
+ const sb = sketchbook.init(b, .{ .target = target, .optimize = optimize });
+ const zt = b.dependency("ztrace", .{ .target = target, .optimize = optimize });
+ const pardes = b.dependency("pardes", .{ .target = target, .optimize = optimize, .@"tree-sitter" = .minimal });
+ const ztrace = zt.artifact("ztrace");
+
+ const imports: []const std.Build.Module.Import = &.{
+ .{ .name = "anim", .module = sb.modules.anim },
+ .{ .name = "sketch", .module = sb.modules.sketch },
+ .{ .name = "ztrace", .module = zt.module("ztrace") },
+ .{ .name = "ztrace-types", .module = zt.module("ztrace-types") },
+ .{ .name = "pardes-syntax", .module = pardes.module("pardes-syntax") },
+ };
+ const canim = b.addModule("canim", .{ .root_source_file = b.path("src/root.zig"), .imports = imports });
+
+ // ---- The recordings: each program of tools/ run once under ztrace's
+ // debugger, without address randomisation (`setarch -R`), so a recording
+ // and the frames made from it are the same on every build.
+ const record_step = b.step("record", "Record the programs of tools/ into zig-out/recordings");
+ const embedded = b.addWriteFiles();
+ var table: std.ArrayList(u8) = .empty;
+
+ // The pass as ztrace's own build makes it.
+ // shortcut: its recipe is repeated here; the root package should name the plugin (`addNamedLazyPath`).
+ const cxx = b.addSystemCommand(&.{ "sh", "-c", "exec clang++ -shared -fPIC -O2 -fno-rtti $(llvm-config --cxxflags) \"$0\" -o \"$1\"" });
+ cxx.addFileArg(zt.path("llvm/pass.cpp"));
+ const plugin = cxx.addOutputFileArg("ztrace-pass.so");
+ // The agent to preload: of the two artifacts of that name, the shared one.
+ const agent = for (zt.builder.install_tls.step.dependencies.items) |step| {
+ const installed = step.cast(std.Build.Step.InstallArtifact) orelse continue;
+ if (std.mem.eql(u8, installed.artifact.name, "ztrace-agent") and installed.artifact.isDynamicLibrary()) break installed.artifact;
+ } else @panic("ztrace has no shared libztrace-agent");
+ const musl = b.resolveTargetQuery(.{ .cpu_arch = .x86_64, .os_tag = .linux, .abi = .musl });
+
+ const Recording = struct {
+ name: []const u8,
+ source: []const u8,
+ /// Where the debugger stops it: every instruction, or every line.
+ /// Each stop records the registers, the stack under them, what
+ /// they point at, and the instructions at the pc.
+ by: []const u8,
+ /// Compiled by `ztrace cc` to tell these of itself as well (its
+ /// calls, its variables with their types, every store and load);
+ /// null for the program as the compiler alone makes it (static,
+ /// unoptimised), whose instructions are then all its own.
+ instr: ?[]const u8 = null,
+ /// With the agent preloaded: `malloc` and `free` too.
+ alloc: bool = false,
+ /// A file of tools/ it reads, by its bare name.
+ reads: ?[]const u8 = null,
+ };
+ for ([_]Recording{
+ .{ .name = "steps", .source = "fib.c", .by = "insn" },
+ .{ .name = "hello", .source = "hello.c", .by = "line", .reads = "note" },
+ .{ .name = "sort", .source = "sort.c", .by = "line", .instr = "calls,vars,stores,loads" },
+ .{ .name = "list", .source = "list.c", .by = "line", .instr = "calls,vars,stores", .alloc = true },
+ }) |r| {
+ const source = b.path(b.fmt("tools/{s}", .{r.source}));
+ var program: std.Build.LazyPath = undefined;
+ if (r.instr) |instr| {
+ const cc = b.addRunArtifact(ztrace);
+ cc.addArgs(&.{ "cc", "--instr", instr, "--plugin" });
+ cc.addFileArg(plugin);
+ cc.addArg("--rt");
+ cc.addArtifactArg(zt.artifact("ztrace-rt"));
+ cc.addArgs(&.{ "--", "clang", "-O0", "-g" });
+ cc.addFileArg(source);
+ cc.addArg("-o");
+ program = cc.addOutputFileArg(r.name);
+ } else {
+ const mod = b.createModule(.{ .target = musl, .optimize = .Debug, .link_libc = true, .omit_frame_pointer = false, .sanitize_c = .off, .stack_protector = false });
+ mod.addCSourceFile(.{ .file = source, .flags = &.{ "-O0", "-g" } });
+ program = b.addExecutable(.{ .name = r.name, .root_module = mod, .linkage = .static }).getEmittedBin();
+ }
+ // It runs by a bare name in a directory of its own, with no
+ // environment: the strings on its stack (its name, its variables)
+ // end up on screen, and should say nothing of the machine it was made on.
+ const where = b.addWriteFiles();
+ _ = where.addCopyFile(program, r.name);
+ if (r.reads) |name| _ = where.addCopyFile(b.path(b.fmt("tools/{s}", .{name})), name);
+ const run = b.addSystemCommand(&.{ "env", "-i", "setarch", "-R" });
+ run.addArtifactArg(ztrace);
+ run.addArgs(&.{ "record", "--by", r.by, "--stack", "256", "-s", "64" });
+ // What an instrumented program tells of itself comes through a ring.
+ if (r.instr != null) run.addArg("--ring");
+ if (r.alloc) {
+ run.addArgs(&.{ "--alloc", "--preload" });
+ run.addArtifactArg(agent);
+ }
+ run.addArg("-o");
+ const trace = run.addOutputFileArg(b.fmt("{s}.ztrace", .{r.name}));
+ run.addArgs(&.{ "--", b.fmt("./{s}", .{r.name}) });
+ run.setCwd(where.getDirectory());
+ run.expectExitCode(0);
+ run.expectStdErrMatch("exit 0");
+
+ // Into the scene's own binary: the recording's bytes and the source it ran.
+ const file = b.fmt("{s}.ztrace", .{r.name});
+ record_step.dependOn(&b.addInstallFile(trace, b.fmt("recordings/{s}", .{file})).step);
+ _ = embedded.addCopyFile(trace, file);
+ _ = embedded.addCopyFile(source, r.source);
+ table.print(b.allocator, "pub const {s}: Program = .{{ .trace = @embedFile(\"{s}\"), .file = \"{s}\", .source = @embedFile(\"{s}\") }};\n", .{ r.name, file, r.source, r.source }) catch @panic("OOM");
+ }
+ const recordings = b.createModule(.{ .root_source_file = embedded.add("recordings.zig", b.fmt(
+ \\//! Generated by canim's build.zig: the recordings and the sources they ran.
+ \\pub const Program = struct {{ trace: []const u8, file: []const u8, source: []const u8 }};
+ \\{s}
+ , .{table.items})) });
+
+ // ---- Tests: the library's own, then on the real recordings.
+ const test_step = b.step("test", "Unit tests and the scripted runs");
+ test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = b.createModule(.{ .root_source_file = b.path("src/root.zig"), .target = target, .optimize = optimize, .imports = imports }) })).step);
+ test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = b.createModule(.{
+ .root_source_file = b.path("test/recordings.zig"),
+ .target = target,
+ .optimize = optimize,
+ .imports = &.{ .{ .name = "canim", .module = canim }, .{ .name = "recordings", .module = recordings }, .{ .name = "anim", .module = sb.modules.anim }, .{ .name = "ztrace", .module = zt.module("ztrace") } },
+ }) })).step);
+
+ // What a recording costs a frame: always optimized, whatever the build is.
+ const fast = b.createModule(.{ .root_source_file = b.path("src/root.zig"), .target = target, .optimize = .ReleaseFast, .imports = imports });
+ const bench = b.addRunArtifact(b.addExecutable(.{ .name = "bench", .root_module = b.createModule(.{
+ .root_source_file = b.path("tools/bench.zig"),
+ .target = target,
+ .optimize = .ReleaseFast,
+ .imports = &.{ .{ .name = "canim", .module = fast }, .{ .name = "recordings", .module = recordings }, .{ .name = "ztrace", .module = zt.module("ztrace") } },
+ }) }));
+ bench.has_side_effects = true;
+ bench.addPassthruArgs();
+ b.step("bench", "Time opening each recording and the queries a frame makes of it").dependOn(&bench.step);
+
+ // ---- Scenes.
+ const videos = b.step("videos", "Export every scene to out/NAME-1080.mp4 and out/NAME-2160.mp4 (use -Doptimize=ReleaseFast)");
+ for (scenes) |name| {
+ const scene = sb.addScene(.{ .root_source_file = b.path(b.fmt("scenes/{s}.zig", .{name})), .imports = &.{
+ .{ .name = "canim", .module = canim },
+ .{ .name = "recordings", .module = recordings },
+ } });
+ const exe = scene.app.addExecutable();
+ if (std.mem.eql(u8, name, chosen)) {
+ b.installArtifact(exe);
+ const library = scene.app.addLibrary();
+ b.step("run", "Play -Dscene with hot reload (rebuild with `zig build lib --watch`)").dependOn(&scene.app.addRun(library, .{}).step);
+ b.step("lib", "Build and install -Dscene's hot-reloadable library").dependOn(&b.addInstallArtifact(library, .{}).step);
+ const exporting = b.addRunArtifact(exe);
+ exporting.addArgs(&.{ "--state", b.fmt("{s}.state", .{name}), "--export" });
+ exporting.addPassthruArgs();
+ exporting.setCwd(b.path("."));
+ exporting.stdio = .inherit;
+ b.step("export", "Export -Dscene's frames: -- DIR for PNGs, or - for raw RGBA on stdout; then --fps N, --frames N, --size WxH").dependOn(&exporting.step);
+ // How it moves: contact sheets of every transition and plots of
+ // what changes from frame to frame (tools/motion.py).
+ const motion = b.addSystemCommand(&.{ "python3", "tools/motion.py" });
+ motion.addArtifactArg(exe);
+ motion.addArg(b.fmt("out/motion/{s}", .{name}));
+ motion.addPassthruArgs();
+ motion.setCwd(b.path("."));
+ motion.stdio = .inherit;
+ b.step("motion", "Judge -Dscene's motion: out/motion/NAME/ gets contact sheets of each transition and plots of change per frame").dependOn(&motion.step);
+ }
+ test_step.dependOn(&scene.app.addScript(exe, b.path(b.fmt("test/{s}.script", .{name})), .{}).step);
+
+ for ([_][]const u8{ "1920x1080", "3840x2160" }) |size| {
+ // The design's master: x264 from the raw frames, tagged bt709.
+ const video = b.addSystemCommand(&.{ "sh", "-c",
+ \\set -e
+ \\mkdir -p out
+ \\"$0" --state "$1" --export - --size "$2" --fps 60 |
+ \\ ffmpeg -loglevel error -y -f rawvideo -pix_fmt rgba -s "$2" -r 60 -i - \
+ \\ -c:v libx264 -crf 14 -preset slow -pix_fmt yuv420p \
+ \\ -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv "$3"
+ });
+ video.addArtifactArg(exe);
+ _ = video.addOutputFileArg(b.fmt("{s}-video.state", .{name}));
+ video.addArgs(&.{ size, b.fmt("out/{s}-{s}.mp4", .{ name, size[5..] }) });
+ video.setCwd(b.path("."));
+ video.has_side_effects = true;
+ videos.dependOn(&video.step);
+ }
+ }
+}