build.zig

const zon = @import("build.zig.zon");
const std = @import("std");
const Io = std.Io;

pub const BuildAsset = struct {
    /// Name of this asset
    name: []const u8,
    /// LazyPath of the generated asset.
    ///
    /// The LazyPath cannot be generated by calling `b.path`.
    /// Use the 'assets' directory for non-buildtime assets.
    lp: std.Build.LazyPath,
    /// Installation path relative to the website's asset output path prefix.
    ///
    /// It is recommended to give the file an appropriate file extension.
    /// No need to specify this value if the asset is not meant to be
    /// `link()`ed
    install_path: ?[]const u8 = null,
    /// Installs the asset unconditionally when set to true.
    ///
    /// When set to false, the asset will be installed only if `link()`ed
    /// in a content file or layout (requires `install_path` to be set).
    ///
    /// Note that even when this property is set to false the asset will be
    /// generated by the Zig build system regardless.
    install_always: bool = false,
};

pub const Options = struct {
    /// The directory that contains 'zine.ziggy'.
    /// Defaults to the directory where your 'build.zig' lives.
    website_root: ?std.Build.LazyPath = null,

    /// Assets generated by the Zig build system to be made available to Zine.
    build_assets: []const BuildAsset = &.{},

    /// Path where to output the website, relative to the zig build install
    /// prefix.
    output_path: []const u8 = "",

    /// Ignore the presence of other files in the output directory.
    /// When set to `false`, Zine will refuse to output a release to a directory
    /// that contains other files. Note that when set to `true` old files will
    /// **NOT** be deleted by Zine.
    force: bool = false,

    /// Whether Zine should be built from source or grabbed from the
    /// environment. In ephemeral environments like CI runners you might
    /// want to build from source only if you are also saving Zig's cache dirs.
    zine: union(enum) {
        /// Build Zine from source (the default).
        source,
        /// Get Zine from the environment. You can either specify a path
        /// to the executable or leave it null if you have 'zine' available
        /// in PATH.
        path: ?[]const u8,
    } = .source,

    /// Debug settings for Zine.
    debug: struct {
        /// The optimization level to use when building Zine.
        optimize: std.builtin.OptimizeMode = .fast,

        /// Logging scopes to enable.
        scopes: []const []const u8 = &.{},
    } = .{},
};

/// Builds a Zine website.
pub fn website(project: *std.Build, opts: Options) *std.Build.Step.Run {
    const zine_dep = project.dependencyFromBuildZig(@This(), .{
        .optimize = opts.debug.optimize,
        .scope = opts.debug.scopes,
        .@"no-git-version" = true,
    });

    const run_zine = switch (opts.zine) {
        .source => project.addRunArtifact(zine_dep.artifact("zine")),
        .path => |path| project.addSystemCommand(&.{path orelse "zine"}),
    };
    run_zine.setCwd(opts.website_root orelse project.path("."));
    run_zine.addArg("release");

    if (opts.force) run_zine.addArg("--force");
    run_zine.addPrefixedFileArg("--output=", project.graph.path(.install_prefix, opts.output_path));
    // _ = run_zine.addPrefixedOutputDirectoryArg("--output=", opts.output_path);

    for (opts.build_assets) |a| {
        run_zine.addArg(project.fmt("--build-asset={s}", .{a.name}));
        run_zine.addFileArg(a.lp);
        if (a.install_always) {
            const install_path = a.install_path orelse std.debug.panic(
                "Build assets '{s}' specifies install_always = true  " ++
                    "but defines no install path.",
                .{a.name},
            );
            run_zine.addArg(project.fmt("--install-always={s}", .{
                install_path,
            }));
        } else if (a.install_path) |ip| {
            run_zine.addArg(project.fmt("--install={s}", .{ip}));
        }
    }

    return run_zine;
}

