path: root/build.zig

const std = @import("std");

const AppKind = enum { main, replay };
const GhosttyArtifact = enum { ghostty, lib };
const TreeSitterGrammars = enum { disabled, minimal, full };

pub fn build(b: *std.Build) void {
    const requested_optimize = b.standardOptimizeOption(.{});
    const target = b.standardTargetOptions(.{});
    const is_emscripten = target.result.os.tag == .emscripten;
    const optimize = if (is_emscripten) .ReleaseSmall else requested_optimize;
    const emscripten_sysroot = if (is_emscripten) detectEmscriptenSysroot(b) else null;

    // build-time IO, only used to slurp the grammars' highlights.scm queries.
    var threaded: std.Io.Threaded = .init(b.allocator, .{});
    defer threaded.deinit();
    const io = threaded.io();

    // -Dtrace: make the e2e runner print the captured screen state (after each
    //   pump/waitFor and on every assertion) so failures can be inspected live.
    //   Usage: `zig build test -Dtrace`.
    const trace = b.option(bool, "trace", "print captured tty/screen state during e2e tests") orelse false;
    const static_link = b.option(bool, "static", "link all build executables and test binaries statically") orelse false;
    const exe_linkage: ?std.builtin.LinkMode = if (static_link) .static else null;
    const strip = b.option(bool, "strip", "strip debug info from the compiled pardes binary") orelse false;
    // -Dsdl: build the SDL3 GPU UI frontend (a windowed cell-grid renderer)
    //   instead of the default libvaxis terminal backend. The sdl/stb deps are
    //   lazy, so a plain `zig build` never fetches or compiles them; they're only
    //   pulled in when this flag is set. Use `zig build test-sdl -Dsdl` for the
    //   rendered-image SDL e2e suite.
    const sdl = b.option(bool, "sdl", "build the SDL3 GPU UI frontend instead of the terminal backend") orelse false;
    const sdl_backend = sdl or is_emscripten;
    const replay_dump = b.option([]const u8, "replay-dump", "embed this replay dump .zon into pardes-replay");
    const default_tree_sitter_grammars: TreeSitterGrammars = if (is_emscripten) .minimal else .full;
    const tree_sitter_grammars = b.option(TreeSitterGrammars, "tree-sitter", "tree-sitter grammar set: disabled, minimal, full") orelse default_tree_sitter_grammars;
    const syntax_highlighting = tree_sitter_grammars != .disabled;
    const syntax_minimal_grammars = tree_sitter_grammars == .minimal or tree_sitter_grammars == .full;
    const syntax_full_grammars = tree_sitter_grammars == .full;
    const emscripten_include: ?std.Build.LazyPath = if (emscripten_sysroot) |sysroot|
        .{ .cwd_relative = b.pathJoin(&.{ sysroot, "include" }) }
    else
        null;
    const emscripten_libc_file: ?std.Build.LazyPath = if (emscripten_sysroot) |sysroot| blk: {
        const files = b.addWriteFiles();
        break :blk files.add("emscripten-libc.txt", b.fmt(
            \\include_dir={s}/include
            \\sys_include_dir={s}/include
            \\crt_dir={s}/lib/wasm32-emscripten
            \\msvc_lib_dir=
            \\kernel32_lib_dir=
            \\gcc_dir=
            \\
        , .{ sysroot, sysroot, sysroot }));
    } else null;

    const exe = b.addExecutable(.{
        .name = "pardes",
        .linkage = exe_linkage,
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("main.zig"),
            .strip = strip,
        }),
    });
    const replay = b.addExecutable(.{
        .name = "pardes-replay",
        .linkage = exe_linkage,
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("replay.zig"),
            .strip = strip,
        }),
    });
    if (emscripten_libc_file) |libc_file| {
        exe.setLibCFile(libc_file);
        replay.setLibCFile(libc_file);
    }
    const tests = b.addExecutable(.{
        .name = "pardes-e2e",
        .linkage = exe_linkage,
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("tests.zig"),
            .link_libc = true,
        }),
    });

    const main_app_config = b.addOptions();
    main_app_config.addOption(AppKind, "app_kind", .main);
    main_app_config.addOption(bool, "syntax_highlighting", syntax_highlighting);
    main_app_config.addOption(bool, "syntax_minimal_grammars", syntax_minimal_grammars);
    main_app_config.addOption(bool, "syntax_full_grammars", syntax_full_grammars);
    exe.root_module.addOptions("app_config", main_app_config);

    const replay_app_config = b.addOptions();
    replay_app_config.addOption(AppKind, "app_kind", .replay);
    replay_app_config.addOption(bool, "syntax_highlighting", syntax_highlighting);
    replay_app_config.addOption(bool, "syntax_minimal_grammars", syntax_minimal_grammars);
    replay_app_config.addOption(bool, "syntax_full_grammars", syntax_full_grammars);
    replay.root_module.addOptions("app_config", replay_app_config);
    const replay_config = b.addOptions();
    replay_config.addOption(bool, "embedded_dump", replay_dump != null);
    replay.root_module.addOptions("replay_config", replay_config);
    if (replay_dump) |path| {
        replay.root_module.addAnonymousImport("replay.dump.zon", .{
            .root_source_file = if (std.fs.path.isAbsolute(path)) .{ .cwd_relative = path } else b.path(path),
        });
    }

    // ghostty-vt and vaxis both depend on uucode, but Zig 0.16 forbids the
    // same source file from belonging to two modules, so they can't each have
    // their own uucode instance. We build a single uucode module here (with our
    // own uucode_config.zig) and hand it to both.
    //
    // Our config matches ghostty's exactly except the tables are `.unpacked`;
    // see uucode_config.zig for why that's required on Zig 0.16.
    const uucode_config = b.path("uucode_config.zig");
    const uucode_tables = b.dependency("uucode", .{
        .target = target,
        .optimize = optimize,
        .build_config_path = uucode_config,
    }).namedLazyPath("tables.zig");
    const uucode_mod = b.dependency("uucode", .{
        .target = target,
        .optimize = optimize,
        .build_config_path = uucode_config,
        .tables_path = uucode_tables,
    }).module("uucode");

    // vaxis is built with `external_uucode = true` so it skips its built-in
    // uucode dependency and lets us wire one in.
    const vaxis_dep = b.dependency("vaxis", .{
        .target = target,
        .optimize = optimize,
        .external_uucode = true,
    });
    const vaxis_mod = vaxis_dep.module("vaxis");

    // You'll want to use a lazy dependency here so that ghostty is only
    // downloaded if you actually need it.
    if (b.lazyDependency("ghostty", .{
        // Setting simd to false will force a pure static build that
        // doesn't even require libc, but it has a significant performance
        // penalty. If your embedding app requires libc anyway, you should
        // always keep simd enabled.
        .simd = !is_emscripten,
    })) |dep| {
        // Accessing ghostty's modules runs its build(), which (because vaxis is
        // a shared dependency, deduplicated to the same module) wires ghostty's
        // own uucode into vaxis. We undo that below by overriding both imports
        // with ours — order matters, so this must happen after this point.
        const ghostty_vt = dep.module("ghostty-vt");
        ghostty_vt.addImport("uucode", uucode_mod);
        if (is_emscripten) {
            const term_opts = b.addOptions();
            term_opts.addOption(GhosttyArtifact, "artifact", .lib);
            term_opts.addOption(bool, "c_abi", false);
            term_opts.addOption(bool, "oniguruma", false);
            term_opts.addOption(bool, "simd", false);
            term_opts.addOption(bool, "slow_runtime_safety", false);
            term_opts.addOption(bool, "kitty_graphics", false);
            term_opts.addOption(bool, "tmux_control_mode", false);
            term_opts.addOption([]const u8, "version_string", "0.0.0");
            term_opts.addOption(usize, "version_major", 0);
            term_opts.addOption(usize, "version_minor", 0);
            term_opts.addOption(usize, "version_patch", 0);
            term_opts.addOption(?[]const u8, "version_pre", null);
            term_opts.addOption(?[]const u8, "version_build", null);
            ghostty_vt.addOptions("terminal_options", term_opts);
        }
        exe.root_module.addImport("ghostty-vt", ghostty_vt);
        replay.root_module.addImport("ghostty-vt", ghostty_vt);
        // The e2e test harness parses the app's pty output with its own ghostty
        // terminal (reads the 2D screen grid, not raw bytes), so it needs the
        // same module.
        tests.root_module.addImport("ghostty-vt", ghostty_vt);
    }

    // Override uucode on vaxis last, so it wins over ghostty's build() above.
    vaxis_mod.addImport("uucode", uucode_mod);
    exe.root_module.addImport("vaxis", vaxis_mod);

    // The UI backend module (`-Dui`). main.zig + image.zig import `"ui"` instead of
    // `"vaxis"` directly; the chosen backend file re-exports the shared UI types
    // (Key/Mouse/Window/Cell/…) and provides the renderer/loop (`Vaxis`/`Tty`/
    // `Loop`/`init`). vaxis = transparent passthrough; sdl = SDL3 GPU frontend.
    const ui_root = if (sdl_backend) b.path("ui_sdl.zig") else b.path("ui_vaxis.zig");
    const ui_mod = b.createModule(.{
        .target = target,
        .optimize = optimize,
        .root_source_file = ui_root,
    });
    ui_mod.addImport("vaxis", vaxis_mod);
    exe.root_module.addImport("ui", ui_mod);
    replay.root_module.addImport("ui", ui_mod);

    // SDL3 backend wiring (`-Dsdl`, or Emscripten replay builds). The sdl package builds SDL3 from source
    // as a static lib + emits the SDL3/ headers; we @cImport those headers in
    // ui_sdl.zig, link the lib, and pull in stb_truetype (for the glyph atlas) and
    // the embedded Maple Mono NF font. All gated on the flag so a plain `zig build`
    // (vaxis) never fetches or compiles SDL.
    var sdl_lib_for_wasm: ?*std.Build.Step.Compile = null;
    if (sdl_backend) {
        const sdl_dep = if (is_emscripten and emscripten_include != null)
            b.lazyDependency("sdl", .{
                .target = target,
                .optimize = optimize,
                .system_include_path = emscripten_include.?,
            }) orelse return
        else
            b.lazyDependency("sdl", .{
                .target = target,
                .optimize = optimize,
            }) orelse return; // not fetched (offline?) — skip SDL wiring
        const sdl_lib = sdl_dep.artifact("SDL3");
        if (emscripten_libc_file) |libc_file| sdl_lib.setLibCFile(libc_file);
        if (is_emscripten) sdl_lib_for_wasm = sdl_lib;
        ui_mod.linkLibrary(sdl_lib);
        ui_mod.addIncludePath(sdl_dep.path("include"));
        if (emscripten_include) |include| ui_mod.addSystemIncludePath(include);
        ui_mod.link_libc = true;

        // stb_truetype: the header (declarations, via include path) + the impl TU
        // + a small C shim (font.c) so ui_sdl.zig doesn't feed the whole
        // single-header lib to translate-c.
        ui_mod.addIncludePath(b.path("vendor/stb"));
        ui_mod.addCSourceFile(.{ .file = b.path("vendor/stb/stb_truetype_impl.c") });
        ui_mod.addCSourceFile(.{ .file = b.path("vendor/stb/font.c") });

        if (is_emscripten) {
            ui_mod.addAnonymousImport("ui.vert.es.glsl", .{ .root_source_file = b.path("shaders/ui.vert.es.glsl") });
            ui_mod.addAnonymousImport("ui.frag.es.glsl", .{ .root_source_file = b.path("shaders/ui.frag.es.glsl") });
        } else {
            // GLSL -> SPIR-V at build time, embedded into ui_sdl.zig via @embedFile.
            ui_mod.addAnonymousImport("ui.vert.spv", .{
                .root_source_file = compileGlsl(b, "shaders/ui.vert.glsl", "vertex", "ui.vert.spv"),
            });
            ui_mod.addAnonymousImport("ui.frag.spv", .{
                .root_source_file = compileGlsl(b, "shaders/ui.frag.glsl", "fragment", "ui.frag.spv"),
            });
        }
    }

    // zstbi: C (stb_image)-backed image decoder for the image-viewer panes. We use
    // it instead of zigimg because zigimg's pure-Zig decoder crashes the Zig 0.16
    // compiler here; stb_image is plain C (extern fns), so it compiles fine, decodes
    // every common format, and offers downscaling. Its module ("root") carries the
    // C source + include path + libc, so importing it is all that's needed.
    const zstbi_dep = b.dependency("zstbi", .{ .target = target, .optimize = optimize });
    const zstbi_mod = zstbi_dep.module("root");
    exe.root_module.addImport("zstbi", zstbi_mod);
    replay.root_module.addImport("zstbi", zstbi_mod);

    const replay_wasm_ready = is_emscripten and replay_dump != null and emscripten_sysroot != null;
    const emcc_for_wasm = if (replay_wasm_ready) blk: {
        const replay_obj = b.addObject(.{
            .name = "pardes-replay",
            .root_module = replay.root_module,
        });
        if (emscripten_libc_file) |libc_file| replay_obj.setLibCFile(libc_file);

        const emcc_path = b.option([]const u8, "emcc", "path to emcc for replay-wasm final link") orelse "/usr/lib/emscripten/emcc";
        const emcc = b.addSystemCommand(&.{emcc_path});
        emcc.addFileArg(replay_obj.getEmittedBinDirectory().path(b, "pardes-replay_zcu.o"));
        emcc.addFileArg(replay_obj.getEmittedBin());
        emcc.addFileArg(b.path("vendor/stb/stb_truetype_impl.c"));
        emcc.addFileArg(b.path("vendor/stb/font.c"));
        emcc.addFileArg(zstbi_dep.path("src/zstbi.c"));
        if (sdl_lib_for_wasm) |sdl_lib| emcc.addFileArg(sdl_lib.getEmittedBin());
        break :blk emcc;
    } else null;

    if (syntax_highlighting) {
        // tree-sitter syntax highlighting for file panes: the Zig bindings + C runtime
        // (the `tree-sitter` module), each grammar's parser.c linked as a static lib,
        // and its highlights.scm read at build time into the `ts_queries` options module.
        const tree_sitter = b.dependency("tree_sitter", .{ .target = target, .optimize = optimize });
        const tree_sitter_mod = tree_sitter.module("tree_sitter");
        if (is_emscripten) {
            for (tree_sitter_mod.link_objects.items) |link_object| switch (link_object) {
                .other_step => |lib| {
                    if (emscripten_libc_file) |libc_file| lib.setLibCFile(libc_file);
                    if (emcc_for_wasm) |emcc| emcc.addFileArg(lib.getEmittedBin());
                },
                else => {},
            };
        }
        exe.root_module.addImport("tree-sitter", tree_sitter_mod);
        replay.root_module.addImport("tree-sitter", tree_sitter_mod);

        const Grammar = struct {
            name: []const u8,
            dep: []const u8,
            src: []const u8 = "src",
            scanner: bool = false,
            query: []const u8 = "queries/highlights.scm",
            local_query: ?[]const u8 = null,
            minimal: bool = false,
        };
        const grammars = [_]Grammar{
            .{ .name = "ada", .dep = "ts_ada" },
            .{ .name = "bash", .dep = "ts_bash", .scanner = true },
            .{ .name = "c", .dep = "ts_c", .minimal = true },
            .{ .name = "c_sharp", .dep = "ts_c_sharp", .scanner = true },
            .{ .name = "clojure", .dep = "ts_clojure" },
            .{ .name = "cpp", .dep = "ts_cpp", .scanner = true, .minimal = true },
            .{ .name = "css", .dep = "ts_css", .scanner = true },
            .{ .name = "elixir", .dep = "ts_elixir", .scanner = true },
            .{ .name = "erlang", .dep = "ts_erlang", .scanner = true },
            .{ .name = "fortran", .dep = "ts_fortran", .scanner = true },
            .{ .name = "go", .dep = "ts_go" },
            .{ .name = "haskell", .dep = "ts_haskell", .scanner = true },
            .{ .name = "html", .dep = "ts_html", .scanner = true },
            .{ .name = "java", .dep = "ts_java" },
            .{ .name = "javascript", .dep = "ts_javascript", .scanner = true },
            .{ .name = "json", .dep = "ts_json" },
            .{ .name = "kotlin", .dep = "ts_kotlin", .scanner = true },
            .{ .name = "ocaml", .dep = "ts_ocaml", .src = "grammars/ocaml/src", .scanner = true },
            .{ .name = "pascal", .dep = "ts_pascal" },
            .{ .name = "php", .dep = "ts_php", .src = "php/src", .scanner = true },
            .{ .name = "powershell", .dep = "ts_powershell", .scanner = true },
            .{ .name = "python", .dep = "ts_python", .scanner = true },
            .{ .name = "ruby", .dep = "ts_ruby", .scanner = true },
            .{ .name = "rust", .dep = "ts_rust", .scanner = true },
            .{ .name = "scala", .dep = "ts_scala", .scanner = true },
            .{ .name = "zig", .dep = "ts_zig", .minimal = true },
        };
        const ts_queries = b.addOptions();
        inline for (grammars) |g| {
            if (tree_sitter_grammars == .full or g.minimal) {
                const dep = b.dependency(g.dep, .{});
                const query_path = if (g.local_query) |p| b.path(p) else dep.path(g.query);
                const query = std.Io.Dir.cwd().readFileAlloc(io, query_path.getPath(b), b.allocator, .limited(0x100000)) catch @panic("read " ++ g.name ++ " highlights");
                ts_queries.addOption([]const u8, g.name ++ "_highlights", query);

                const lib = b.addLibrary(.{
                    .name = "tree-sitter-" ++ g.name,
                    .root_module = b.createModule(.{ .target = target, .optimize = optimize, .link_libc = true }),
                    .linkage = .static,
                });
                if (emscripten_libc_file) |libc_file| lib.setLibCFile(libc_file);
                lib.root_module.addCSourceFile(.{ .file = dep.path(g.src ++ "/parser.c") });
                if (g.scanner) lib.root_module.addCSourceFile(.{ .file = dep.path(g.src ++ "/scanner.c") });
                lib.root_module.addIncludePath(dep.path(g.src));
                exe.root_module.linkLibrary(lib);
                replay.root_module.linkLibrary(lib);
                if (emcc_for_wasm) |emcc| emcc.addFileArg(lib.getEmittedBin());
            }
        }
        exe.root_module.addOptions("ts_queries", ts_queries);
        replay.root_module.addOptions("ts_queries", ts_queries);
    }

    // Install the exe so `zig build` (and `zig build install`) produces it in
    // zig-out/bin for global install, not just as a hidden dep of `run`/`test`.
    b.installArtifact(exe);
    b.installArtifact(replay);

    const run_exe = b.addRunArtifact(exe);

    const run = b.step("run", "descend to the pardes");
    run.dependOn(&run_exe.step);

    const run_replay = b.addRunArtifact(replay);
    if (b.args) |args| run_replay.addArgs(args);
    const replay_step = b.step("replay", "replay a pardes dump: zig build replay -- <dump.zon>");
    replay_step.dependOn(&run_replay.step);

    const replay_wasm_step = b.step("replay-wasm", "build browser SDL replay (requires -Dtarget=wasm32-emscripten -Dreplay-dump=<dump.zon>)");
    if (!is_emscripten) {
        replay_wasm_step.dependOn(&b.addFail("replay-wasm requires -Dtarget=wasm32-emscripten").step);
    } else if (replay_dump == null) {
        replay_wasm_step.dependOn(&b.addFail("replay-wasm requires -Dreplay-dump=<dump.zon>").step);
    } else if (emscripten_sysroot == null) {
        replay_wasm_step.dependOn(&b.addFail("replay-wasm requires an Emscripten sysroot; pass --sysroot <emscripten>/cache/sysroot or set EM_CACHE/EMSDK").step);
    } else {
        const emcc = emcc_for_wasm.?;
        emcc.addPrefixedDirectoryArg("-I", b.path("vendor/stb"));
        emcc.addPrefixedDirectoryArg("-I", zstbi_dep.path("libs/stbi"));
        emcc.addArgs(&.{
            "-std=c99",
            "-fno-sanitize=undefined",
            "-Oz",
            "-sINITIAL_MEMORY=2147483648",
            "-sEXIT_RUNTIME=0",
            "-sFULL_ES3=1",
            "-sMIN_WEBGL_VERSION=2",
            "-sMAX_WEBGL_VERSION=2",
            "-sINCOMING_MODULE_JS_API=canvas",
            "-o",
        });
        const replay_js = emcc.addOutputFileArg("pardes-replay.js");
        replay_wasm_step.dependOn(&b.addInstallFileWithDir(replay_js, .{ .custom = "web" }, "pardes-replay.js").step);
        replay_wasm_step.dependOn(&b.addInstallFileWithDir(replay_js.dirname().path(b, "pardes-replay.wasm"), .{ .custom = "web" }, "pardes-replay.wasm").step);

        const web = b.addWriteFiles();
        const html = web.add("replay.html",
            \\<!doctype html>
            \\<html>
            \\<head>
            \\  <meta charset="utf-8">
            \\  <meta name="viewport" content="width=device-width, initial-scale=1">
            \\  <title>pardes replay</title>
            \\  <style>
            \\    html, body { margin: 0; min-width: 100%; min-height: 100%; background: #121212; }
            \\    body { overflow: auto; }
            \\    canvas { display: block; }
            \\  </style>
            \\</head>
            \\<body>
            \\  <canvas id="canvas" oncontextmenu="event.preventDefault()" tabindex="-1"></canvas>
            \\  <script>
            \\    window.Module = { canvas: document.getElementById('canvas') };
            \\  </script>
            \\  <script src="pardes-replay.js"></script>
            \\</body>
            \\</html>
        );
        replay_wasm_step.dependOn(&b.addInstallFileWithDir(html, .{ .custom = "web" }, "replay.html").step);
    }

    const test_browser_step = b.step("test-browser", "run browser SDL replay screenshot e2e (requires -Dtarget=wasm32-emscripten -Dreplay-dump=<dump.zon>)");
    if (!is_emscripten) {
        test_browser_step.dependOn(&b.addFail("test-browser requires -Dtarget=wasm32-emscripten").step);
    } else if (replay_dump == null) {
        test_browser_step.dependOn(&b.addFail("test-browser requires -Dreplay-dump=<dump.zon>").step);
    } else {
        const run_browser_e2e = b.addSystemCommand(&.{ "node", "tests/browser_replay_e2e.mjs" });
        run_browser_e2e.addArg("zig-out/web");
        run_browser_e2e.addArg("zig-out/browser-replay.png");
        run_browser_e2e.step.dependOn(replay_wasm_step);
        test_browser_step.dependOn(&run_browser_e2e.step);
    }

    // tutor_gen: a separate binary that parses tutor.txt and writes
    // tutor_cases.zig (a file of `test` blocks, one per practice block).
    // `zig build tutor-gen` runs it; the unit-test step depends on the output.
    const tutor_gen = b.addExecutable(.{
        .name = "tutor-gen",
        .linkage = exe_linkage,
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("tutor_gen.zig"),
        }),
    });
    const run_tutor_gen = b.addRunArtifact(tutor_gen);
    run_tutor_gen.addArg("tutor.txt");
    const tutor_cases_lazy = run_tutor_gen.addOutputFileArg("tutor_cases.zig");
    const tutor_gen_step = b.step("tutor-gen", "regenerate tutor_cases.zig from tutor.txt");
    tutor_gen_step.dependOn(&run_tutor_gen.step);

    const run_tests = b.addRunArtifact(tests);
    run_tests.addArtifactArg(exe);
    run_tests.addArtifactArg(replay);

    // Expose build-time flags (e.g. -Dtrace) to the test runner as an importable
    // `config` module. tests.zig reads `config.trace` and hands it to the harness.
    const test_opts = b.addOptions();
    test_opts.addOption(bool, "trace", trace);
    tests.root_module.addOptions("config", test_opts);

    const test_step = b.step("test", "run deterministic tests");
    test_step.dependOn(&run_tests.step);

    // `test-sdl`: e2e tests for the SDL3 GPU backend. The SDL pardes exe runs in
    // test mode (PARDES_TEST=1): stdin drives app events through a pty, while the
    // real GPU renderer writes the latest framebuffer capture to a temp PPM file.
    // Requires `-Dsdl` so the SDL exe is the one under test.
    const sdl_tests = b.addExecutable(.{
        .name = "pardes-e2e-sdl",
        .linkage = exe_linkage,
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("tests_sdl.zig"),
            .link_libc = true,
        }),
    });
    const run_sdl_tests = b.addRunArtifact(sdl_tests);
    run_sdl_tests.addArtifactArg(exe);
    const sdl_test_opts = b.addOptions();
    sdl_test_opts.addOption(bool, "trace", trace);
    sdl_tests.root_module.addOptions("config", sdl_test_opts);
    const test_sdl_step = b.step("test-sdl", "run SDL3 GPU e2e tests (requires -Dsdl)");
    test_sdl_step.dependOn(&run_sdl_tests.step);

    // Unit tests for the pure modal-editing math (modal.zig has no vaxis/ghostty
    // deps, so `zig test` on it is fast and needs no wired-in modules).
    const unit_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("modal.zig"),
        }),
    });
    unit_tests.linkage = exe_linkage;
    const run_unit = b.addRunArtifact(unit_tests);
    const unit_step = b.step("unit-test", "run modal.zig unit tests");
    unit_step.dependOn(&run_unit.step);
    test_step.dependOn(&run_unit.step);

    // petscii.zig is likewise pure (std only) — fold its matcher tests into both
    // the unit-test and the umbrella test step.
    const petscii_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("petscii.zig"),
        }),
    });
    petscii_tests.linkage = exe_linkage;
    const run_petscii = b.addRunArtifact(petscii_tests);
    unit_step.dependOn(&run_petscii.step);
    test_step.dependOn(&run_petscii.step);

    const dump_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = b.path("dump.zig"),
        }),
    });
    dump_tests.linkage = exe_linkage;
    const run_dump = b.addRunArtifact(dump_tests);
    unit_step.dependOn(&run_dump.step);
    test_step.dependOn(&run_dump.step);

    // Tutor practice blocks as unit tests: a second `zig test` target over the
    // generated tutor_cases.zig (which imports modal.zig). Depends on tutor-gen
    // so the file is (re)generated first.
    const tutor_tests = b.addTest(.{
        .root_module = b.createModule(.{
            .target = target,
            .optimize = optimize,
            .root_source_file = tutor_cases_lazy,
        }),
    });
    tutor_tests.linkage = exe_linkage;
    // The generated cases `@import("modal")` (a module name, not a relative
    // path, since the generated file lives in the cache dir, not next to modal.zig).
    const modal_for_tutor = b.createModule(.{
        .target = target,
        .optimize = optimize,
        .root_source_file = b.path("modal.zig"),
    });
    tutor_tests.root_module.addImport("modal", modal_for_tutor);
    const run_tutor = b.addRunArtifact(tutor_tests);
    const tutor_step = b.step("tutor-test", "run the tutor practice-block tests");
    tutor_step.dependOn(&run_tutor.step);
    test_step.dependOn(&run_tutor.step);
}

