zfin/build.zig

const std = @import("std");
const Coverage = @import("build/Coverage.zig");

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

    // External dependencies
    const srf_dep = b.dependency("srf", .{
        .target = target,
        .optimize = optimize,
    });

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

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

    const srf_mod = srf_dep.module("srf");

    // Build-time info: version string (from git describe) and build timestamp.
    // Exposed to application code as `@import("build_info")`.
    //
    // The version string is derived from `git describe --tags --always --dirty`
    // so dev builds show the nearest tag plus commit hash + dirty flag. If git
    // is unavailable (e.g. building from a source tarball), falls back to the
    // `.version` in build.zig.zon.
    const build_info = buildInfoOptions(b);

    // Library module -- the public API for downstream consumers of zfin.
    // Internal code (CLI, TUI) uses file-path imports instead.
    _ = b.addModule("zfin", .{
        .root_source_file = b.path("src/root.zig"),
        .target = target,
        .imports = &.{
            .{ .name = "srf", .module = srf_mod },
            .{ .name = "build_info", .module = build_info },
        },
    });

    // Shared imports for the unified module (CLI + TUI + lib in one module).
    // Only external deps -- internal imports use file paths so that Zig's
    // test runner can discover tests across the entire source tree.
    const imports: []const std.Build.Module.Import = &.{
        .{ .name = "srf", .module = srf_mod },
        .{ .name = "vaxis", .module = vaxis_dep.module("vaxis") },
        .{ .name = "z2d", .module = z2d_dep.module("z2d") },
        .{ .name = "build_info", .module = build_info },
    };

    // Unified executable (CLI + TUI in one binary)
    const exe = b.addExecutable(.{
        .name = "zfin",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
            .imports = imports,
        }),
    });
    b.installArtifact(exe);

    // Run step: `zig build run -- <args>`
    const run_step = b.step("run", "Run the zfin CLI");
    const run_cmd = b.addRunArtifact(exe);
    run_step.dependOn(&run_cmd.step);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }

    // Tests: single binary, single module. refAllDeclsRecursive in
    // main.zig discovers all tests via file imports.
    const test_step = b.step("test", "Run all tests");
    const tests = b.addTest(.{ .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
        .imports = imports,
    }) });
    test_step.dependOn(&b.addRunArtifact(tests).step);

    // Docs (still uses the library module for clean public API docs)
    const lib = b.addLibrary(.{
        .name = "zfin",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/root.zig"),
            .target = target,
            .optimize = optimize,
            .imports = &.{
                .{ .name = "srf", .module = srf_mod },
                .{ .name = "build_info", .module = build_info },
            },
        }),
    });
    const docs_step = b.step("docs", "Generate documentation");
    docs_step.dependOn(&b.addInstallDirectory(.{
        .source_dir = lib.getEmittedDocs(),
        .install_dir = .prefix,
        .install_subdir = "docs",
    }).step);

    // Coverage: `zig build coverage` (uses kcov, Linux x86_64/aarch64 only)
    {
        var cov = Coverage.init(b);
        _ = cov.addModule(b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
            .imports = imports,
        }), "zfin");
    }
}

/// Produce the `build_info` module exposing `version` (derived from `git
/// describe`) and `build_timestamp` (Unix epoch seconds at build time).
/// Consumed as `@import("build_info")` from `src/version.zig`.
fn buildInfoOptions(b: *std.Build) *std.Build.Module {
    const opts = b.addOptions();

    // `git describe --tags --always --dirty` gives the closest tag, with a
    // distance-+-hash suffix when HEAD isn't exactly on a tag, plus a
    // `-dirty` marker if the working tree has uncommitted changes. Falls
    // back to the build.zig.zon `.version` when git is unavailable.
    const version = gitDescribe(b) orelse fallbackVersion();
    opts.addOption([]const u8, "version", version);

    // Seconds since the Unix epoch at build time. Rendered by `zfin version
    // --verbose` as a human-readable date.
    opts.addOption(i64, "build_timestamp", std.time.timestamp());

    return opts.createModule();
}

/// Run `git describe --tags --always --dirty` in the repo root and return
/// the trimmed output. Returns null on any error (git missing, not a repo,
/// non-zero exit).
fn gitDescribe(b: *std.Build) ?[]const u8 {
    var child = std.process.Child.init(&.{ "git", "describe", "--tags", "--always", "--dirty" }, b.allocator);
    child.cwd = b.build_root.path;
    child.stdout_behavior = .Pipe;
    child.stderr_behavior = .Ignore;
    child.spawn() catch return null;

    const stdout_file = child.stdout orelse {
        _ = child.wait() catch {};
        return null;
    };
    const stdout_bytes = stdout_file.readToEndAlloc(b.allocator, 4096) catch {
        _ = child.wait() catch {};
        return null;
    };

    const term = child.wait() catch return null;
    switch (term) {
        .Exited => |code| if (code != 0) return null,
        else => return null,
    }

    const trimmed = std.mem.trim(u8, stdout_bytes, " \t\r\n");
    if (trimmed.len == 0) return null;
    return b.dupe(trimmed);
}

/// Read `.version` from `build.zig.zon` as a fallback when git describe
/// fails (e.g. when building from a source tarball with no .git directory).
/// Returns a static string if even that fails.
fn fallbackVersion() []const u8 {
    // `build.zig.zon` is embedded at compile time so the fallback never
    // requires runtime filesystem access in the built binary — we only do
    // this lookup at build time, on the build host.
    const zon_contents = @embedFile("build.zig.zon");
    if (std.mem.indexOf(u8, zon_contents, ".version = \"")) |start| {
        const after = zon_contents[start + ".version = \"".len ..];
        if (std.mem.indexOfScalar(u8, after, '"')) |end| {
            return after[0..end];
        }
    }
    return "unknown";
}