/// Serves a Zine website via the Zine live server, allowing you to edit
/// the input files and obtaining instant rebuild and page reload.
/// Currently does not support `--watch` but will in the future.
///
/// Ignores `opts.output_path` as it keeps all generated files in memory.
pub fn serve(project: *std.Build, opts: Options) *std.Build.Step.Run {
    const zine_dep = project.dependencyFromBuildZig(@This(), .{
        .optimize = opts.debug.optimize,
        .scope = opts.debug.scopes,
        .@"no-git-version" = true,
    });

    const run_zine = switch (opts.zine) {
        .source => project.addRunArtifact(zine_dep.artifact("zine")),
        .path => |path| project.addSystemCommand(&.{path orelse "zine"}),
    };

    run_zine.setCwd(opts.website_root orelse project.path("."));

    for (opts.build_assets) |a| {
        run_zine.addArg(project.fmt("--build-asset={s}", .{a.name}));
        run_zine.addFileArg(a.lp);
        if (a.install_always) {
            const install_path = a.install_path orelse std.debug.panic(
                "Build assets '{s}' specifies output_always = true  " ++
                    "but defines no install path.",
                .{a.name},
            );
            run_zine.addArg(project.fmt("--install-always={s}", .{
                install_path,
            }));
        } else if (a.install_path) |ip| {
            run_zine.addArg(project.fmt("--install={s}", .{ip}));
        }
    }

    return run_zine;
}

pub fn build(b: *std.Build) !void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const no_git_version = b.option(
        bool,
        "no-git-version",
        "Disable git version detection, useful when using Zine as a dependency",
    ) orelse false;

    const version = b.option(
        []const u8,
        "version",
        "Override the Zine version, use with care!",
    ) orelse getVersion(b, no_git_version);

    const preview = b.option(bool, "preview", "Allow creating release builds of a '-dev' version") orelse false;

    const tsan = b.option(
        bool,
        "tsan",
        "enable thread sanitizer",
    ) orelse false;

    const enable_tracy = b.option(
        bool,
        "tracy",
        "Enable Tracy profiling",
    ) orelse false;

    const highlight = b.option(
        bool,
        "highlight",
        "Include treesitter grammars for build-time syntax highlighting (enabled by default). Disabling reduces executable size significantly.",
    ) orelse true;

    const zine_mod = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
        .single_threaded = b.option(
            bool,
            "single-threaded",
            "build Zine in single-threaded mode",
        ) orelse false,

        .sanitize_thread = tsan,
    });

    // This is this up because otherwise lazy deps will hide the existence of this artifact
    const zine_exe = b.addExecutable(.{
        .name = "zine",
        .root_module = zine_mod,
    });

    const tracy = b.dependency("tracy", .{ .enable = enable_tracy });

    const scopes: []const []const u8 = b.option(
        []const []const u8,
        "scope",
        "logging scopes to enable",
    ) orelse &.{};

    const options = blk: {
        const options = b.addOptions();
        try options.contents.print(b.allocator,
            \\// module = zine
            \\const std = @import("std");
            \\pub const tsan = {};
            \\pub const enable_treesitter = {};
            \\pub const version = "{s}";
            \\pub const log_scope_levels: []const std.log.ScopeLevel = &.{{
            \\
        , .{ tsan, highlight, version });

        for (scopes) |l| try options.contents.print(b.allocator,
            \\.{{.scope = .{f}, .level = .debug}},
        , .{std.zig.fmtId(l)});
        try options.contents.print(b.allocator, "}};", .{});
        break :blk options.createModule();
    };

    const scripty = b.dependency("scripty", .{
        .target = target,
        .optimize = optimize,
        .tracy = enable_tracy,
    }).module("scripty");

    const superhtml = b.dependency("superhtml", .{
        .target = target,
        .optimize = optimize,
        .tracy = enable_tracy,
    }).module("superhtml");

    const ziggy = b.dependency("ziggy", .{
        .target = target,
        .optimize = optimize,
    }).module("ziggy");
    const supermd = b.dependency("supermd", .{
        .target = target,
        .optimize = optimize,
        .tracy = enable_tracy,
    }).module("supermd");
    supermd.addImport("scripty", scripty);
    supermd.addImport("superhtml", superhtml);
    supermd.addImport("ziggy", ziggy);

    const zeit = b.dependency("zeit", .{
        .target = target,
        .optimize = optimize,
    }).module("zeit");
    const syntax = b.dependency("flow_syntax", .{
        .target = target,
        .optimize = optimize,
    });
    const ts = syntax.builder.dependency("tree_sitter", .{
        .target = target,
        .optimize = optimize,
    });
    const treez = ts.module("treez");

    const mime = b.dependency("mime", .{
        .target = target,
        .optimize = optimize,
    });

    const wuffs = b.dependency("wuffs", .{
        .target = target,
        .optimize = optimize,
    });
    const translate_c = b.dependency("translate_c", .{
        .optimize = .fast,
    });

    const release = b.step("release", "Create release builds of Zine");
    if (!preview and (std.mem.indexOf(u8, version, "dev") != null)) {
        release.dependOn(&b.addFail(b.fmt(
            "error: cannot build release of dev version ({s}), use -Dpreview to override",
            .{version},
        )).step);
    } else {
        setupReleaseStep(b, release, version, translate_c);
    }

    const shtml_docgen = b.addExecutable(.{
        .name = "shtml_docgen",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/docgen.zig"),
            .target = target,
            .optimize = .debug,
        }),
    });
    shtml_docgen.root_module.addImport("zeit", zeit);
    shtml_docgen.root_module.addImport("ziggy", ziggy);
    shtml_docgen.root_module.addImport("supermd", supermd);
    shtml_docgen.root_module.addImport("superhtml", superhtml);

    if (b.option(
        bool,
        "docgen",
        "enable building the SuperHTML docgen tool",
    ) orelse false) {
        b.installArtifact(shtml_docgen);
    }

    switch (target.result.os.tag) {
        else => @panic("target must be added to build.zig"),
        .linux => {},
        .netbsd => {},
        .freebsd => {
            // only required for FreeBSD < 15
            // zine_exe.linkSystemLibrary("inotify");
        },
        .windows => {},
        .macos => {
            const Translator = @import("translate_c").Translator;
            const t: Translator = .init(translate_c, .{
                .c_source_file = b.path("src/c.h"),
                .target = target,
                .optimize = optimize,
            });

            const frameworks = b.lazyDependency("frameworks", .{}) orelse return;
            zine_mod.addIncludePath(frameworks.path("include"));
            zine_mod.addFrameworkPath(frameworks.path("Frameworks"));
            zine_mod.addLibraryPath(frameworks.path("lib"));
            zine_mod.linkFramework("CoreServices", .{});
            t.addIncludePath(frameworks.path("include"));
            t.addFrameworkPath(frameworks.path("Frameworks"));
            t.mod.addLibraryPath(frameworks.path("lib"));
            t.mod.linkFramework("CoreServices", .{});
            zine_mod.addImport("c", t.mod);
        },
    }

    zine_mod.addImport("ziggy", ziggy);
    zine_mod.addImport("scripty", scripty);
    zine_mod.addImport("supermd", supermd);
    zine_mod.addImport("superhtml", superhtml);
    zine_mod.addImport("zeit", zeit);
    zine_mod.addImport("options", options);
    zine_mod.addImport("tracy", tracy.module("tracy"));
    zine_mod.addImport("mime", mime.module("mime"));
    zine_mod.addImport("wuffs", wuffs.module("wuffs"));
    if (highlight) {
        zine_mod.addImport("syntax", syntax.module("syntax"));
        zine_mod.addImport("treez", treez);
    }

    const check = b.step("check", "check the standalone zine executable");
    check.dependOn(&zine_exe.step);
    b.installArtifact(zine_exe);

    const run_step = b.step("run", "run the standalone zine executable");
    const zine_run = b.addRunArtifact(zine_exe);
    zine_run.setCwd(b.path("standalone-test"));
    zine_run.addPassthruArgs();
    run_step.dependOn(&zine_run.step);

    const test_step = b.step("test", "build snapshot tests and diff the results");
    setupSchemaCheck(b, target, zine_mod, test_step);
    try setupSnapshotTesting(b, target, zine_exe, test_step);
}