// glslc <src> -fshader-stage=<stage> -o <out> -> .spv, returned as a LazyPath to
// @embedFile. Only used by the SDL3 GPU UI backend (`-Dui=sdl`).
fn compileGlsl(b: *std.Build, src: []const u8, stage: []const u8, out: []const u8) std.Build.LazyPath {
    const cmd = b.addSystemCommand(&.{ "glslc", b.fmt("-fshader-stage={s}", .{stage}) });
    cmd.addFileArg(b.path(src));
    cmd.addArg("-o");
    return cmd.addOutputFileArg(out);
}

fn detectEmscriptenSysroot(b: *std.Build) ?[]const u8 {
    if (b.option([]const u8, "emscripten-sysroot", "path to the Emscripten sysroot")) |path| return path;
    if (b.sysroot) |path| return path;
    if (envPath(b, "EMSCRIPTEN_SYSROOT")) |path| return path;
    if (envPath(b, "EM_CACHE")) |cache| {
        return b.pathJoin(&.{ cache, "sysroot" });
    }
    if (envPath(b, "EMSDK")) |emsdk| {
        return b.pathJoin(&.{ emsdk, "upstream", "emscripten", "cache", "sysroot" });
    }
    if (envPath(b, "HOME")) |home| {
        return b.pathJoin(&.{ home, ".cache", "emscripten", "sysroot" });
    }
    return null;
}

fn envPath(b: *std.Build, name: []const u8) ?[]const u8 {
    return b.graph.environ_map.get(name);
}