//! 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", "gallery" }; 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 }); // The tools a recording is made with, always optimized: a step through // the agent's or the runtime's code is a moment of the recording, and // a slow tracer stretches the clock's retry loops it steps through. const tools = b.dependency("ztrace", .{ .target = target, .optimize = .ReleaseFast }); const ztrace = tools.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 and the agent to preload, as ztrace's own build makes and names them. const plugin = tools.namedLazyPath("ztrace-pass"); const agent = tools.namedLazyPath("ztrace-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 /// variables with their types), for the functions and globals /// `only` names: everything else is the compiler's alone. Null for /// the program as the compiler alone makes it (static, unoptimised), /// whose instructions are then all its own. instr: ?[]const u8 = null, only: []const u8 = "*", /// Run through to here before the first stop: the loader, the C /// library's start, and what the scene does not show. from: ?[]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" }, // By instruction, as `steps` is: the registers are the program's // own, so they strike and link. Only the variables the scenes name // are told by the instrumentation (each a call into its runtime, // stepped like any other); `list` starts at `reverse`, its pushes // (the agent's and the runtime's first calls) run through. .{ .name = "sort", .source = "sort.c", .by = "insn", .instr = "vars", .only = "sort,a", .from = "main" }, .{ .name = "list", .source = "list.c", .by = "insn", .instr = "vars", .only = "push,reverse,head", .from = "reverse", .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, "--only", r.only, "--plugin" }); cc.addFileArg(plugin); cc.addArg("--rt"); cc.addArtifactArg(tools.artifact("ztrace-rt")); // Not position-independent: code and heap at short addresses, as // the design's columns are drawn for (seven digits, not twelve). // Bound at load and with no canary: no resolver and no check is // stepped through that the source does not say. cc.addArgs(&.{ "--", "clang", "-O0", "-g", "-no-pie", "-fno-stack-protector", "-Wl,-z,now" }); 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" }); if (r.from) |place| run.addArgs(&.{ "--from", place }); // 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.addFileArg(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"); } // The gallery's own: a recording of the list kept in test/gallery, so its // pictures change when the drawing does and not when a new recording does. _ = embedded.addCopyFile(b.path("test/gallery/list.ztrace"), "gallery.ztrace"); table.print(b.allocator, "pub const gallery: Program = .{{ .trace = @embedFile(\"gallery.ztrace\"), .file = \"list.c\", .source = @embedFile(\"list.c\") }};\n", .{}) 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); } if (std.mem.eql(u8, name, "gallery")) { // The catalogue drawn: its pages against the pictures in test/gallery // (`zig build gallery` draws them anew), at the design's size. for ([_]struct { []const u8, []const u8 }{ .{ "test", ".zig-cache/canim" }, .{ "gallery", "test/gallery" } }) |use| { const run = b.addRunArtifact(exe); run.addArgs(&.{ "--headless", "--fresh", "--size", "1920x1080", "--define", b.fmt("dir={s}", .{use[1]}), "--script" }); run.addFileArg(b.path("test/gallery.script")); run.addArg("--state"); _ = run.addOutputFileArg(b.fmt("gallery-{s}.state", .{use[0]})); run.setCwd(b.path(".")); run.expectExitCode(0); run.has_side_effects = true; if (std.mem.eql(u8, use[0], "test")) test_step.dependOn(&run.step) else b.step("gallery", "Draw the gallery's pages anew into test/gallery, the pictures the test compares with").dependOn(&run.step); } continue; } 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 -g 600 -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); } } }