fn setupSchemaCheck(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    zine_mod: *std.Build.Module,
    test_step: *std.Build.Step,
) void {
    {
        const schema = b.path("src/schemas/zine.ziggy-schema");
        const types_mod = b.createModule(.{
            .root_source_file = b.path("src/schemas/zine.zig"),
        });
        types_mod.addImport("zine", zine_mod);

        const ziggy = @import("ziggy");
        const check_step = ziggy.addTypeCheckStep(b, target, .debug, types_mod, schema);
        test_step.dependOn(check_step);
    }

    {
        const schema = b.path("src/schemas/page.ziggy-schema");
        const types_mod = b.createModule(.{
            .root_source_file = b.path("src/schemas/page.zig"),
        });
        types_mod.addImport("zine", zine_mod);

        const ziggy = @import("ziggy");
        const check_step = ziggy.addTypeCheckStep(b, target, .debug, types_mod, schema);
        test_step.dependOn(check_step);
    }
}

fn setupSnapshotTesting(
    b: *std.Build,
    target: std.Build.ResolvedTarget,
    zine_exe: *std.Build.Step.Compile,
    test_step: *std.Build.Step,
) !void {
    const camera = b.addExecutable(.{
        .name = "camera",
        .root_module = b.createModule(.{
            .root_source_file = b.path("build/camera.zig"),
            .target = target,
            .optimize = .fast,
        }),
    });

    const diff = b.addSystemCommand(&.{ "git", "diff", "--exit-code" });
    diff.addDirectoryArg(b.path("tests"));
    diff.setName("git diff tests/");
    test_step.dependOn(&diff.step);

    // We need to add all files in `tests/` to the index so that previously-untracked files show up
    // in the diff. By using `--intent-to-add`, we add new paths to the index with no content, so
    // the actual changes are still unstaged. By using `--ignore-removal`, we prevent paths being
    // *removed* from the index when a file is deleted, so deleted files still appear in the diff.
    const git_add = b.addSystemCommand(&.{ "git", "add", "--intent-to-add", "--ignore-removal" });
    git_add.addDirectoryArg(b.path("tests/"));
    git_add.setName("git add tests/");
    diff.step.dependOn(&git_add.step);

    // content scanning
    {
        const tests_dir = try b.root.root_dir.handle.openDir(b.graph.io, "tests/content-scanning", .{
            .iterate = true,
        });

        var it = tests_dir.iterateAssumeFirstIteration();
        while (try it.next(b.graph.io)) |entry| {
            if (entry.kind != .directory) continue;
            if (entry.name[0] == '.') continue;

            const path = b.pathJoin(&.{
                "tests/content-scanning",
                entry.name,
            });

            const run_camera = b.addRunArtifact(camera);
            run_camera.addArtifactArg(zine_exe);
            run_camera.addArg("debug");
            run_camera.setCwd(b.path(path));
            run_camera.has_side_effects = true;

            const out = run_camera.captureStdErr(.{});

            const update_snap = b.addUpdateSourceFiles();
            update_snap.addCopyFileToSource(out, b.pathJoin(&.{ path, "snapshot.txt" }));

            update_snap.step.dependOn(&run_camera.step);
            git_add.step.dependOn(&update_snap.step);
        }
    }

    // rendering
    {
        const tests_dir = try b.root.root_dir.handle.openDir(b.graph.io, "tests/rendering", .{
            .iterate = true,
        });

        var it = tests_dir.iterateAssumeFirstIteration();
        while (try it.next(b.graph.io)) |entry| {
            if (entry.kind != .directory) continue;
            if (entry.name[0] == '.') continue;
            const src_path = b.pathJoin(&.{
                "tests/rendering",
                entry.name,
            });
            const snapshot_path = b.pathJoin(&.{
                src_path,
                "snapshot",
            });

            _ = b.run(&.{ "rm", "-rf", snapshot_path });

            const run_zine = b.addRunArtifact(zine_exe);
            run_zine.addArg("release");
            run_zine.addArg("--force");
            run_zine.addArg("--output=snapshot");
            run_zine.setCwd(b.path(src_path));
            run_zine.has_side_effects = true;

            const stderr_out = run_zine.captureStdErr(.{});
            const update_snap = b.addUpdateSourceFiles();
            update_snap.addCopyFileToSource(stderr_out, b.pathJoin(
                &.{ src_path, "snapshot.txt" },
            ));

            update_snap.step.dependOn(&run_zine.step);
            git_add.step.dependOn(&update_snap.step);
        }
    }
    // drafts on
    {
        const tests_dir = try b.root.root_dir.handle.openDir(b.graph.io, "tests/drafts", .{
            .iterate = true,
        });

        var it = tests_dir.iterateAssumeFirstIteration();
        while (try it.next(b.graph.io)) |entry| {
            if (entry.kind != .directory) continue;
            if (entry.name[0] == '.') continue;

            const src_path = b.pathJoin(&.{
                "tests/drafts",
                entry.name,
            });

            const snapshot_path = b.pathJoin(&.{
                src_path,
                "snapshot",
            });

            _ = b.run(&.{ "rm", "-rf", snapshot_path });

            const run_zine = b.addRunArtifact(zine_exe);
            run_zine.addArg("release");
            run_zine.addArg("--drafts");
            run_zine.addArg("--force");
            run_zine.addArg("--output=snapshot");
            run_zine.setCwd(b.path(src_path));
            run_zine.has_side_effects = true;

            const stderr_out = run_zine.captureStdErr(.{});
            const update_snap = b.addUpdateSourceFiles();
            update_snap.addCopyFileToSource(stderr_out, b.pathJoin(
                &.{ src_path, "snapshot.txt" },
            ));

            update_snap.step.dependOn(&run_zine.step);
            git_add.step.dependOn(&update_snap.step);
        }
    }
}

