//! 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`. The sqlite scene also needs `clang` and SQLite's //! amalgamation (`-Dsqlite=DIR`); without it that scene is not made. const std = @import("std"); const sketchbook = @import("sketchbook"); const scenes = [_][]const u8{ "title", "fib", "list", "sort", "syscalls", "musl", "zoom", "heap", "gallery", "column", "column_sort", "intro", "asan" }; 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, .tracy = b.option([]const u8, "tracy", "Enable native Tracy profiling with this checkout") }); 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 }); // The debuginfod client's cache, where elfutils and Zig's std look: a // distribution's library's debug info of the same build id, that the // recorder names its code and lines by; and where `sources` keeps the // source files those lines name (//source/). // Found when a step runs, from its environment (`$DEBUGINFOD_CACHE_PATH`, // else `$XDG_CACHE_HOME/debuginfod_client`, else `~/.cache/debuginfod_client`), // never at configure time, whose result zig caches. const debuginfod_cache = "${DEBUGINFOD_CACHE_PATH:-${XDG_CACHE_HOME:-$HOME/.cache}/debuginfod_client}"; // The sources a recording's lines name, other than the program's own: // embedded from the cache and Zig's lib directory (`embed`, every build), // fetched into the cache (`fetch`, `zig build sources`). const sources_tool = b.addExecutable(.{ .name = "sources", .root_module = b.createModule(.{ .root_source_file = b.path("tools/sources.zig"), .target = b.graph.host, .optimize = .ReleaseFast, .imports = &.{.{ .name = "ztrace", .module = tools.module("ztrace") }}, }) }); const fetch = b.addRunArtifact(sources_tool); fetch.addArg("fetch"); fetch.has_side_effects = true; b.step("sources", "Fetch the library sources the recordings' lines name into the debuginfod cache (the only step that uses the network)").dependOn(&fetch.step); var source_modules: std.ArrayList(std.Build.Module.Import) = .empty; 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, /// Bytes of stack above rsp each stop records. (A call into the /// vDSO, the runtime's clock, is one moment: its retry loop is not stepped.) stack: []const u8 = "1024", /// Built by the system's clang against its glibc and linked /// dynamically, as a C programmer's program is (a PLT, libc's own /// code to follow down): `-no-pie` for short addresses, bound at /// load (`-z now`: no resolver), with the canary the compiler puts in. glibc: bool = false, /// The compiler's command for a `glibc` build, in place of its own. cc: ?[]const []const u8 = null, /// Stops after `from` before the recording ends: main's return, not the exit's. steps: ?[]const u8 = null, /// Ends the recording at the first stop here (`--until`). until: ?[]const u8 = null, /// The name it runs by (argv[0], its mapping), where not the recording's. program: ?[]const u8 = null, /// Also glibc's heap at every stop (`--heap`), and memory watched (`-w`). heap: bool = false, watch: []const []const u8 = &.{}, /// Also a stop at the call, in function [0], of function [1] through /// its PLT stub (found by objdump: there is no name for it): the row /// a line's cascade lands on before the call is stepped over. break_call: ?[2][]const u8 = null, }; for ([_]Recording{ .{ .name = "steps", .source = "fib.c", .by = "insn" }, // By instruction from main, through the PLT and libc's wrappers to // the kernel and back: the descent; to main's return. .{ .name = "hello", .source = "hello.c", .by = "insn", .from = "main", .steps = "132", .glibc = true, .reads = "note" }, // A line a stop, malloc and free run through (through the PLT); glibc's heap at each; // to main's return (libc's lines, named now, would take it on through `exit`). .{ .name = "heap", .source = "heap.c", .by = "line", .from = "main", .steps = "46", .glibc = true, .heap = true, .watch = &.{ "0x405000,1024", "head" }, .break_call = .{ "pop", "free" } }, // 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 }, // The introduction's: the same program as the compiler alone makes it // (no tracer's calls in reverse; no red zone, so its prologue makes // room for its locals: `push rbp; mov rbp, rsp; sub rsp, 0x18`; its // locals named by the debug info), from main's push(9) (its call of // malloc, which chapter II steps over) to line 22, past the load; the // program's alone (no agent: malloc changes only what glibc's does), // glibc's heap at each stop for the list's nodes; `head` watched, the // global the list hangs from. .{ .name = "intro", .source = "list.c", .by = "insn", .glibc = true, .cc = &.{ "clang", "-O0", "-g", "-mno-red-zone", "-no-pie", "-fno-stack-protector", "-Wl,-z,now" }, .from = "list.c:40", .until = "list.c:22", .heap = true, .watch = &.{"head"}, .program = "list" }, // `hello` again, built by Zig against musl, static: no PLT; musl's // own source (`open.c`, `syscall_cp`) on the way down to the kernel. .{ .name = "musl", .source = "hello.c", .by = "insn", .from = "main", .steps = "166", .reads = "note" }, }) |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 if (r.glibc) { const cc = b.addSystemCommand(r.cc orelse &.{ "clang", "-O0", "-g", "-no-pie", "-fstack-protector-strong", "-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(); const runs_as = r.program orelse r.name; _ = where.addCopyFile(program, runs_as); if (r.reads) |name| _ = where.addCopyFile(b.path(b.fmt("tools/{s}", .{name})), name); // A dynamic program's libraries are named by their debug info in // the debuginfod cache: the recorder finds it by DEBUGINFOD_CACHE_PATH, // which the program inherits, so it is a link beside the program // (`debuginfod`), a name that says nothing of the machine. const dynamic = r.glibc or r.instr != null; const run = if (r.break_call) |call| blk: { // The call's address, from the program as built, then the recorder with a breakpoint there. const sh = b.addSystemCommand(&.{ "sh", "-c", b.fmt( \\p=$0 z=$1; shift \\c={s} \\at=$(objdump -d --no-show-raw-insn "$p" | awk '/<{s}>:/ {{ f = 1 }} f && /call.*<{s}@plt>/ {{ sub(":", "", $1); print "0x" $1; exit }}') \\[ -n "$at" ] || {{ echo "no call of {s} in {s}" >&2; exit 1; }} \\ln -sfn "$c" debuginfod \\exec env -i DEBUGINFOD_CACHE_PATH=debuginfod setarch -R "$z" record -b "*$at" "$@" , .{ debuginfod_cache, call[0], call[1], call[1], call[0] }) }); sh.addFileArg(program); break :blk sh; } else if (dynamic) blk: { const sh = b.addSystemCommand(&.{ "sh", "-c", "ln -sfn \"" ++ debuginfod_cache ++ "\" debuginfod && exec env -i DEBUGINFOD_CACHE_PATH=debuginfod setarch -R \"$0\" \"$@\"" }); break :blk sh; } else b.addSystemCommand(&.{ "env", "-i", "setarch", "-R" }); run.addArtifactArg(ztrace); // More round each stop than the working frame shows: the map of // the whole context wants the words of the stack, 256 bytes round // what a pointer leads to and what a step touches, and 69 // instructions round the pc. if (r.break_call == null) run.addArg("record"); run.addArgs(&.{ "--by", r.by, "--stack", r.stack, "--around", "256", "--disasm", "69", "-s", "64" }); if (r.from) |place| run.addArgs(&.{ "--from", place }); if (r.steps) |n| run.addArgs(&.{ "--steps", n }); if (r.until) |place| run.addArgs(&.{ "--until", place }); if (r.heap) run.addArg("--heap"); for (r.watch) |what| run.addArgs(&.{ "-w", what }); // 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}", .{runs_as}) }); run.setCwd(where.getDirectory()); run.expectExitCode(0); run.expectStdErrMatch("exit 0"); // Into the scene's own binary: the recording's bytes, the source it // ran, and the other sources its lines name that the build has. 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); fetch.addFileArg(trace); const sources = embedSources(b, sources_tool, r.name, trace, r.source); source_modules.append(b.allocator, .{ .name = b.fmt("{s}-sources", .{r.name}), .module = sources }) catch @panic("OOM"); table.print(b.allocator, "pub const {s}: Program = .{{ .trace = @embedFile(\"{s}\"), .file = \"{s}\", .source = @embedFile(\"{s}\"), .sources = &@import(\"{s}-sources\").list }};\n", .{ r.name, file, r.source, r.source, r.name }) catch @panic("OOM"); } // The pair (`asan`, design/motion.md "A scene: ASan against a plain // build"): overflow.c built twice by the system's clang, plain and with // AddressSanitizer, frame pointers kept and no canary (Arch's clang puts // one in by default, and the plain run would die in `__stack_chk_fail`, // not at `ret`). Each run as `./overflow` in a directory of its own, with // no environment but ASan's leak check off (it fails under a tracer): // plain by instruction from main to its fault at `ret` (the recorder // says `exit 139`, SIGSEGV); ASan by instruction from main to the first // stop in `__asan_report_store1` (`--until`: the report itself is a // million more), and the same run again by syscall alone, for the // report's `write`s to fd 2 as written. for ([_]struct { name: []const u8, asan: bool, args: []const []const u8, exit: []const u8 }{ .{ .name = "overflow", .asan = false, .args = &.{ "--by", "insn", "--stack", "1024", "--around", "256", "--disasm", "69", "-s", "64", "--from", "main" }, .exit = "exit 139" }, .{ .name = "overflow_asan", .asan = true, .args = &.{ "--asan", "--by", "insn", "--stack", "1024", "--around", "256", "--disasm", "69", "-s", "64", "--from", "main", "--until", "__asan_report_store1" }, .exit = "exit 0" }, .{ .name = "overflow_report", .asan = true, .args = &.{ "--by", "syscall", "--stack", "0", "--telescope", "0", "-s", "4096" }, .exit = "exit 1" }, }) |r| { const cc = b.addSystemCommand(&.{ "clang", "-O0", "-g", "-fno-omit-frame-pointer", "-no-pie", "-fno-stack-protector" }); if (r.asan) cc.addArg("-fsanitize=address"); cc.addFileArg(b.path("tools/overflow.c")); cc.addArg("-o"); const program = cc.addOutputFileArg("overflow"); const where = b.addWriteFiles(); _ = where.addCopyFile(program, "overflow"); const link = "ln -sfn \"" ++ debuginfod_cache ++ "\" debuginfod && exec env -i DEBUGINFOD_CACHE_PATH=debuginfod "; const run = b.addSystemCommand(&.{ "sh", "-c", if (r.asan) link ++ "ASAN_OPTIONS=detect_leaks=0 setarch -R \"$0\" \"$@\"" else link ++ "setarch -R \"$0\" \"$@\"" }); run.addArtifactArg(ztrace); run.addArg("record"); run.addArgs(r.args); run.addArg("-o"); const trace = run.addOutputFileArg(b.fmt("{s}.ztrace", .{r.name})); run.addArgs(&.{ "--", "./overflow" }); run.setCwd(where.getDirectory()); run.expectExitCode(0); run.expectStdErrMatch(r.exit); const file = b.fmt("{s}.ztrace", .{r.name}); record_step.dependOn(&b.addInstallFile(trace, b.fmt("recordings/{s}", .{file})).step); _ = embedded.addCopyFile(trace, file); table.print(b.allocator, "pub const {s}: Program = .{{ .trace = @embedFile(\"{s}\"), .file = \"overflow.c\", .source = @embedFile(\"overflow.c\") }};\n", .{ r.name, file }) catch @panic("OOM"); } _ = embedded.addCopyFile(b.path("tools/overflow.c"), "overflow.c"); // SQLite, the next rung: its amalgamation is not ours to copy, so the // scene is made only where it is. Built as the bench builds it (-O2, // frame pointers kept), and as the instrumented ones are (no PIE, bound // at load, no canary); run once under the debugger, stopping where a // statement's bytecode is run (`sqlite3_step`), where a row enters the // B-tree (`sqlite3BtreeInsert`), where a page is written // (`unixWrite`) and where its `pwrite64` has returned to it (the // instruction after the call, found by objdump: there is no name for // it); every syscall recorded with the bytes it points at, up to a page. // In a directory of its own each time: the database it makes must not be there. const sqlite_dir = b.option([]const u8, "sqlite", "SQLite's amalgamation (sqlite3.c, sqlite3.h): the sqlite scene is made only with it") orelse b.pathJoin(&.{ b.graph.environ_map.get("HOME") orelse "/", "05-genizah/sqlite/sqlite-amalgamation-3500400" }); const sqlite_c = b.pathJoin(&.{ sqlite_dir, "sqlite3.c" }); const has_sqlite = if (std.Io.Dir.cwd().access(b.graph.io, sqlite_c, .{})) |_| true else |_| false; if (has_sqlite) { const cc = b.addSystemCommand(&.{ "clang", "-O2", "-g", "-fno-omit-frame-pointer", "-no-pie", "-fno-stack-protector", "-Wl,-z,now", "-w" }); cc.addPrefixedDirectoryArg("-I", .{ .cwd_relative = sqlite_dir }); cc.addFileArg(b.path("tools/sqlite.c")); cc.addFileArg(.{ .cwd_relative = sqlite_c }); cc.addArgs(&.{ "-lm", "-o" }); const program = cc.addOutputFileArg("sqlite"); const run = b.addSystemCommand(&.{ "sh", "-c", \\set -e \\ztrace=$(realpath "$0") program=$(realpath "$1") \\case $2 in /*) out=$2 ;; *) out=$PWD/$2 ;; esac \\back=$(objdump -d --no-show-raw-insn "$program" | awk '/:/ { f = 1 } f && /call.*pwrite64/ { getline; sub(":", "", $1); print "0x" $1; exit }') \\[ -n "$back" ] || { echo "no call of pwrite64 in unixWrite" >&2; exit 1; } \\d=$(mktemp -d) \\trap 'rm -rf "$d"' EXIT \\cp "$program" "$d/sqlite" \\cd "$d" \\ln -s "${DEBUGINFOD_CACHE_PATH:-${XDG_CACHE_HOME:-$HOME/.cache}/debuginfod_client}" debuginfod \\env -i DEBUGINFOD_CACHE_PATH=debuginfod setarch -R "$ztrace" record --by break -b sqlite3_step -b sqlite3BtreeInsert -b unixWrite -b "*$back" --stack 1024 --around 256 --disasm 69 -s 4096 -o "$out" -- ./sqlite }); run.addArtifactArg(ztrace); run.addFileArg(program); const trace = run.addOutputFileArg("sqlite.ztrace"); run.expectStdErrMatch("exit 0"); record_step.dependOn(&b.addInstallFile(trace, "recordings/sqlite.ztrace").step); _ = embedded.addCopyFile(trace, "sqlite.ztrace"); _ = embedded.addCopyFile(.{ .cwd_relative = sqlite_c }, "sqlite3.c"); fetch.addFileArg(trace); source_modules.append(b.allocator, .{ .name = "sqlite-sources", .module = embedSources(b, sources_tool, "sqlite", trace, "sqlite3.c") }) catch @panic("OOM"); table.print(b.allocator, "pub const sqlite: Program = .{{ .trace = @embedFile(\"sqlite.ztrace\"), .file = \"sqlite3.c\", .source = @embedFile(\"sqlite3.c\"), .sources = &@import(\"sqlite-sources\").list }};\n", .{}) 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"); // And for its graph pages, sort's and hello's, kept as they were recorded with blocks. for ([_][2][]const u8{ .{ "sort", "sort.c" }, .{ "hello", "hello.c" } }) |kept| { _ = embedded.addCopyFile(b.path(b.fmt("test/gallery/{s}.ztrace", .{kept[0]})), b.fmt("gallery-{s}.ztrace", .{kept[0]})); table.print(b.allocator, "pub const gallery_{s}: Program = .{{ .trace = @embedFile(\"gallery-{s}.ztrace\"), .file = \"{s}\", .source = @embedFile(\"{s}\") }};\n", .{ kept[0], kept[0], kept[1], kept[1] }) catch @panic("OOM"); } const recordings = b.createModule(.{ .root_source_file = embedded.add("recordings.zig", b.fmt( \\//! Generated by canim's build.zig: the recordings, the sources they ran, and the other sources their lines name that the build found (path, text). \\pub const Program = struct {{ trace: []const u8, file: []const u8, source: []const u8, sources: []const [2][]const u8 = &.{{}} }}; \\{s} , .{table.items})), .imports = source_modules.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 ++ [_][]const u8{"sqlite"}) |name| { if (std.mem.eql(u8, name, "sqlite") and !has_sqlite) continue; 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. No // adaptive quantization: on a still page it re-quantized a glyph's // edge as the rest of the frame moved, a column flickering (fib 7.45 s). 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 -x264-params aq-mode=0 -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); } } } /// The sources the lines of recording `name` (`trace`) name (but `own`, the program's /// file) that this machine has, as a module: `list`, each path and text. /// It reads the debuginfod cache, which the build does not track: run every build. fn embedSources(b: *std.Build, tool: *std.Build.Step.Compile, name: []const u8, trace: std.Build.LazyPath, own: []const u8) *std.Build.Module { const run = b.addRunArtifact(tool); run.addArg("embed"); run.addFileArg(trace); run.addArgs(&.{ own, b.graph.zig_exe }); const dir = run.addOutputDirectoryArg(b.fmt("{s}-sources", .{name})); run.has_side_effects = true; return b.createModule(.{ .root_source_file = dir.path(b, "sources.zig") }); }