//! 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, web, probe, e2e, test, install //! //! or pick the pieces: `app.addLibrary()`, `app.addExecutable()`, //! `app.addWeb(...)`, `app.addRun(...)`, `app.addScript(...)`, //! `app.addProbe(...)`, `app.addTest(...)`. For GPU shaders: //! `sb.addGlslLayouts(...)`, `sb.addGlslc(...)`, `sb.addSpirvModule(...)`. //! Each returns the ordinary `std.Build` objects, so anything can be //! extended or rewired. 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") }); const sketch = b.addModule("sketch", .{ .root_source_file = b.path("src/sketch/root.zig"), .imports = &.{.{ .name = "abi", .module = abi }}, }); const c = cModule(b, target, optimize); const host = b.addModule("host", .{ .root_source_file = b.path("src/host/root.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "c", .module = c } }, }); 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, .vector = undefined }, .host_exe = host_exe, .probe_exe = probe, .web = b.path("web"), .glsl = b.path("src/glsl.zig") }; // Vector graphics: built with the same shader step apps use. const vector_layouts = b.createModule(.{ .root_source_file = b.path("src/vector/layouts.zig") }); const glsl = sb.addGlslLayouts(.{ .module = vector_layouts, .types = &.{ "Vertex", "Viewport", "Paint" } }); const vector_shaders = sb.addSpirvModule(&.{ .{ .name = "path_vert", .spirv = sb.addGlslc(.{ .source = b.path("src/vector/shaders/path.vert"), .include_dirs = &.{glsl.dir} }).spirv }, .{ .name = "stencil_frag", .spirv = sb.addGlslc(.{ .source = b.path("src/vector/shaders/stencil.frag") }).spirv }, .{ .name = "cover_frag", .spirv = sb.addGlslc(.{ .source = b.path("src/vector/shaders/cover.frag"), .include_dirs = &.{glsl.dir} }).spirv }, }); const vector_imports: []const Build.Module.Import = &.{ .{ .name = "abi", .module = abi }, .{ .name = "vector_layouts", .module = vector_layouts }, .{ .name = "vector_shaders", .module = vector_shaders }, }; sb.modules.vector = b.addModule("vector", .{ .root_source_file = b.path("src/vector/root.zig"), .imports = vector_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/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 = &.{.{ .name = "abi", .module = abi }} }), b.createModule(.{ .root_source_file = b.path("src/host/root.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "c", .module = c } } }), }) |module| test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = module })).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(); // 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); 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); } 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")); 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 ), .target = target, .optimize = optimize, }); translator.linkLibrary(sdl); translator.linkSystemLibrary("sndfile", .{}); 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.? }); } // --------------------------------------------------------------------------- // 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", }; pub fn init(b: *Build, options: Options) Sketchbook { const dep = b.dependency(options.dependency, .{ .target = options.target, .optimize = options.optimize }); return .{ .b = b, .target = options.target, .optimize = options.optimize, .modules = .{ .abi = dep.module("abi"), .sketch = dep.module("sketch"), .host = dep.module("host"), .vector = dep.module("vector") }, .host_exe = dep.artifact("sketchbook"), .probe_exe = dep.artifact("sketchbook-probe"), .web = dep.path("web"), .glsl = dep.path("src/glsl.zig"), }; } pub const Sketchbook = struct { b: *Build, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, /// `vector`: SVG, cubic geometry, and CPU and GPU renderers. modules: struct { abi: *Build.Module, sketch: *Build.Module, host: *Build.Module, vector: *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, 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` (from the Vulkan SDK or /// shaderc, on PATH). pub fn addGlslc(sb: Sketchbook, options: struct { source: Build.LazyPath, include_dirs: []const Build.LazyPath = &.{}, target_env: []const u8 = "vulkan1.1", optimize: bool = true, }) Glslc { const b = sb.b; const run = b.addSystemCommand(&.{ "glslc", b.fmt("--target-env={s}", .{options.target_env}) }); if (options.optimize) run.addArg("-O"); for (options.include_dirs) |dir| run.addPrefixedDirectoryArg("-I", dir); run.addArg("-o"); const spirv = run.addOutputFileArg(b.fmt("{s}.spv", .{std.fs.path.basename(options.source.getDisplayName())})); run.addFileArg(options.source); return .{ .run = run, .spirv = spirv }; } /// A module declaring each SPIR-V file as `pub const : []const u8`, /// 4-byte aligned as Vulkan reads it. pub fn addSpirvModule(sb: Sketchbook, shaders: []const struct { name: []const u8, spirv: Build.LazyPath }) *Build.Module { const b = sb.b; const files = b.addWriteFiles(); var source: std.ArrayList(u8) = .empty; for (shaders) |shader| { const file = b.fmt("{s}.spv", .{shader.name}); _ = files.addCopyFile(shader.spirv, file); source.print(b.allocator, "const {s}_words align(4) = @embedFile(\"{s}\").*;\npub const {s}: []const u8 = &{s}_words;\n", .{ shader.name, file, shader.name, shader.name }) catch @panic("OOM"); } return b.createModule(.{ .root_source_file = files.add("spirv.zig", source.items) }); } 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.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, app.sb.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. index_html: ?Build.LazyPath = null, optimize: std.builtin.OptimizeMode = .ReleaseSafe, pub const Asset = struct { source: Build.LazyPath, dest: []const u8 }; }; 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; const wasm = b.addExecutable(.{ .name = "sketch", .root_module = 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); _ = files.addCopyFile(page.addOutputFileArg("index.html"), "index.html"); for (options.assets) |asset| _ = files.addCopyDirectory(asset.source, asset.dest, .{}); return .{ .wasm = wasm, .dir = files.getDirectory() }; } 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.addArg(b.getInstallPath(.lib, library.out_filename)); run.setCwd(options.cwd orelse b.path(".")); run.stdio = .inherit; if (b.args) |args| run.addArgs(args); 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"); _ = run.addOutputFileArg(b.fmt("{s}.state", .{app.name})); 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; } /// 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; if (b.args) |args| run.addArgs(args); 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 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`, `probe`, `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); b.step("web", "Build the browser version into zig-out/web").dependOn(&b.addInstallDirectory(.{ .source_dir = web.dir, .install_dir = .prefix, .install_subdir = "web" }).step); break :blk web; } else null; const e2e = b.step("e2e", "Play the end-to-end scripts headless"); for (options.scripts) |script| e2e.dependOn(&app.addScript(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 }; } }; /// Fills `{title}` 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 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 page = try std.mem.replaceOwned(u8, arena, source, "{title}", title); \\ try cwd.writeFile(init.io, .{ .sub_path = out, .data = page }); \\} ;