fn setupReleaseStep(
    b: *std.Build,
    release_step: *std.Build.Step,
    version: []const u8,
    translate_c: *std.Build.Dependency,
) void {
    const targets: []const std.Target.Query = &.{
        .{ .cpu_arch = .aarch64, .os_tag = .macos },
        .{ .cpu_arch = .aarch64, .os_tag = .linux, .abi = .musl },
        .{ .cpu_arch = .aarch64, .os_tag = .freebsd, .os_version_min = .{ .semver = .{ .major = 15, .minor = 0, .patch = 0 } } },
        .{ .cpu_arch = .aarch64, .os_tag = .netbsd },
        .{ .cpu_arch = .aarch64, .os_tag = .windows },
        .{ .cpu_arch = .x86_64, .os_tag = .macos },
        .{ .cpu_arch = .x86_64, .os_tag = .linux, .abi = .musl },
        .{ .cpu_arch = .x86_64, .os_tag = .freebsd, .os_version_min = .{ .semver = .{ .major = 15, .minor = 0, .patch = 0 } } },
        .{ .cpu_arch = .x86_64, .os_tag = .netbsd },
        .{ .cpu_arch = .x86_64, .os_tag = .windows },
    };

    // Io.Dir.cwd().createDirPath(b.graph.io, b.pathJoin(&.{
    //     b.install_prefix,
    //     "releases",
    // })) catch unreachable;

    for (targets) |t| {
        const target = b.resolveTargetQuery(t);
        const optimize = .fast;

        const tracy = b.dependency("tracy", .{ .enable = false });
        const scripty = b.dependency("scripty", .{
            .target = target,
            .optimize = optimize,
            .tracy = false,
        }).module("scripty");

        const superhtml = b.dependency("superhtml", .{
            .target = target,
            .optimize = optimize,
            .tracy = false,
        }).module("superhtml");

        const ziggy = b.dependency("ziggy", .{
            .target = target,
            .optimize = optimize,
        }).module("ziggy");

        const supermd = b.dependency("supermd", .{
            .target = target,
            .optimize = optimize,
            .tracy = false,
        }).module("supermd");
        supermd.addImport("scripty", scripty);
        supermd.addImport("superhtml", superhtml);
        supermd.addImport("ziggy", ziggy);

        const zeit = b.dependency("zeit", .{
            .target = target,
            .optimize = optimize,
        }).module("zeit");

        const syntax = b.dependency("flow_syntax", .{
            .target = target,
            .optimize = optimize,
        });

        const ts = syntax.builder.dependency("tree_sitter", .{
            .target = target,
            .optimize = optimize,
        });

        const wuffs = b.dependency("wuffs", .{
            .target = target,
            .optimize = optimize,
        });

        const treez = ts.module("treez");

        const mime = b.dependency("mime", .{
            .target = target,
            .optimize = optimize,
        });

        const options = blk: {
            const options = b.addOptions();
            options.contents.print(b.allocator,
                \\// module = zine
                \\const std = @import("std");
                \\pub const tsan = false;
                \\pub const enable_treesitter = true;
                \\pub const version = "{s}";
                \\pub const log_scope_levels: []const std.log.ScopeLevel = &.{{}};
                \\
            , .{version}) catch unreachable;
            break :blk options.createModule();
        };

        const Translator = @import("translate_c").Translator;
        const tr: Translator = .init(translate_c, .{
            .c_source_file = b.path("src/c.h"),
            .target = target,
            .optimize = optimize,
        });

        const zine_exe_release = b.addExecutable(.{
            .name = "zine",
            .root_module = b.createModule(.{
                .root_source_file = b.path("src/main.zig"),
                .target = target,
                .optimize = .fast,
            }),
        });

        zine_exe_release.root_module.addImport("options", options);
        zine_exe_release.root_module.addImport("ziggy", ziggy);
        zine_exe_release.root_module.addImport("scripty", scripty);
        zine_exe_release.root_module.addImport("supermd", supermd);
        zine_exe_release.root_module.addImport("superhtml", superhtml);
        zine_exe_release.root_module.addImport("zeit", zeit);
        zine_exe_release.root_module.addImport("syntax", syntax.module("syntax"));
        zine_exe_release.root_module.addImport("treez", treez);
        zine_exe_release.root_module.addImport("tracy", tracy.module("tracy"));
        zine_exe_release.root_module.addImport("mime", mime.module("mime"));
        zine_exe_release.root_module.addImport("wuffs", wuffs.module("wuffs"));

        switch (target.result.os.tag) {
            else => @panic("target must be added to build.zig"),
            .linux => {},
            .netbsd => {},
            .freebsd => {
                // only required for FreeBSD < 15
                // zine_exe_release.linkSystemLibrary("inotify");
            },
            .windows => {},
            .macos => {
                const frameworks = b.lazyDependency("frameworks", .{
                    .target = target,
                    .optimize = optimize,
                }) orelse return;
                zine_exe_release.root_module.addIncludePath(frameworks.path("include"));
                zine_exe_release.root_module.addFrameworkPath(frameworks.path("Frameworks"));
                zine_exe_release.root_module.addLibraryPath(frameworks.path("lib"));
                zine_exe_release.root_module.linkFramework("CoreServices", .{});
                tr.addIncludePath(frameworks.path("include"));
                tr.addFrameworkPath(frameworks.path("Frameworks"));
                tr.mod.addLibraryPath(frameworks.path("lib"));
                tr.mod.linkFramework("CoreServices", .{});

                zine_exe_release.root_module.addImport("c", tr.mod);
            },
        }

        switch (t.os_tag.?) {
            .macos, .windows => {
                const archive_name = b.fmt("{s}.zip", .{
                    t.zigTriple(b.allocator) catch unreachable,
                });

                const zip = b.addSystemCommand(&.{
                    "zip",
                    "-9",
                    // "-dd",
                    "-q",
                    "-j",
                });
                const archive = zip.addOutputFileArg(archive_name);
                zip.addDirectoryArg(zine_exe_release.getEmittedBin());
                _ = zip.captureStdOut(.{});

                release_step.dependOn(&b.addInstallFileWithDir(
                    archive,
                    .{ .custom = "releases" },
                    archive_name,
                ).step);
            },
            else => {
                const archive_name = b.fmt("{s}.tar.xz", .{
                    t.zigTriple(b.allocator) catch unreachable,
                });

                const tar = b.addSystemCommand(&.{
                    "gtar",
                    "-cJf",
                });

                const archive = tar.addOutputFileArg(archive_name);
                tar.addArg("-C");

                tar.addDirectoryArg(zine_exe_release.getEmittedBinDirectory());
                tar.addArg("zine");
                _ = tar.captureStdOut(.{});

                release_step.dependOn(&b.addInstallFileWithDir(
                    archive,
                    .{ .custom = "releases" },
                    archive_name,
                ).step);
            },
        }
    }
}

