diff options
Diffstat (limited to 'build.zig')
| -rw-r--r-- | build.zig | 513 |
1 files changed, 513 insertions, 0 deletions
diff --git a/build.zig b/build.zig new file mode 100644 index 0000000..9fc9049 --- /dev/null +++ b/build.zig @@ -0,0 +1,513 @@ +//! 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 <SDL3/SDL.h> + \\#include <sndfile.h> + ), + .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 <pthread.h> + \\#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, + /// `<Name>.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 <name>: []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 against `exe` (from `addExecutable`), with a + /// throwaway state file. Fails when an expectation does. + pub fn addScript(app: App, exe: *Build.Step.Compile, script: Build.LazyPath, options: ScriptOptions) *Build.Step.Run { + const b = app.sb.b; + const run = b.addRunArtifact(exe); + 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] }) }); + 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 }); + \\} +; |
