build.zig

//! page-stack build script.
//!
//! Provides library, documentation, test, benchmark, and freestanding-check
//! steps. Library sources under `src/*` are strictly freestanding; `tools/*`
//! and `tests/*` are host-only.

const std = @import("std");

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

    // Freestanding library module (must stay host-independent).
    const lib_mod = b.createModule(.{
        .root_source_file = b.path("src/root.zig"),
        .target = target,
        .optimize = optimize,
    });
    const lib = b.addLibrary(.{
        .name = "page_stack",
        .root_module = lib_mod,
    });
    b.installArtifact(lib);

    // Autodoc generation step: `zig build docs`.
    const install_docs = b.addInstallDirectory(.{
        .source_dir = lib.getEmittedDocs(),
        .install_dir = .prefix,
        .install_subdir = "docs",
    });
    const docs_step = b.step("docs", "Generate HTML documentation using Zig Autodoc");
    docs_step.dependOn(&install_docs.step);

    // Host-only unit + concurrency tests: `zig build test`.
    const test_mod = b.createModule(.{
        .root_source_file = b.path("tests/test_stack.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{
            .{ .name = "page_stack", .module = lib_mod },
        },
    });
    const main_tests = b.addTest(.{
        .root_module = test_mod,
    });
    const run_main_tests = b.addRunArtifact(main_tests);
    const test_step = b.step("test", "Run library unit tests and concurrency stress tests");
    test_step.dependOn(&run_main_tests.step);

    // Freestanding compile check: `zig build freestanding`.
    // Proves src/* compiles for a true freestanding target without running.
    const freestanding_target = b.resolveTargetQuery(.{
        .cpu_arch = .x86_64,
        .os_tag = .freestanding,
        .abi = .none,
    });
    const freestanding_mod = b.createModule(.{
        .root_source_file = b.path("src/root.zig"),
        .target = freestanding_target,
        .optimize = optimize,
    });
    const freestanding_lib = b.addLibrary(.{
        .name = "page_stack_freestanding",
        .root_module = freestanding_mod,
    });
    const freestanding_step = b.step("freestanding", "Compile src/* for x86_64-freestanding (no run)");
    freestanding_step.dependOn(&freestanding_lib.step);

    // Host-only benchmarks: `zig build bench -Doptimize=ReleaseFast`.
    const bench_mod = b.createModule(.{
        .root_source_file = b.path("benchmarks/bench_stack.zig"),
        .target = target,
        .optimize = optimize,
        .imports = &.{
            .{ .name = "page_stack", .module = lib_mod },
        },
    });
    const bench_exe = b.addExecutable(.{
        .name = "bench_stack",
        .root_module = bench_mod,
    });
    const run_bench = b.addRunArtifact(bench_exe);
    const bench_step = b.step("bench", "Run performance benchmarks (TDD Section 5)");
    bench_step.dependOn(&run_bench.step);
}