fn getVersion(b: *std.Build, no_git_version: bool) []const u8 {
    if (no_git_version) return b.fmt("{s}-dev", .{
        zon.version,
    });

    const git_path = b.findProgram(.{ .names = &.{"git"} }) orelse {
        std.debug.panic(
            "unable to find git, use -Dno-git-version to disable git-based Zine version detection",
            .{},
        );
    };
    var out: u8 = undefined;
    const git_describe = std.mem.trim(
        u8,
        b.runAllowFail(&[_][]const u8{
            git_path,               "-C",
            b.root.root_dir.path.?, "describe",
            "--match",              "*.*.*",
            "--tags",
        }, &out, .ignore) catch unreachable,
        " \n\r",
    );

    switch (std.mem.count(u8, git_describe, "-")) {
        0, 1 => {
            if (git_describe[0] != 'v') {
                std.debug.panic("Unexpected `git describe` output: {s}\n", .{git_describe});
            }
            return git_describe[1..];
        },
        2 => {
            // Untagged development build (e.g. 0.8.0-684-gbbe2cca1a).
            var it = std.mem.splitScalar(u8, git_describe, '-');
            const git_version_str = it.next() orelse unreachable;
            const commit_height = it.next() orelse unreachable;
            _ = commit_height;
            const commit_id = it.next() orelse unreachable;
            const git_version = std.SemanticVersion.parse(git_version_str[1..]) catch
                std.SemanticVersion.parse("0.0.1") catch unreachable;

            var zon_version = std.SemanticVersion.parse(zon.version) catch unreachable;

            {
                if (zon_version.order(git_version) != .gt) {
                    std.debug.panic(
                        "zine maintainers: bump up zine version to '{s}-dev' in build.zig.zon!",
                        .{zon.version},
                    );
                }
            }

            // The version is reformatted in accordance with
            // the https://semver.org specification.
            return b.fmt("{s}-dev+{s}", .{
                zon.version,
                commit_id[1..],
            });
        },
        else => unreachable,
    }
}