1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
|
//! 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_memory", "intro_stack", "intro_code", "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 });
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 (<cache>/<build id>/source/<path>).
// 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,
/// 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 from main's call of reverse
// (its push of the way back, reverse's prologue) to line 22, past the load.
.{ .name = "intro", .source = "list.c", .by = "insn", .instr = "vars", .only = "push,reverse,head", .from = "list.c:41", .until = "list.c:22", .alloc = true, .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(&.{ "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
// instruction of `__asan_report_store1` (582 stops: 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", "--steps", "582" }, .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 '/<unixWrite>:/ { 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") });
}
|