//! 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); } } }