From 7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 14:48:26 -0300 Subject: 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. --- anim/build.zig | 204 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 anim/build.zig (limited to 'anim/build.zig') 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); + } + } +} -- cgit v1.3