//! sketchbook: a host that hot-reloads sketches, and the library they use. //! //! Apps use it from their own build.zig: //! //! const sketchbook = @import("sketchbook"); //! //! const sb = sketchbook.init(b, .{ .target = target, .optimize = optimize }); //! const app = sb.app(.{ .name = "demo", .root_source_file = b.path("src/main.zig") }); //! _ = app.addSteps(.{}); // run, lib, probe, e2e, test, install; //! // web and serve with `.web = .{}` //! //! or pick the pieces: `app.addLibrary()`, `app.addExecutable()`, //! `app.addWeb(...)`, `app.addRun(...)`, `app.addScript(...)`, //! `app.addProbe(...)`, `app.addTest(...)`. `sb.addScene(...)` is the app //! that plays an `anim` scene file. GPU shaders are GLSL, built by //! `sb.addShaders(...)` into SPIR-V for native hosts and WGSL for the web; //! `sb.addGlslLayouts(...)` and `sb.addGlslc(...)` are its pieces. Each //! returns the ordinary `std.Build` objects, so anything can be extended or //! rewired. //! //! Tools, found on PATH when a step needs them: `glslc` (shaderc or the //! Vulkan SDK) for any shader, `naga` (`cargo install naga-cli`) only for //! the web build of a sketch with shaders, `typst` only for a scene with //! Typst in it, and `miniserve` and `openssl` only for `serve`. const std = @import("std"); const Build = std.Build; const translate_c = @import("translate_c"); pub fn build(b: *Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); // Target-free: they compile for whatever imports them, native or wasm. const abi = b.addModule("abi", .{ .root_source_file = b.path("src/abi.zig") }); // Geometry and noise, shared by the sketch library and `vector`. const math = b.addModule("math", .{ .root_source_file = b.path("src/math/root.zig") }); const sketch_imports: []const Build.Module.Import = &.{ .{ .name = "abi", .module = abi }, .{ .name = "math", .module = math } }; const sketch = b.addModule("sketch", .{ .root_source_file = b.path("src/sketch/root.zig"), .imports = sketch_imports }); const tracy_path = b.option([]const u8, "tracy", "Enable Tracy with this source checkout (disabled by default)") orelse ""; const profile_options = b.addOptions(); profile_options.addOption(bool, "enabled", tracy_path.len > 0); const tracy = b.addModule("tracy", .{ .root_source_file = b.path("src/tracy.zig"), .target = target, .optimize = optimize }); tracy.addOptions("profile_options", profile_options); if (tracy_path.len > 0) { tracy.addIncludePath(.{ .cwd_relative = tracy_path }); tracy.addCSourceFile(.{ .file = .{ .cwd_relative = b.pathJoin(&.{ tracy_path, "public", "TracyClient.cpp" }) }, .flags = &.{ "-DTRACY_ENABLE=1", "-DTRACY_NO_SAMPLING", "-DTRACY_NO_CALLSTACK", "-DTRACY_NO_SYSTEM_TRACING", "-DTRACY_NO_CRASH_HANDLER", "-DTRACY_NO_CODE_TRANSFER", "-fno-sanitize=undefined" }, }); tracy.link_libcpp = true; } const c = cModule(b, target, optimize); // No optimize mode of its own: the host's Zig code builds in the mode // of the executable it is part of (`script_optimize` makes use of it). const host = b.addModule("host", .{ .root_source_file = b.path("src/host/root.zig"), .target = target, .imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "c", .module = c }, .{ .name = "tracy", .module = tracy } }, }); const host_exe = b.addExecutable(.{ .name = "sketchbook", .root_module = b.createModule(.{ .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "host", .module = host }}, }), }); b.installArtifact(host_exe); const probe = b.addExecutable(.{ .name = "sketchbook-probe", .root_module = b.createModule(.{ .root_source_file = b.path("src/host/probe.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "abi", .module = abi }}, }), }); b.installArtifact(probe); var sb: Sketchbook = .{ .b = b, .target = target, .optimize = optimize, .modules = .{ .abi = abi, .sketch = sketch, .host = host, .tracy = tracy, .vector = undefined, .scope = undefined, .anim = undefined }, .host_exe = host_exe, .probe_exe = probe, .web = b.path("web"), .glsl = b.path("src/glsl.zig"), .tools = b.path("tools"), .anim_dir = b.path("src/anim"), .script_optimize = optimize, .shared = .create(b) }; // Vector graphics: built with the same shader step apps use. Both forms // of its shaders are exported, so apps' web builds can swap them too. const vector_layouts = b.createModule(.{ .root_source_file = b.path("src/vector/layouts.zig") }); const vector_shaders = sb.addShaders(.{ .layouts = .{ .module = vector_layouts, .types = &.{ "Vertex", "Painted", "Viewport", "Paint" } }, .sources = &.{ b.path("src/vector/shaders/path.vert"), b.path("src/vector/shaders/stencil.frag"), b.path("src/vector/shaders/paint.vert"), b.path("src/vector/shaders/paint.frag") }, }); b.modules.put(b.graph.arena, "vector_shaders", vector_shaders.module) catch @panic("OOM"); b.modules.put(b.graph.arena, "vector_shaders_web", vector_shaders.web) catch @panic("OOM"); const vector_imports: []const Build.Module.Import = &.{ .{ .name = "abi", .module = abi }, .{ .name = "math", .module = math }, .{ .name = "vector_layouts", .module = vector_layouts }, .{ .name = "vector_shaders", .module = vector_shaders.module }, }; sb.modules.vector = b.addModule("vector", .{ .root_source_file = b.path("src/vector/root.zig"), .imports = vector_imports }); // manim-style animation: scenes as code, played by `src/anim/player.zig`. const anim_imports: []const Build.Module.Import = &.{ .{ .name = "sketch", .module = sketch }, .{ .name = "vector", .module = sb.modules.vector } }; sb.modules.anim = b.addModule("anim", .{ .root_source_file = b.path("src/anim/root.zig"), .imports = anim_imports }); // Sound scopes: waveform, spectrogram, spectrum and oscilloscope of a // stream of samples, analysed and drawn on the GPU. const scope_layouts = b.createModule(.{ .root_source_file = b.path("src/scope/layouts.zig") }); const scope_shaders = sb.addShaders(.{ .layouts = .{ .module = scope_layouts, .types = &.{ "SpectrumParams", "WaveParams", "WaveView", "SpectrumView", "SpectrogramParams", "SpectrogramView" } }, .sources = &.{ b.path("src/scope/shaders/view.vert"), b.path("src/scope/shaders/waveform.comp"), b.path("src/scope/shaders/waveform.frag"), b.path("src/scope/shaders/spectrogram.comp"), b.path("src/scope/shaders/spectrogram.frag"), b.path("src/scope/shaders/spectrum.comp"), b.path("src/scope/shaders/spectrum.frag"), }, }); b.modules.put(b.graph.arena, "scope_shaders", scope_shaders.module) catch @panic("OOM"); b.modules.put(b.graph.arena, "scope_shaders_web", scope_shaders.web) catch @panic("OOM"); const scope_imports: []const Build.Module.Import = &.{ .{ .name = "sketch", .module = sketch }, .{ .name = "scope_layouts", .module = scope_layouts }, .{ .name = "scope_shaders", .module = scope_shaders.module }, }; sb.modules.scope = b.addModule("scope", .{ .root_source_file = b.path("src/scope/root.zig"), .imports = scope_imports }); const test_step = b.step("test", "Run unit tests and the reload end-to-end test"); for ([_]*Build.Module{ b.createModule(.{ .root_source_file = b.path("src/vector/root.zig"), .target = target, .optimize = optimize, .imports = vector_imports }), b.createModule(.{ .root_source_file = b.path("src/scope/root.zig"), .target = target, .optimize = optimize, .imports = scope_imports }), b.createModule(.{ .root_source_file = b.path("src/anim/root.zig"), .target = target, .optimize = optimize, .imports = anim_imports }), b.createModule(.{ .root_source_file = b.path("src/glsl.zig"), .target = target, .optimize = optimize }), b.createModule(.{ .root_source_file = b.path("src/abi.zig"), .target = target, .optimize = optimize }), b.createModule(.{ .root_source_file = b.path("src/sketch/root.zig"), .target = target, .optimize = optimize, .imports = sketch_imports }), b.createModule(.{ .root_source_file = b.path("src/math/root.zig"), .target = target, .optimize = optimize }), b.createModule(.{ .root_source_file = b.path("src/host/root.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "c", .module = c }, .{ .name = "tracy", .module = tracy } } }), }) |module| test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = module })).step); // The noise tests again on wasm32 as the web builds it, under Node's // WASI: the golden bits must come out the same in the browser as // natively. (Only noise: LLVM 21 cannot select code for one of the // Bézier tests' vector constants on wasm32 in release modes.) const wasm_math = b.addTest(.{ .root_module = b.createModule(.{ .root_source_file = b.path("src/math/noise.zig"), .target = b.resolveTargetQuery(.{ .cpu_arch = .wasm32, .os_tag = .wasi }), .optimize = .ReleaseSafe, }) }); const wasi = Build.Step.Run.create(b, "noise tests on wasm32-wasi"); wasi.addFileArg(sb.program(&sb.shared.node, &.{"node"})); wasi.addArg("--no-warnings"); wasi.addFileArg(b.path("tools/wasi_run.mjs")); wasi.addArtifactArg(wasm_math); // The test runner's progress is not a warning. _ = wasi.captureStdErr(.{}); wasi.expectExitCode(0); test_step.dependOn(&wasi.step); // A sketch reloaded mid-run with a changed layout: state carried over by // field name, through the real dlopen path and the headless host. const v1 = sb.app(.{ .name = "counter", .root_source_file = b.path("test/counter_v1.zig") }).addLibrary(); const v2 = sb.app(.{ .name = "counter", .root_source_file = b.path("test/counter_v2.zig") }).addLibrary(); // Command.shape on the native host: the parity cases, screenshotted // and checked pixel by pixel (tools/shapes_web.mjs compares the same // sketch in headless Chrome: `zig build test-web`). const shapes = sb.app(.{ .name = "shapes", .root_source_file = b.path("test/shapes.zig") }); const shapes_native = shapes.addScript(shapes.addExecutable(), b.path("test/shapes.script"), .{}); test_step.dependOn(&shapes_native.step); const shapes_web = Build.Step.Run.create(b, "shapes in headless Chrome"); shapes_web.addFileArg(sb.program(&sb.shared.node, &.{"node"})); shapes_web.addFileArg(b.path("tools/shapes_web.mjs")); shapes_web.addDirectoryArg(shapes.addWeb(.{}).dir); shapes_web.addFileArg(b.path(".zig-cache/shapes/native.png")); shapes_web.addFileArg(b.findProgramLazy(.{ .names = &.{ "google-chrome-stable", "google-chrome", "chromium", "chromium-browser" } })); shapes_web.step.dependOn(&shapes_native.step); shapes_web.has_side_effects = true; shapes_web.expectExitCode(0); const test_web = b.step("test-web", "Compare shapes, targets, blending and images in headless Chrome with the native host, and time 5000 circles"); test_web.dependOn(&shapes_web.step); // Targets, blend modes, image placement and tint, colours per subpath // (test/render.zig): natively, checked pixel by pixel, and in Chrome. const render = sb.app(.{ .name = "render", .root_source_file = b.path("test/render.zig") }); const render_native = render.addScript(render.addExecutable(), b.path("test/render.script"), .{}); test_step.dependOn(&render_native.step); const render_web = Build.Step.Run.create(b, "render in headless Chrome"); render_web.addFileArg(sb.program(&sb.shared.node, &.{"node"})); render_web.addFileArg(b.path("tools/render_web.mjs")); render_web.addDirectoryArg(render.addWeb(.{}).dir); render_web.addFileArg(b.path(".zig-cache/render/native.png")); render_web.addFileArg(b.findProgramLazy(.{ .names = &.{ "google-chrome-stable", "google-chrome", "chromium", "chromium-browser" } })); render_web.step.dependOn(&render_native.step); render_web.has_side_effects = true; render_web.expectExitCode(0); test_web.dependOn(&render_web.step); // `Host.textSize` against the text drawn (test/text.zig). const text = sb.app(.{ .name = "text", .root_source_file = b.path("test/text.zig") }); test_step.dependOn(&text.addScript(text.addExecutable(), b.path("test/text.script"), .{}).step); // The anim module's player on its test scenes: a live one with a // custom object between vector objects, and a compiled one, which is // also exported, at half size. const live = sb.addScene(.{ .root_source_file = b.path("test/scene_live.zig") }); test_step.dependOn(&live.app.addScript(live.app.addExecutable(), b.path("test/scene_live.script"), .{}).step); const compiled = sb.addScene(.{ .root_source_file = b.path("test/scene_compiled.zig") }); const compiled_exe = compiled.app.addExecutable(); const compiled_script = compiled.app.addScript(compiled_exe, b.path("test/scene_compiled.script"), .{}); compiled_script.addArg("--define"); compiled_script.addPrefixedDirectoryArg("frames=", compiled.app.addExport(compiled_exe, .{ .fps = 30, .size = .{ 640, 360 }, .frames = 200 }).frames); test_step.dependOn(&compiled_script.step); // Both vector renderers against resvg, through the host (tools/svgdiff.py). const svgview = sb.app(.{ .name = "svgview", .root_source_file = b.path("test/svgview.zig"), .imports = &.{.{ .name = "vector", .module = sb.modules.vector }} }); const diff = b.addSystemCommand(&.{ "python3", "tools/svgdiff.py" }); diff.addArtifactArg(svgview.addExecutable()); diff.addDirectoryArg(b.path("test/svg")); diff.addArg(".zig-cache/svgdiff"); diff.setCwd(b.path(".")); diff.has_side_effects = true; b.step("diff", "Compare the CPU and GPU vector renderers with resvg").dependOn(&diff.step); test_step.dependOn(&diff.step); // Timings always in release mode: a debug build measures nothing useful. 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 = "vector", .module = sb.modules.vector }, .{ .name = "abi", .module = abi }, .{ .name = "anim", .module = sb.modules.anim }, .{ .name = "scene", .module = compiled.module }, .{ .name = "typst", .module = compiled.typst }, }, }), })); bench.has_side_effects = true; b.step("bench", "Time parsing and drawing a scene's Typst (release mode, must be under 1ms)").dependOn(&bench.step); // After the tests above, not beside them: it measures time. for (test_step.dependencies.items) |step| bench.step.dependOn(step); test_step.dependOn(&bench.step); // The examples, so they always compile. for ([_][]const u8{ "pen", "flock" }) |example| { test_step.dependOn(&sb.app(.{ .name = example, .root_source_file = b.path(b.fmt("examples/{s}.zig", .{example})) }).addLibrary().step); } // The README's example, so the documentation always compiles. test_step.dependOn(&sb.app(.{ .name = "readme", .root_source_file = b.path("test/readme.zig") }).addLibrary().step); // Export: two builds of one sketch export the same frames, on the // export's own clock (test/export.script); the raw stream is as long as // its frames, up to where the sketch quits; and ffmpeg, if there is // one, makes a video of it with as many. const export_a = sb.app(.{ .name = "export-a", .root_source_file = b.path("test/export.zig") }); const export_b = sb.app(.{ .name = "export-b", .root_source_file = b.path("test/export.zig") }); const export_exe = export_a.addExecutable(); const export_options: App.ExportOptions = .{ .fps = 30, .frames = 5, .size = .{ 320, 180 } }; const exported = export_a.addScript(export_exe, b.path("test/export.script"), .{}); exported.addArg("--define"); exported.addPrefixedDirectoryArg("a=", export_a.addExport(export_exe, export_options).frames); exported.addArg("--define"); exported.addPrefixedDirectoryArg("b=", export_b.addExport(export_b.addExecutable(), export_options).frames); test_step.dependOn(&exported.step); const raw = b.addSystemCommand(&.{ "sh", "-c", \\set -e \\test "$("$0" --state "$1" --export - --fps 30 --size 320x180 | wc -c)" = $((320 * 180 * 4 * 8)) \\command -v ffmpeg >/dev/null && command -v ffprobe >/dev/null || exit 0 \\"$0" --state "$1" --export - --fps 30 --size 320x180 | ffmpeg -loglevel error -y -f rawvideo -pix_fmt rgba -s 320x180 -r 30 -i - -pix_fmt yuv420p "$2" \\test "$(ffprobe -v error -count_frames -select_streams v:0 -show_entries stream=nb_read_frames -of csv=p=0 "$2")" = 8 }); raw.addArtifactArg(export_exe); _ = raw.addOutputFileArg("raw.state"); _ = raw.addOutputFileArg("raw.mp4"); raw.expectExitCode(0); test_step.dependOn(&raw.step); const reload = b.addRunArtifact(host_exe); reload.addArgs(&.{ "--headless", "--fresh", "--script" }); reload.addFileArg(b.path("test/reload.script")); reload.addArg("--state"); _ = reload.addOutputFileArg("counter.state"); reload.addArg("--define"); reload.addPrefixedArtifactArg("v2=", v2); reload.addArtifactArg(v1); reload.expectExitCode(0); test_step.dependOn(&reload.step); // Recorded input replays to the same state: played, seeked, stepped, // and after a live pointer move (core host behaviour, not an API). const replay = b.addRunArtifact(host_exe); replay.addArgs(&.{ "--headless", "--fresh", "--script" }); replay.addFileArg(b.path("test/replay.script")); replay.addArg("--state"); _ = replay.addOutputFileArg("replay.state"); replay.addArtifactArg(sb.app(.{ .name = "replay", .root_source_file = b.path("test/replay.zig") }).addLibrary()); replay.expectExitCode(0); test_step.dependOn(&replay.step); } fn cModule(b: *Build, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode) *Build.Module { const sdl_dep = b.dependency("sdl", .{ .target = target, .optimize = optimize }); const sdl = sdl_dep.artifact("SDL3"); if (target.result.os.tag == .linux) fixSdlThreadCleanup(b, sdl.root_module, sdl_dep.path("src")); fixSdlVulkanAllocationLeak(b, sdl.root_module, sdl_dep.path("src")); const translator: translate_c.Translator = .init(b.dependency("translate_c", .{}), .{ .c_source_file = b.addWriteFiles().add("c.h", \\#define SDL_DISABLE_OLD_NAMES \\#include \\#include "codecs.h" \\#include "text.h" ), .target = target, .optimize = optimize, }); translator.linkLibrary(sdl); translator.addIncludePath(b.path("vendor")); translator.mod.addCSourceFile(.{ .file = b.path("vendor/codecs.c"), .flags = &.{"-fno-sanitize=undefined"} }); if (target.result.os.tag == .linux) { translator.mod.addCSourceFile(.{ .file = b.path("vendor/text.c"), .flags = &.{"-std=c23"} }); translator.mod.linkSystemLibrary("pangocairo-1.0", .{ .use_pkg_config = .force }); translator.mod.linkSystemLibrary("pangoft2-1.0", .{ .use_pkg_config = .force }); } return translator.mod; } /// SDL 3.4.14 gives its pthread TLS key no destructor, so threads SDL did not /// create (PipeWire's) leave error storage behind when they exit. Compile the /// original backend with an exit destructor; the pinned package is untouched. fn fixSdlThreadCleanup(b: *Build, sdl: *Build.Module, source: Build.LazyPath) void { var flags: ?[]const []const u8 = null; for (sdl.link_objects.items) |object| { if (object != .c_source_files) continue; const group = object.c_source_files; for (group.files, 0..) |file, i| { if (!std.mem.eql(u8, file, "src/thread/pthread/SDL_systls.c")) continue; const files = b.allocator.alloc([]const u8, group.files.len - 1) catch @panic("OOM"); @memcpy(files[0..i], group.files[0..i]); @memcpy(files[i..], group.files[i + 1 ..]); group.files = files; flags = group.flags; break; } } std.debug.assert(flags != null); const patched = b.addWriteFiles().add("SDL_systls_cleanup.c", \\#include \\#include "SDL_internal.h" \\#include "thread/SDL_systhread.h" \\static void sketchbook_cleanup_tls(void *data) { \\ /* pthread clears the key before calling us; SDL_CleanupTLS reads it. */ \\ if (SDL_SYS_SetTLSData(data)) SDL_CleanupTLS(); \\} \\#define pthread_key_create(key, destructor) pthread_key_create(key, sketchbook_cleanup_tls) \\#include "thread/pthread/SDL_systls.c" ); sdl.addIncludePath(source); sdl.addCSourceFile(.{ .file = patched, .flags = flags.? }); } /// SDL 3.4's Vulkan backend leaks a memory allocation's region list and /// mutex when `vkAllocateMemory` fails (SDL_gpu_vulkan.c, /// `VULKAN_INTERNAL_AllocateMemory`), which it then survives by trying /// another memory type. Many headless hosts at once (parallel `e2e`) run /// small heaps out, and the leak check failed random scripts. The file is /// compiled from a copy with the two frees added. /// /// The copy also never defragments memory. A defragmentation runs inside /// whichever command buffer is submitted next, moves the textures of a /// fragmented allocation to new ones and re-points their handles, and the /// host submits a sketch's GPU passes while the 2D renderer's command /// buffer for the frame is still being recorded: what that had drawn so /// far went to the old texture and the rest to the copy, which shows the /// previous frame under it (seen after a large texture was freed, at /// 1920x1080 and up). Freed memory is still reused; it is only not /// compacted. With relocation disabled, small transfer buffers can also /// suballocate safely instead of freeing hundreds of dedicated Vulkan /// allocations during presentation. fn fixSdlVulkanAllocationLeak(b: *Build, sdl: *Build.Module, source: Build.LazyPath) void { const file = "src/gpu/vulkan/SDL_gpu_vulkan.c"; var found = false; var flags: []const []const u8 = &.{}; for (sdl.link_objects.items) |object| { if (object != .c_source_files) continue; const group = object.c_source_files; for (group.files, 0..) |f, i| { if (!std.mem.eql(u8, f, file)) continue; const files = b.allocator.alloc([]const u8, group.files.len - 1) catch @panic("OOM"); @memcpy(files[0..i], group.files[0..i]); @memcpy(files[i..], group.files[i + 1 ..]); group.files = files; flags = group.flags; found = true; break; } } if (!found) return; const tool = b.addExecutable(.{ .name = "reload-edit", .root_module = b.createModule(.{ .root_source_file = b.path("tools/reload_edit.zig"), .target = b.graph.host, }) }); const edit = b.addRunArtifact(tool); edit.setName("patch SDL_gpu_vulkan.c"); edit.addFileInput(source.path(b, "gpu/vulkan/SDL_gpu_vulkan.c")); edit.addDirectoryArg(source.path(b, "gpu/vulkan")); const out = edit.addOutputDirectoryArg("vulkan"); edit.addArgs(&.{ "SDL_gpu_vulkan.c", " // Uh oh, we couldn't allocate, time to clean up\n SDL_free(allocation->freeRegions);\n", " // Uh oh, we couldn't allocate, time to clean up\n SDL_free(allocation->freeRegions);\n SDL_free(allocation->usedRegions);\n SDL_DestroyMutex(allocation->memoryLock);\n", "SDL_gpu_vulkan.c", " VULKAN_INTERNAL_MarkAllocationsForDefrag(renderer);\n", " (void)VULKAN_INTERNAL_MarkAllocationsForDefrag;\n", "SDL_gpu_vulkan.c", " VULKAN_BUFFER_TYPE_TRANSFER,\n true, // Dedicated allocations preserve the data even if a defrag is triggered.\n", " VULKAN_BUFFER_TYPE_TRANSFER,\n false, // Sketchbook disables defrag, so small transfers can share allocations.\n", }); // The copy's relative includes (`../SDL_sysgpu.h`) resolve from the // original directory. sdl.addIncludePath(source.path(b, "gpu/vulkan")); sdl.addIncludePath(source); sdl.addCSourceFile(.{ .file = out.path(b, "SDL_gpu_vulkan.c"), .flags = flags }); } // --------------------------------------------------------------------------- // Build API for apps pub const Options = struct { target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, /// This package's name in the app's build.zig.zon. dependency: []const u8 = "sketchbook", /// An existing Tracy checkout; null leaves native profiling compiled out. tracy: ?[]const u8 = null, /// The optimize mode of the executables `e2e` plays scripts with /// (`App.addScriptExecutable`); `optimize` when null. Pass it a /// `b.option`, say `-Dscript-optimize=ReleaseSafe`, when Debug is too /// slow for a sketch's scripts. Only the host's and the app's Zig code /// change mode; SDL and the C pieces keep `optimize`. script_optimize: ?std.builtin.OptimizeMode = null, }; pub fn init(b: *Build, options: Options) Sketchbook { const dep = b.dependency(options.dependency, .{ .target = options.target, .optimize = options.optimize, .tracy = options.tracy orelse "" }); const shared: *Shared = .create(b); for ([_][]const u8{ "vector_shaders", "scope_shaders" }) |name| { shared.web_twins.put(b.graph.arena, dep.module(name), dep.module(b.fmt("{s}_web", .{name}))) catch @panic("OOM"); } return .{ .b = b, .target = options.target, .optimize = options.optimize, .modules = .{ .abi = dep.module("abi"), .sketch = dep.module("sketch"), .host = dep.module("host"), .tracy = dep.module("tracy"), .vector = dep.module("vector"), .scope = dep.module("scope"), .anim = dep.module("anim") }, .host_exe = dep.artifact("sketchbook"), .probe_exe = dep.artifact("sketchbook-probe"), .web = dep.path("web"), .glsl = dep.path("src/glsl.zig"), .tools = dep.path("tools"), .anim_dir = dep.path("src/anim"), .script_optimize = options.script_optimize orelse options.optimize, .shared = shared, }; } /// What every copy of a `Sketchbook` value shares. const Shared = struct { /// SPIR-V shader modules and their WGSL twins (see `addShaders`). web_twins: std.AutoArrayHashMapUnmanaged(*Build.Module, *Build.Module) = .empty, /// How each shader module was made, so `addReloadCheck` can make it /// again from edited sources. recipes: std.AutoArrayHashMapUnmanaged(*Build.Module, Recipe) = .empty, /// Lookups of external tools, made once, run when a step needs them. glslc: ?Build.LazyPath = null, naga: ?Build.LazyPath = null, miniserve: ?Build.LazyPath = null, node: ?Build.LazyPath = null, openssl: ?Build.LazyPath = null, /// A self-signed certificate and its key, for `addServe`. certificate: ?Certificate = null, const Certificate = struct { cert: Build.LazyPath, key: Build.LazyPath }; const Recipe = union(enum) { glsl: Sketchbook.ShaderOptions, zig: Sketchbook.ZigShaderOptions }; fn create(b: *Build) *Shared { const shared = b.graph.arena.create(Shared) catch @panic("OOM"); shared.* = .{}; return shared; } }; pub const Sketchbook = struct { b: *Build, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, /// `vector`: SVG, cubic geometry, and CPU and GPU renderers. `scope`: /// waveform, spectrogram, spectrum and oscilloscope views of a sound. /// `anim`: manim-style scenes as code (see `addScene`). modules: struct { abi: *Build.Module, sketch: *Build.Module, host: *Build.Module, tracy: *Build.Module, vector: *Build.Module, scope: *Build.Module, anim: *Build.Module }, /// The generic host: loads and hot-reloads a sketch library. host_exe: *Build.Step.Compile, /// Prints any sketch's state file. probe_exe: *Build.Step.Compile, /// `host.js` and the `index.html` template. web: Build.LazyPath, /// The GLSL declaration generator (see `addGlslLayouts`). glsl: Build.LazyPath, /// Build-time tools (`spirv_strip.zig`, `reload_edit.zig`, ...). tools: Build.LazyPath, /// The `anim` module's player and Typst generator (see `addScene`). anim_dir: Build.LazyPath, /// The optimize mode of executables that play scripts (`e2e`): Debug /// is slow for per-pixel loops, and that is often the only reason to /// build a script run differently from the rest. script_optimize: std.builtin.OptimizeMode, shared: *Shared, pub const GlslLayouts = struct { run: *Build.Step.Run, /// `.glsl` for each type: pass it to `addGlslc` as an include. dir: Build.LazyPath, }; /// GLSL declarations generated from Zig types, so shaders and Zig share /// one definition (see `glsl.zig`; std140 is checked as it runs). /// `module` holds the types and must not depend on the shaders; /// `types` are paths inside it, like "Vertex" or "gpu.Paint". pub fn addGlslLayouts(sb: Sketchbook, options: struct { module: *Build.Module, types: []const []const u8 }) GlslLayouts { const b = sb.b; var paths: std.ArrayList(u8) = .empty; for (options.types) |t| paths.print(b.allocator, "\"{s}\", ", .{t}) catch @panic("OOM"); const tool = b.addExecutable(.{ .name = "glsl-layouts", .root_module = b.createModule(.{ .root_source_file = b.addWriteFiles().add("glsl_layouts.zig", b.fmt( \\const std = @import("std"); \\pub fn main(init: std.process.Init) !void {{ \\ var args = init.minimal.args.iterate(); \\ _ = args.skip(); \\ var dir = try std.Io.Dir.cwd().createDirPathOpen(init.io, args.next().?, .{{}}); \\ defer dir.close(init.io); \\ try @import("glsl").generate(@import("layouts"), &.{{ {s}}}, init.io, dir); \\}} , .{paths.items})), .target = b.graph.host, .imports = &.{ .{ .name = "glsl", .module = b.createModule(.{ .root_source_file = sb.glsl }) }, .{ .name = "layouts", .module = options.module }, }, }), }); const run = b.addRunArtifact(tool); return .{ .run = run, .dir = run.addOutputDirectoryArg("glsl") }; } pub const Glslc = struct { run: *Build.Step.Run, spirv: Build.LazyPath, }; /// One GLSL file compiled to SPIR-V by `glslc`. pub fn addGlslc(sb: Sketchbook, options: struct { source: Build.LazyPath, include_dirs: []const Build.LazyPath = &.{}, /// Macros defined for the source, as `NAME` or `NAME=VALUE`. defines: []const []const u8 = &.{}, target_env: []const u8 = "vulkan1.1", optimize: bool = true, }) Glslc { const b = sb.b; const name = fileName(options.source); const run = Build.Step.Run.create(b, b.fmt("glslc {s}", .{name})); run.addFileArg(sb.glslc()); run.addArg(b.fmt("--target-env={s}", .{options.target_env})); if (options.optimize) run.addArg("-O"); for (options.defines) |define| run.addArg(b.fmt("-D{s}", .{define})); for (options.include_dirs) |dir| run.addPrefixedDirectoryArg("-I", dir); // The files the source #includes, for the cache: editing one // recompiles every shader that includes it. run.addArgs(&.{ "-MD", "-MF" }); _ = run.addDepFileOutputArg(b.fmt("{s}.d", .{name})); run.addArg("-o"); const spirv = run.addOutputFileArg(b.fmt("{s}.spv", .{name})); run.addFileArg(options.source); return .{ .run = run, .spirv = spirv }; } pub const Shaders = struct { /// SPIR-V, one `pub const : []const u8` per shader, 4-byte /// aligned as Vulkan reads it: the module to import. module: *Build.Module, /// The same declarations in WGSL, translated from the SPIR-V by /// `naga`. The web build puts it in place of `module` wherever /// `module` is imported (see `addWeb`), so sketches import one /// module and never choose. web: *Build.Module, }; /// GLSL shaders for every host: compiled to SPIR-V, and for the web /// compiled again with `SKETCHBOOK_WEB` defined and translated to WGSL, /// which only the web build waits for. Each source is declared under its /// file name with dots as underscores: `tuner.comp` is `tuner_comp`. /// /// WGSL lacks a little GLSL has: no write-only storage buffers (declare /// them `buffer`), and no `coherent` (WGSL's barriers make storage /// writes visible to the workgroup anyway, so leave it out under /// `#ifdef SKETCHBOOK_WEB`). pub const ShaderOptions = struct { sources: []const Build.LazyPath, /// Uniform and vertex layouts generated from Zig types, which the /// sources `#include` as `.glsl` (see `addGlslLayouts`). layouts: ?struct { module: *Build.Module, types: []const []const u8 } = null, /// More `#include` directories. include_dirs: []const Build.LazyPath = &.{}, }; pub fn addShaders(sb: Sketchbook, options: ShaderOptions) Shaders { const b = sb.b; const include_dirs = b.graph.arena.alloc(Build.LazyPath, options.include_dirs.len + 1) catch @panic("OOM"); @memcpy(include_dirs[0..options.include_dirs.len], options.include_dirs); var dirs: []const Build.LazyPath = include_dirs[0..options.include_dirs.len]; if (options.layouts) |layouts| { include_dirs[options.include_dirs.len] = sb.addGlslLayouts(.{ .module = layouts.module, .types = layouts.types }).dir; dirs = include_dirs; } const native = b.addWriteFiles(); const web = b.addWriteFiles(); var native_source: std.ArrayList(u8) = .empty; var web_source: std.ArrayList(u8) = .empty; for (options.sources) |source| { const file = fileName(source); const name = std.mem.replaceOwned(u8, b.graph.arena, file, ".", "_") catch @panic("OOM"); const spirv = sb.addGlslc(.{ .source = source, .include_dirs = dirs }).spirv; _ = native.addCopyFile(spirv, b.fmt("{s}.spv", .{name})); native_source.print(b.graph.arena, "const {s}_words align(4) = @embedFile(\"{s}.spv\").*;\npub const {s}: []const u8 = &{s}_words;\n", .{ name, name, name, name }) catch @panic("OOM"); const translate = Build.Step.Run.create(b, b.fmt("naga {s}", .{file})); translate.addFileArg(sb.naga()); // SDL_GPU flips Vulkan's viewport, so the SPIR-V's clip space is // already WebGPU's (y up): naga must not flip it again. translate.addArg("--keep-coordinate-space"); translate.addFileArg(sb.addGlslc(.{ .source = source, .include_dirs = dirs, .defines = &.{"SKETCHBOOK_WEB"} }).spirv); _ = web.addCopyFile(translate.addOutputFileArg(b.fmt("{s}.wgsl", .{name})), b.fmt("{s}.wgsl", .{name})); web_source.print(b.graph.arena, "pub const {s}: []const u8 = @embedFile(\"{s}.wgsl\");\n", .{ name, name }) catch @panic("OOM"); } const shaders: Shaders = .{ .module = b.createModule(.{ .root_source_file = native.add("spirv.zig", native_source.items) }), .web = b.createModule(.{ .root_source_file = web.add("wgsl.zig", web_source.items) }), }; sb.shared.web_twins.put(b.graph.arena, shaders.module, shaders.web) catch @panic("OOM"); var kept = options; kept.sources = b.graph.arena.dupe(Build.LazyPath, options.sources) catch @panic("OOM"); kept.include_dirs = b.graph.arena.dupe(Build.LazyPath, options.include_dirs) catch @panic("OOM"); sb.shared.recipes.put(b.graph.arena, shaders.module, .{ .glsl = kept }) catch @panic("OOM"); return shaders; } pub const ZigShaderOptions = struct { /// One shader per file, its entry point `export fn main` with a /// SPIR-V calling convention (`.spirv_fragment`, `.spirv_vertex`). sources: []const Build.LazyPath, /// Modules the shaders import (shared uniform structs, helpers). imports: []const Build.Module.Import = &.{}, }; /// Shaders written in Zig, as `addShaders` makes them from GLSL: the /// same `Shaders` (SPIR-V module, WGSL twin swapped in for the web), so /// a sketch cannot tell which language a shader came from. `fill.zig` /// is declared as `fill`. /// /// Each source is compiled by Zig's own SPIR-V backend. The steps, and /// why each one is there: /// - target `spirv32-vulkan`: `spirv64` asks for physical storage /// buffer pointers, which naga refuses; /// - the self-hosted backend (`use_llvm = false`), ReleaseFast: through /// LLVM the object comes out empty, without an error; /// - `tools/spirv_strip.zig` then drops the `Aligned` memory operands /// Zig puts on every OpLoad/OpStore: Vulkan accepts them, naga's /// SPIR-V reader does not ("invalid operand count"); /// - for the web, `naga --keep-coordinate-space` translates the /// stripped SPIR-V to WGSL, as for GLSL. /// /// What shader code can be: no table-driven `std.math` (`atan2` indexes /// const tables through generic pointers, which logical addressing /// forbids: call GLSL.std.450 through inline assembly), and no /// `@Vector` in an `extern struct` shared with the CPU (use `[2]f32` /// there and `@Vector` only when `builtin.cpu.arch.isSpirV()`; std140 /// wants a vec2 array stride of 16, which a `[2]f32` array lacks). pub fn addZigShaders(sb: Sketchbook, options: ZigShaderOptions) Shaders { const b = sb.b; const spirv = b.resolveTargetQuery(.{ .cpu_arch = .spirv32, .os_tag = .vulkan }); const strip = b.addExecutable(.{ .name = "spirv-strip", .root_module = b.createModule(.{ .root_source_file = sb.tools.path(b, "spirv_strip.zig"), .target = b.graph.host, }) }); const native = b.addWriteFiles(); const web = b.addWriteFiles(); var native_source: std.ArrayList(u8) = .empty; var web_source: std.ArrayList(u8) = .empty; for (options.sources) |source| { const name = std.fs.path.stem(fileName(source)); const object = b.addObject(.{ .name = name, .root_module = b.createModule(.{ .root_source_file = source, .target = spirv, .optimize = .ReleaseFast, .imports = options.imports }), .use_llvm = false, }); const stripped = b.addRunArtifact(strip); stripped.addFileArg(object.getEmittedBin()); const spv = stripped.addOutputFileArg(b.fmt("{s}.spv", .{name})); _ = native.addCopyFile(spv, b.fmt("{s}.spv", .{name})); native_source.print(b.graph.arena, "const {s}_words align(4) = @embedFile(\"{s}.spv\").*;\npub const {s}: []const u8 = &{s}_words;\n", .{ name, name, name, name }) catch @panic("OOM"); const translate = Build.Step.Run.create(b, b.fmt("naga {s}", .{fileName(source)})); translate.addFileArg(sb.naga()); translate.addArg("--keep-coordinate-space"); translate.addFileArg(spv); _ = web.addCopyFile(translate.addOutputFileArg(b.fmt("{s}.wgsl", .{name})), b.fmt("{s}.wgsl", .{name})); web_source.print(b.graph.arena, "pub const {s}: []const u8 = @embedFile(\"{s}.wgsl\");\n", .{ name, name }) catch @panic("OOM"); } const shaders: Shaders = .{ .module = b.createModule(.{ .root_source_file = native.add("spirv.zig", native_source.items) }), .web = b.createModule(.{ .root_source_file = web.add("wgsl.zig", web_source.items) }), }; sb.shared.web_twins.put(b.graph.arena, shaders.module, shaders.web) catch @panic("OOM"); sb.shared.recipes.put(b.graph.arena, shaders.module, .{ .zig = .{ .sources = b.graph.arena.dupe(Build.LazyPath, options.sources) catch @panic("OOM"), .imports = b.graph.arena.dupe(Build.Module.Import, options.imports) catch @panic("OOM"), } }) catch @panic("OOM"); return shaders; } /// `glslc`, from shaderc or the Vulkan SDK. fn glslc(sb: Sketchbook) Build.LazyPath { const sdk = if (sb.b.graph.environ_map.get("VULKAN_SDK")) |dir| sb.b.pathJoin(&.{ dir, "bin", "glslc" }) else "glslc"; return sb.program(&sb.shared.glslc, &.{ "glslc", sdk }); } /// `naga`, from `cargo install naga-cli`: on PATH, or where cargo puts it. fn naga(sb: Sketchbook) Build.LazyPath { const env = &sb.b.graph.environ_map; const cargo = if (env.get("CARGO_HOME")) |home| sb.b.pathJoin(&.{ home, "bin", "naga" }) else if (env.get("HOME")) |home| sb.b.pathJoin(&.{ home, ".cargo", "bin", "naga" }) else "naga"; return sb.program(&sb.shared.naga, &.{ "naga", cargo }); } /// A tool found on PATH when a step needs it, looked up once. pub fn program(sb: Sketchbook, slot: *?Build.LazyPath, names: []const []const u8) Build.LazyPath { if (slot.* == null) slot.* = sb.b.findProgramLazy(.{ .names = names }); return slot.*.?; } /// A self-signed certificate for serving over https, made once by /// `openssl` and kept in the cache: browsers ask to trust it once. fn certificate(sb: Sketchbook) Shared.Certificate { if (sb.shared.certificate == null) { const b = sb.b; const run = Build.Step.Run.create(b, "self-signed certificate"); run.addFileArg(sb.program(&sb.shared.openssl, &.{"openssl"})); run.addArgs(&.{ "req", "-x509", "-newkey", "ec", "-pkeyopt", "ec_paramgen_curve:prime256v1", "-nodes", "-days", "3650", "-subj", "/CN=sketchbook" }); run.addArg("-keyout"); const key = run.addOutputFileArg("key.pem"); run.addArg("-out"); // Its progress on stderr is not a warning. _ = run.captureStdErr(.{}); sb.shared.certificate = .{ .cert = run.addOutputFileArg("cert.pem"), .key = key }; } return sb.shared.certificate.?; } /// `module` as the web build compiles it: each shader module in its /// imports, however deep, replaced by its WGSL twin, and each module on /// the way copied to import the copy. Modules nothing swaps below are /// shared as they are. fn webModule(sb: Sketchbook, module: *Build.Module, copies: *std.AutoArrayHashMapUnmanaged(*Build.Module, *Build.Module)) *Build.Module { const arena = sb.b.graph.arena; if (sb.shared.web_twins.get(module)) |twin| return twin; if (copies.get(module)) |done| return done; // An import cycle comes back here as itself: unchanged, which is // right unless a shader module hides inside the cycle. copies.put(arena, module, module) catch @panic("OOM"); var swapped = false; const imports = arena.alloc(*Build.Module, module.import_table.count()) catch @panic("OOM"); for (module.import_table.values(), imports) |imported, *web| { web.* = sb.webModule(imported, copies); swapped = swapped or web.* != imported; } if (!swapped) return module; const copy = arena.create(Build.Module) catch @panic("OOM"); copy.init(module.owner, .{ .existing = module }); copy.import_table = .empty; copy.cached_graph = .{ .modules = &.{}, .names = &.{} }; for (module.import_table.keys(), imports) |name, web| copy.addImport(name, web); copies.put(arena, module, copy) catch @panic("OOM"); return copy; } pub const SceneOptions = struct { /// The app's name; the scene file's by default (`scenes/intro.zig` /// is `intro`). name: ?[]const u8 = null, /// The scene: a file with `pub const scene = anim.Scene(construct)` /// or `anim.Live(frame, typst)`. root_source_file: Build.LazyPath, /// Imports for the scene file, besides `anim` and `sketch`. imports: []const Build.Module.Import = &.{}, }; pub const Scene = struct { /// The player built around the scene: an app like any other /// (`addSteps`, `addExecutable`, `addScript`, `addExport`). app: App, /// The scene file's module. module: *Build.Module, /// Its Typst sources as SVG: `find(source) ?[]const u8`. typst: *Build.Module, }; /// The `anim` player (`src/anim/player.zig`) built around one scene /// file, whose Typst is compiled here, at build time. pub fn addScene(sb: Sketchbook, options: SceneOptions) Scene { const b = sb.b; const imports = b.allocator.alloc(Build.Module.Import, options.imports.len + 2) catch @panic("OOM"); imports[0] = .{ .name = "anim", .module = sb.modules.anim }; imports[1] = .{ .name = "sketch", .module = sb.modules.sketch }; @memcpy(imports[2..], options.imports); const scene = b.createModule(.{ .root_source_file = options.root_source_file, .imports = imports }); const typst = sb.addTypst(scene); return .{ .app = sb.app(.{ .name = options.name orelse std.fs.path.stem(fileName(options.root_source_file)), .root_source_file = sb.anim_dir.path(b, "player.zig"), .imports = &.{ .{ .name = "vector", .module = sb.modules.vector }, .{ .name = "anim", .module = sb.modules.anim }, .{ .name = "scene", .module = scene }, .{ .name = "typst", .module = typst }, }, }), .module = scene, .typst = typst, }; } /// Compiles the Typst sources a scene declares (`scene.typst_sources`), /// after its `typst_preamble`, with the `typst` CLI, and returns the /// module the player finds them in (see `src/anim/typst.zig`). `scene` /// is the scene file's module. A scene without Typst runs no `typst`. pub fn addTypst(sb: Sketchbook, scene: *Build.Module) *Build.Module { const b = sb.b; const tool = b.addExecutable(.{ .name = "typst-scene", .root_module = b.createModule(.{ .root_source_file = b.addWriteFiles().add("typst_scene.zig", \\const std = @import("std"); \\const scene = @import("scene"); \\pub fn main(init: std.process.Init) !void { \\ var args = init.minimal.args.iterate(); \\ _ = args.skip(); \\ const out = args.next().?; \\ const cache = args.next().?; \\ try @import("typst").generate(scene, scene.scene.typst_sources, init.arena.allocator(), init.io, out, cache); \\} ), .target = b.graph.host, .imports = &.{ .{ .name = "typst", .module = b.createModule(.{ .root_source_file = sb.anim_dir.path(b, "typst.zig") }) }, .{ .name = "scene", .module = scene }, }, }), }); const run = b.addRunArtifact(tool); const dir = run.addOutputDirectoryArg("typst"); // A cache that outlives the build cache's own entries: the local // .zig-cache, relative to the project root. run.setCwd(b.path(".")); run.addArg(".zig-cache/typst"); return b.createModule(.{ .root_source_file = dir.path(b, "typst.zig") }); } pub fn app(sb: Sketchbook, options: App.Options) App { const imports = sb.b.allocator.alloc(Build.Module.Import, options.imports.len + 1) catch @panic("OOM"); imports[0] = .{ .name = "sketch", .module = sb.modules.sketch }; @memcpy(imports[1..], options.imports); return .{ .sb = sb, .name = options.name, .root_source_file = options.root_source_file, .imports = imports, // No target: every artifact compiles it for its own. .module = sb.b.createModule(.{ .root_source_file = options.root_source_file, .imports = imports }), }; } }; pub const App = struct { sb: Sketchbook, name: []const u8, root_source_file: Build.LazyPath, imports: []const Build.Module.Import, /// The app's root, importing `sketch` and the app's own imports. module: *Build.Module, pub const Options = struct { name: []const u8, root_source_file: Build.LazyPath, /// Imports for the app's root module, besides `sketch`: for example /// `sb.modules.vector`, or shaders from `addSpirvModule`. imports: []const Build.Module.Import = &.{}, }; /// A root module around the app: `source` sees `app`, `sketch` and `host`. fn wrap(app: App, source: []const u8, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode) *Build.Module { const b = app.sb.b; const root = b.createModule(.{ .root_source_file = b.addWriteFiles().add("root.zig", source), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "app", .module = app.module }, .{ .name = "sketch", .module = app.sb.modules.sketch } }, }); if (std.mem.indexOf(u8, source, "\"host\"") != null) root.addImport("host", app.sb.modules.host); return root; } /// The hot-reloadable sketch: a shared library the host watches. pub fn addLibrary(app: App) *Build.Step.Compile { return app.sb.b.addLibrary(.{ .name = app.name, .linkage = .dynamic, .root_module = app.wrap("comptime { @import(\"sketch\").exportSketch(@import(\"app\")); }", app.sb.target, app.sb.optimize), }); } /// Host and sketch in one executable, nothing loaded at runtime: for /// shipping, and for scripts that must not depend on a library path. pub fn addExecutable(app: App) *Build.Step.Compile { return app.executable(app.sb.optimize); } /// The executable as scripts play it: built in `script_optimize` mode /// (see `Options`), the same as `addExecutable` unless that was set. pub fn addScriptExecutable(app: App) *Build.Step.Compile { return app.executable(app.sb.script_optimize); } fn executable(app: App, optimize: std.builtin.OptimizeMode) *Build.Step.Compile { return app.sb.b.addExecutable(.{ .name = app.name, .root_module = app.wrap( \\const std = @import("std"); \\pub fn main(init: std.process.Init) !void { \\ return @import("host").main(init, @import("sketch").sketch(@import("app"))); \\} , app.sb.target, optimize), }); } pub const WebOptions = struct { /// Directories copied next to the page, under their own `dest`. assets: []const Asset = &.{}, /// Replaces the generic page; `{title}` is substituted either way, /// and `{head}` with the links an installable app needs. index_html: ?Build.LazyPath = null, optimize: std.builtin.OptimizeMode = .ReleaseSafe, /// Makes the page an installable app that opens offline. pwa: ?Pwa = null, pub const Asset = struct { source: Build.LazyPath, dest: []const u8 }; /// A progressive web app: a manifest naming it, icons, and a /// service worker (`web/sw.js`) that keeps a copy of everything the /// page fetches, network first, so it opens offline and still shows /// each new build at once. Browsers allow service workers only in /// secure contexts (https, or localhost). pub const Pwa = struct { /// The app's name by default. name: ?[]const u8 = null, short_name: ?[]const u8 = null, description: []const u8 = "", /// CSS colours: behind the page while it starts, and the /// browser's chrome around it. background: []const u8 = "#000000", theme: []const u8 = "#000000", /// Square PNGs, served as `icon-.png`. Browsers want 192 /// and 512 pixels to offer installing. icons: []const Icon = &.{}, pub const Icon = struct { source: Build.LazyPath, size: u32 }; }; }; pub const Web = struct { wasm: *Build.Step.Compile, /// The page: `index.html`, `host.js`, `sketch.wasm` and assets. dir: Build.LazyPath, }; /// The browser build, as one directory ready to serve. pub fn addWeb(app: App, options: WebOptions) Web { const b = app.sb.b; var copies: std.AutoArrayHashMapUnmanaged(*Build.Module, *Build.Module) = .empty; var web_app = app; web_app.module = app.sb.webModule(app.module, &copies); const wasm = b.addExecutable(.{ .name = "sketch", .root_module = web_app.wrap("comptime { @import(\"sketch\").web.exportWeb(@import(\"app\")); }", b.resolveTargetQuery(.{ .cpu_arch = .wasm32, .os_tag = .freestanding }), options.optimize), }); wasm.entry = .disabled; wasm.rdynamic = true; wasm.export_memory = true; const files = b.addWriteFiles(); _ = files.addCopyFile(wasm.getEmittedBin(), "sketch.wasm"); _ = files.addCopyFile(app.sb.web.path(b, "host.js"), "host.js"); const page = b.addRunArtifact(b.addExecutable(.{ .name = "sketchbook-page", .root_module = b.createModule(.{ .root_source_file = b.addWriteFiles().add("page.zig", page_tool), .target = b.graph.host }), })); page.addFileArg(options.index_html orelse app.sb.web.path(b, "index.html")); page.addArg(app.name); page.addArg(if (options.pwa) |pwa| app.addPwa(files, pwa) else ""); _ = files.addCopyFile(page.addOutputFileArg("index.html"), "index.html"); for (options.assets) |asset| _ = files.addCopyDirectory(asset.source, asset.dest, .{}); return .{ .wasm = wasm, .dir = files.getDirectory() }; } /// Writes the manifest, icons and service worker into `files`, and /// returns what the page's `` needs for them. fn addPwa(app: App, files: *Build.Step.WriteFile, pwa: WebOptions.Pwa) []const u8 { const b = app.sb.b; const arena = b.graph.arena; const Icon = struct { src: []const u8, sizes: []const u8, type: []const u8 = "image/png", purpose: []const u8 = "any" }; const icons = arena.alloc(Icon, pwa.icons.len) catch @panic("OOM"); var touch: ?[]const u8 = null; for (pwa.icons, icons) |icon, *entry| { const name = b.fmt("icon-{d}.png", .{icon.size}); _ = files.addCopyFile(icon.source, name); entry.* = .{ .src = name, .sizes = b.fmt("{d}x{d}", .{ icon.size, icon.size }) }; // iOS takes its home-screen icon from the page, not the manifest. if (icon.size >= 180 and (touch == null or icon.size < 512)) touch = name; } const name = pwa.name orelse app.name; const manifest = std.json.Stringify.valueAlloc(arena, .{ .name = name, .short_name = pwa.short_name orelse name, .description = pwa.description, // Relative: the app works under any path it is served from. .start_url = ".", .scope = ".", .display = "standalone", .background_color = pwa.background, .theme_color = pwa.theme, .icons = icons, }, .{ .whitespace = .indent_2 }) catch @panic("OOM"); _ = files.add("manifest.webmanifest", manifest); _ = files.addCopyFile(app.sb.web.path(b, "sw.js"), "sw.js"); return b.fmt( \\ \\{s} , .{ pwa.theme, if (touch) |icon| b.fmt("\n", .{icon}) else "" }); } /// Serves an installed web build (`install`, under the prefix) with /// `miniserve`, over https on port 8042 of every interface, until /// stopped. Browsers give WebGPU and the microphone only to secure /// contexts, and https makes the page one from any device on the /// network, once the self-signed certificate is accepted; miniserve /// prints the addresses as QR codes, for phones. It serves the installed /// files, so `zig build web --watch` alongside shows each rebuild on /// reload. Its defaults are environment variables, so miniserve's /// options after `--` replace them (`-p 9000`). pub fn addServe(app: App, install: *Build.Step.InstallDir) *Build.Step.Run { const sb = app.sb; const b = sb.b; const prefix_relative = switch (install.options.install_dir) { .prefix => install.options.install_subdir, .custom => |dir| b.pathJoin(&.{ dir, install.options.install_subdir }), else => @panic("addServe: install the web build under the prefix"), }; const certificate = sb.certificate(); const run = Build.Step.Run.create(b, "miniserve"); run.addFileArg(sb.program(&sb.shared.miniserve, &.{"miniserve"})); run.addPrefixedFileArg("--tls-cert=", certificate.cert); run.addPrefixedFileArg("--tls-key=", certificate.key); for ([_][2][]const u8{ .{ "MINISERVE_PORT", "8042" }, .{ "MINISERVE_INTERFACE", "0.0.0.0" }, .{ "MINISERVE_INDEX", "index.html" }, .{ "MINISERVE_DISABLE_INDEXING", "true" }, .{ "MINISERVE_QRCODE", "true" }, // A rebuilt sketch shows on reload. .{ "MINISERVE_HEADER", "Cache-Control:no-cache" }, }) |env| run.setEnvironmentVariable(env[0], env[1]); run.addPassthruArgs(); run.addDirectoryArg(b.graph.path(.install_prefix, prefix_relative)); run.step.dependOn(&install.step); run.stdio = .inherit; run.has_side_effects = true; return run; } pub const RunOptions = struct { /// State file, relative to the working directory. state: ?[]const u8 = null, /// Where relative asset paths resolve; the project root by default. cwd: ?Build.LazyPath = null, }; /// Runs the generic host on the installed library. Rebuilding the library /// (`zig build lib --watch` in another terminal) reloads it in place. pub fn addRun(app: App, library: *Build.Step.Compile, options: RunOptions) *Build.Step.Run { const b = app.sb.b; const install = b.addInstallArtifact(library, .{}); const run = b.addRunArtifact(app.sb.host_exe); run.step.dependOn(&install.step); run.addArgs(&.{ "--state", options.state orelse b.fmt("{s}.state", .{app.name}) }); run.addFileArg(b.graph.path(.install_lib, library.out_filename)); run.setCwd(options.cwd orelse b.path(".")); run.stdio = .inherit; run.addPassthruArgs(); return run; } pub const ScriptOptions = struct { /// `{name}` substitutions for the script. defines: []const [2][]const u8 = &.{}, cwd: ?Build.LazyPath = null, }; /// Plays a script headless, with a throwaway state file, against /// `artifact`: the executable (`addExecutable`), or the hot-reloadable /// library (`addLibrary`) through the generic host, which scripts can /// `reload`. Fails when an expectation or a console line does. pub fn addScript(app: App, artifact: *Build.Step.Compile, script: Build.LazyPath, options: ScriptOptions) *Build.Step.Run { const b = app.sb.b; const library = artifact.isDynamicLibrary(); const run = b.addRunArtifact(if (library) app.sb.host_exe else artifact); run.addArgs(&.{ "--headless", "--fresh", "--script" }); run.addFileArg(script); run.addArg("--state"); // Named per script: runs of one app may share an output directory. _ = run.addOutputFileArg(b.fmt("{s}-{s}.state", .{ app.name, std.fs.path.stem(script.getDisplayName()) })); for (options.defines) |pair| run.addArgs(&.{ "--define", b.fmt("{s}={s}", .{ pair[0], pair[1] }) }); if (library) run.addArtifactArg(artifact); run.setCwd(options.cwd orelse b.path(".")); run.expectExitCode(0); run.has_side_effects = true; return run; } pub const ExportOptions = struct { fps: u32 = 60, /// Null: until the sketch quits (`f.quit()`). frames: ?u64 = null, /// The canvas of a sketch that takes the room it is given. size: ?[2]u32 = null, }; pub const Export = struct { run: *Build.Step.Run, /// `000000.png`, `000001.png`, ... frames: Build.LazyPath, }; /// Exports the frames of `exe` (`addExecutable`) as PNGs into a /// directory of the cache: headless, from fresh state, frame k at /// k/fps seconds whatever the wall clock does. pub fn addExport(app: App, exe: *Build.Step.Compile, options: ExportOptions) Export { const b = app.sb.b; const run = b.addRunArtifact(exe); run.addArg("--state"); _ = run.addOutputFileArg(b.fmt("{s}-export.state", .{app.name})); run.addArg("--export"); const frames = run.addOutputDirectoryArg("frames"); run.addArgs(&.{ "--fps", b.fmt("{d}", .{options.fps}) }); if (options.frames) |n| run.addArgs(&.{ "--frames", b.fmt("{d}", .{n}) }); if (options.size) |size| run.addArgs(&.{ "--size", b.fmt("{d}x{d}", .{ size[0], size[1] }) }); run.setCwd(b.path(".")); run.expectExitCode(0); return .{ .run = run, .frames = frames }; } /// Prints the app's live state; `zig build probe -- --watch` follows it. pub fn addProbe(app: App, state: ?[]const u8) *Build.Step.Run { const b = app.sb.b; const run = b.addRunArtifact(app.sb.probe_exe); run.addArg(state orelse b.fmt("{s}.state", .{app.name})); run.setCwd(b.path(".")); run.stdio = .inherit; run.addPassthruArgs(); return run; } /// Tests in `root_source_file` (the app's root by default), with the /// app's imports and the app itself importable as `app`. pub fn addTest(app: App, options: struct { root_source_file: ?Build.LazyPath = null }) *Build.Step.Compile { const b = app.sb.b; const module = b.createModule(.{ .root_source_file = options.root_source_file orelse app.root_source_file, .target = app.sb.target, .optimize = app.sb.optimize, .imports = app.imports, }); if (options.root_source_file != null) module.addImport("app", app.module); return b.addTest(.{ .root_module = module }); } pub const Edit = struct { /// Relative to the app's build root, as given to `b.path`: a Zig /// source, a GLSL source, or a Zig shader source the app builds. file: []const u8, /// Must occur exactly once in `file`, or the build fails. old: []const u8, new: []const u8, }; pub const ReloadCheck = struct { run: *Build.Step.Run, /// The library as written, and as edited. library: *Build.Step.Compile, edited: *Build.Step.Compile, }; /// Checks that the app hot-reloads with its State kept: builds its /// library as written, and again from a copy of its sources with /// `edits` applied, then plays `script` headless through the generic /// host on the first, with `{v2}` defined as the second, so the script /// can `load {v2}` midway and check that State carried over (and, with /// `expect-different-screenshot`, that the edit shows). /// /// The copy covers the directory of every source an edited file is in /// (a module's root's directory holds what it imports), and every /// module and shader set (`addShaders`, `addZigShaders`) built from it /// is built again from the copy, so edits to Zig code, GLSL and Zig /// shaders all reach the second library. pub fn addReloadCheck(app: App, options: struct { script: Build.LazyPath, edits: []const Edit, }) ReloadCheck { const b = app.sb.b; var remap: Remap = .{ .sb = app.sb }; remap.collect(app.module); for (options.edits) |edit| remap.cover(edit); remap.makeCopies(options.edits); var edited_app = app; edited_app.module = remap.remapModule(app.module); const library = app.addLibrary(); const edited = edited_app.addLibrary(); const run = b.addRunArtifact(app.sb.host_exe); run.setName(b.fmt("reload check {s}", .{options.script.getDisplayName()})); run.addArgs(&.{ "--headless", "--fresh", "--script" }); run.addFileArg(options.script); run.addArg("--state"); _ = run.addOutputFileArg(b.fmt("{s}-{s}.state", .{ app.name, std.fs.path.stem(options.script.getDisplayName()) })); run.addArg("--define"); run.addPrefixedArtifactArg("v2=", edited); run.addArtifactArg(library); run.setCwd(b.path(".")); run.expectExitCode(0); run.has_side_effects = true; return .{ .run = run, .library = library, .edited = edited }; } /// The app's module graph, with the sources under some directories /// replaced by edited copies (see `addReloadCheck`). const Remap = struct { sb: Sketchbook, /// Source directories (relative to the build root) the graph uses. dirs: std.ArrayList([]const u8) = .empty, /// The directories copied, and their edited copies. roots: std.ArrayList([]const u8) = .empty, copies: std.ArrayList(Build.LazyPath) = .empty, seen: std.AutoArrayHashMapUnmanaged(*Build.Module, void) = .empty, done: std.AutoArrayHashMapUnmanaged(*Build.Module, *Build.Module) = .empty, fn arena(r: *Remap) std.mem.Allocator { return r.sb.b.graph.arena; } fn ours(r: *Remap, path: Build.LazyPath) ?[]const u8 { return switch (path) { .src_path => |p| if (p.owner == r.sb.b) p.sub_path else null, else => null, }; } fn note(r: *Remap, path: ?Build.LazyPath) void { const sub = r.ours(path orelse return) orelse return; r.dirs.append(r.arena(), std.fs.path.dirname(sub) orelse ".") catch @panic("OOM"); } fn collect(r: *Remap, m: *Build.Module) void { if ((r.seen.getOrPut(r.arena(), m) catch @panic("OOM")).found_existing) return; if (r.sb.shared.recipes.get(m)) |recipe| switch (recipe) { .glsl => |o| { for (o.sources) |src| r.note(src); if (o.layouts) |l| r.collect(l.module); }, .zig => |o| { for (o.sources) |src| r.note(src); for (o.imports) |i| r.collect(i.module); }, }; r.note(m.root_source_file); for (m.import_table.values()) |i| r.collect(i); } fn under(dir: []const u8, path: []const u8) bool { if (std.mem.eql(u8, dir, ".")) return true; return path.len > dir.len and std.mem.startsWith(u8, path, dir) and path[dir.len] == '/'; } /// Picks the outermost source directory holding `edit.file`. fn cover(r: *Remap, edit: Edit) void { var best: ?[]const u8 = null; for (r.dirs.items) |dir| if (under(dir, edit.file) and (best == null or under(dir, best.?))) { best = dir; }; const dir = best orelse std.debug.panic("addReloadCheck: {s} is in no directory of a source the app builds", .{edit.file}); for (r.roots.items) |*root| { if (under(root.*, dir) or std.mem.eql(u8, root.*, dir)) return; if (under(dir, root.*)) { root.* = dir; return; } } r.roots.append(r.arena(), dir) catch @panic("OOM"); } fn makeCopies(r: *Remap, edits: []const Edit) void { const b = r.sb.b; const tool = b.addExecutable(.{ .name = "reload-edit", .root_module = b.createModule(.{ .root_source_file = r.sb.tools.path(b, "reload_edit.zig"), .target = b.graph.host, }) }); for (r.roots.items) |root| { // Copied first: the copy's directory is named by its // contents, so the edit below reruns whenever they change. const copy = b.addWriteFiles(); const source = copy.addCopyDirectory(b.path(root), "", .{}); const run = b.addRunArtifact(tool); run.setName(b.fmt("edit a copy of {s}", .{root})); run.addDirectoryArg(source); const out = run.addOutputDirectoryArg("src"); for (edits) |edit| { if (!under(root, edit.file)) continue; run.addArgs(&.{ if (std.mem.eql(u8, root, ".")) edit.file else edit.file[root.len + 1 ..], edit.old, edit.new }); } r.copies.append(r.arena(), out) catch @panic("OOM"); } } fn remapPath(r: *Remap, original: Build.LazyPath) Build.LazyPath { const sub = r.ours(original) orelse return original; for (r.roots.items, r.copies.items) |root, copy| { if (!under(root, sub)) continue; return copy.path(r.sb.b, if (std.mem.eql(u8, root, ".")) sub else sub[root.len + 1 ..]); } return original; } fn paths(r: *Remap, originals: []const Build.LazyPath, changed: *bool) []const Build.LazyPath { const out = r.arena().alloc(Build.LazyPath, originals.len) catch @panic("OOM"); for (originals, out) |o, *p| { p.* = r.remapPath(o); changed.* = changed.* or std.meta.activeTag(p.*) != std.meta.activeTag(o); } return out; } fn remapModule(r: *Remap, m: *Build.Module) *Build.Module { if (r.done.get(m)) |copy| return copy; r.done.put(r.arena(), m, m) catch @panic("OOM"); var changed = false; const result = if (r.sb.shared.recipes.get(m)) |recipe| switch (recipe) { .glsl => |o| blk: { var e = o; e.sources = r.paths(o.sources, &changed); if (o.layouts) |l| { e.layouts = .{ .module = r.remapModule(l.module), .types = l.types }; changed = changed or e.layouts.?.module != l.module; } break :blk if (changed) r.sb.addShaders(e).module else m; }, .zig => |o| blk: { var e = o; e.sources = r.paths(o.sources, &changed); const imports = r.arena().alloc(Build.Module.Import, o.imports.len) catch @panic("OOM"); for (o.imports, imports) |i, *out| { out.* = .{ .name = i.name, .module = r.remapModule(i.module) }; changed = changed or out.module != i.module; } e.imports = imports; break :blk if (changed) r.sb.addZigShaders(e).module else m; }, } else blk: { const root = if (m.root_source_file) |file| r.remapPath(file) else null; if (m.root_source_file) |file| changed = std.meta.activeTag(root.?) != std.meta.activeTag(file); const imports = r.arena().alloc(*Build.Module, m.import_table.count()) catch @panic("OOM"); for (m.import_table.values(), imports) |i, *out| { out.* = r.remapModule(i); changed = changed or out.* != i; } if (!changed) break :blk m; const copy = r.arena().create(Build.Module) catch @panic("OOM"); copy.init(m.owner, .{ .existing = m }); copy.root_source_file = root; copy.import_table = .empty; copy.cached_graph = .{ .modules = &.{}, .names = &.{} }; for (m.import_table.keys(), imports) |name, i| copy.addImport(name, i); break :blk copy; }; r.done.put(r.arena(), m, result) catch @panic("OOM"); return result; } }; pub const StepsOptions = struct { web: ?WebOptions = null, /// Scripts run by the `e2e` step. scripts: []const Build.LazyPath = &.{}, /// Extra test roots for the `test` step, besides the app's root. tests: []const Build.LazyPath = &.{}, }; pub const Steps = struct { library: *Build.Step.Compile, exe: *Build.Step.Compile, run: *Build.Step.Run, web: ?Web, test_step: *Build.Step, e2e: *Build.Step, }; /// The conventional wiring. Installs the executable, and adds: /// `run` (host + hot reload), `lib` (rebuild the library; use `--watch`), /// `web` and `serve` (with `web` options), `probe`, `export` (frames /// for ffmpeg), `e2e` (scripts) and `test`. pub fn addSteps(app: App, options: StepsOptions) Steps { const b = app.sb.b; const library = app.addLibrary(); const exe = app.addExecutable(); b.installArtifact(exe); const run = app.addRun(library, .{}); b.step("run", "Run with hot reload (rebuild with `zig build lib --watch`)").dependOn(&run.step); b.step("lib", "Build and install the hot-reloadable library").dependOn(&b.addInstallArtifact(library, .{}).step); b.step("probe", "Print the live state (-- --watch to follow)").dependOn(&app.addProbe(null).step); const web = if (options.web) |web_options| blk: { const web = app.addWeb(web_options); const install = b.addInstallDirectory(.{ .source_dir = web.dir, .install_dir = .prefix, .install_subdir = "web" }); b.step("web", "Build the browser version into zig-out/web").dependOn(&install.step); b.step("serve", "Serve zig-out/web over https on port 8042, to the local network too (-- -p PORT for another)").dependOn(&app.addServe(install).step); break :blk web; } else null; // `--export` takes the first argument after `--`. const exporting = b.addRunArtifact(exe); exporting.addArgs(&.{ "--state", b.fmt("{s}.state", .{app.name}), "--export" }); exporting.addPassthruArgs(); exporting.setCwd(b.path(".")); exporting.stdio = .inherit; b.step("export", "Export frames: -- DIR for PNGs, or - for raw RGBA on stdout; then --fps N, --frames N, --size WxH").dependOn(&exporting.step); const e2e = b.step("e2e", "Play the end-to-end scripts headless"); const script_exe = if (app.sb.script_optimize == app.sb.optimize) exe else app.addScriptExecutable(); for (options.scripts) |script| e2e.dependOn(&app.addScript(script_exe, script, .{}).step); const test_step = b.step("test", "Run unit tests and end-to-end scripts"); test_step.dependOn(&b.addRunArtifact(app.addTest(.{})).step); for (options.tests) |root| test_step.dependOn(&b.addRunArtifact(app.addTest(.{ .root_source_file = root })).step); test_step.dependOn(e2e); return .{ .library = library, .exe = exe, .run = run, .web = web, .test_step = test_step, .e2e = e2e }; } }; /// A source's file name, for naming what is made from it: also for a file /// inside a generated directory (an edited copy, see `addReloadCheck`), /// whose display name would be "generated". fn fileName(path: Build.LazyPath) []const u8 { return switch (path) { .generated => |g| if (g.sub_path.len > 0) std.fs.path.basename(g.sub_path) else path.getDisplayName(), else => std.fs.path.basename(path.getDisplayName()), }; } /// Fills `{title}` and `{head}` in the page template. const page_tool = \\const std = @import("std"); \\pub fn main(init: std.process.Init) !void { \\ var args = init.minimal.args.iterate(); \\ _ = args.skip(); \\ const template = args.next().?; \\ const title = args.next().?; \\ const head = args.next().?; \\ const out = args.next().?; \\ const cwd = std.Io.Dir.cwd(); \\ const arena = init.arena.allocator(); \\ const source = try cwd.readFileAlloc(init.io, template, arena, .limited(1 << 20)); \\ const titled = try std.mem.replaceOwned(u8, arena, source, "{title}", title); \\ const page = try std.mem.replaceOwned(u8, arena, titled, "{head}", head); \\ try cwd.writeFile(init.io, .{ .sub_path = out, .data = page }); \\} ;