// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT const std = @import("std"); pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); const mod = b.addModule("z46", .{ .root_source_file = b.path("src/root.zig"), // The optimize mode has to be set here, not only on the executable // below: without it the module's tests always build in Debug and // `zig build test -Doptimize=...` reaches only the executable's tests. .target = target, .optimize = optimize, }); // The library also ships a CLI that validates and describes its arguments. const exe = b.addExecutable(.{ .name = "z46", .root_module = b.createModule(.{ .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "z46", .module = mod }, }, }), }); b.installArtifact(exe); const run_cmd = b.addRunArtifact(exe); run_cmd.step.dependOn(b.getInstallStep()); if (b.args) |args| run_cmd.addArgs(args); const run_step = b.step("run", "Run the app"); run_step.dependOn(&run_cmd.step); // Renders the module's doc comments into browsable HTML under // `zig-out/docs`, which CI publishes to https://jeff.jcollie.page/z46/. // The documentation comes from an object file because that is what emits // it; the object is never linked or installed. const docs_obj = b.addObject(.{ .name = "z46", .root_module = mod, }); const install_docs = b.addInstallDirectory(.{ .source_dir = docs_obj.getEmittedDocs(), .install_dir = .prefix, .install_subdir = "docs", }); const docs_step = b.step("docs", "Generate API documentation"); docs_step.dependOn(&install_docs.step); // The generated viewer fetches `sources.tar` and `main.wasm` at runtime, // which a browser refuses to do from a `file://` page, so reading the docs // locally means serving them. This is the same reason `zig std` runs a // server rather than just opening a file. const docs_port = b.option(u16, "docs-port", "Port for `zig build docs-serve` (default 8000)") orelse 8000; const docs_server = b.addExecutable(.{ .name = "docs-server", .root_module = b.createModule(.{ .root_source_file = b.path("tools/docs_server.zig"), // Always built for the machine running the build, never for // whatever `-Dtarget` the library is being built for. .target = b.graph.host, .optimize = .Debug, }), }); const run_docs_server = b.addRunArtifact(docs_server); run_docs_server.step.dependOn(&install_docs.step); run_docs_server.addArg(b.getInstallPath(.prefix, "docs")); run_docs_server.addArg(b.fmt("{d}", .{docs_port})); // The server runs until interrupted, so its output has to reach the // terminal rather than being captured by the build runner. run_docs_server.stdio = .inherit; const docs_serve_step = b.step("docs-serve", "Serve the API documentation over HTTP"); docs_serve_step.dependOn(&run_docs_server.step); // A test binary covers one module at a time, so the library, the CLI and // the documentation server need one each. const mod_tests = b.addTest(.{ .name = "z46-test", .root_module = mod }); const exe_tests = b.addTest(.{ .name = "z46-cli-test", .root_module = exe.root_module }); const docs_server_tests = b.addTest(.{ .name = "docs-server-test", .root_module = docs_server.root_module, }); const test_step = b.step("test", "Run tests"); for ([_]*std.Build.Step.Compile{ mod_tests, exe_tests, docs_server_tests }) |test_binary| { test_step.dependOn(&b.addRunArtifact(test_binary).step); } // Benchmarks are only meaningful optimized, so the library is built again // as ReleaseFast here rather than reusing `mod`, whose optimize mode // follows `-Doptimize` and defaults to Debug. const bench_mod = b.createModule(.{ .root_source_file = b.path("src/root.zig"), .target = target, .optimize = .ReleaseFast, }); const bench_exe = b.addExecutable(.{ .name = "z46-bench", .root_module = b.createModule(.{ .root_source_file = b.path("tools/bench.zig"), .target = target, .optimize = .ReleaseFast, .imports = &.{ .{ .name = "z46", .module = bench_mod }, }, }), }); // The benchmark harness has tests of its own, and nothing else compiles // it, so without this it could stop building and no test would notice. const bench_tests = b.addTest(.{ .name = "bench-test", .root_module = bench_exe.root_module, }); test_step.dependOn(&b.addRunArtifact(bench_tests).step); const run_bench = b.addRunArtifact(bench_exe); // Timings go straight to the terminal; capturing them would serve nothing. run_bench.stdio = .inherit; const bench_step = b.step("bench", "Run the microbenchmarks"); bench_step.dependOn(&run_bench.step); // kcov runs the library's tests under a tracer and writes an HTML report // to `zig-out/coverage`. Restricting it to `src` keeps the standard // library, which these tests exercise heavily, out of the numbers. // // Only the library's tests are measured. kcov reads the CLI and // documentation-server test binaries without error but records no lines // for this package's files in them, even though their debug info names the // same source directory, so including them would cost a traced run each // and change nothing in the report. // // Coverage wants an unoptimised build: under `-Doptimize=ReleaseFast` the // inlining leaves the line counts meaningless. // // Nothing in the library's tests may construct a `std.testing.Smith`. // Merely having one in the binary makes kcov record no lines at all, for // any file, and the report comes out as 0.00% of zero lines rather than as // an error. The fuzz targets are reached through `std.testing.fuzz`, which // does not have that effect. // // There is a second way into that same silent 0.00%, and it is a size // limit rather than a construct: past some amount of debug info kcov // simply records nothing. `std.json.parseFromSlice` builds its parser by // reflecting over the type it is given, so a test that calls it costs a // whole copy of that machinery, and fifteen of them -- one per type here // -- goes over the line. Either half of the JSON tests alone measured // fine; the two together did not. So the per-type `jsonParse` tests drive // the hook from a `std.json.Scanner` directly, which is what they are // named after anyway, and `root.zig` pays for `parseFromSlice` once. // // It is not only `std.json`, and it is not simply size. Four things have // triggered it so far, each found by adding one thing and watching the // report go empty: // // * a `std.testing.Smith` anywhere in the binary; // * `std.json.parseFromSlice` instantiated once per type, fifteen times; // * `std.mem.sort` instantiated once per network type, where // `std.mem.sortUnstable` in the same place is fine; // * a `std.json.Stringify` constructed directly in a test, where // `std.json.Stringify.value` in the same place is fine. // // Size is not the explanation, tempting as it looked: a binary of 28.27 // MB has produced an empty report where one of 28.32 MB produced a full // one. Whatever kcov cannot digest, it is a construct rather than a // quantity, and the last two pairs above are each a smaller binary // failing where a larger one succeeded. // // The practical consequence is that a random sweep over `Ipv4Range.merge` // is missing from `root.zig`, where the one over `Ipv4Network.merge` is // present: adding it empties the report and nothing short of removing it // brings the report back. The range fold is a single pass over a sorted // slice where the network fold has to reason about alignment and repeat // itself, so it is the one of the two that least needed the sweep, and // its unit tests cover touching, overlapping, nested, duplicate, gapped // and top-of-space cases explicitly. // // All of these failures look identical from outside -- an empty report, // a zero, and every test passing -- so the way to work on this file is to // add one thing at a time and run `zig build coverage` after each. // // A note on reading the output: the build runner prints a `failed command` // line for any step that writes to stderr, which a passing test run does. // The exit status is what says whether the step failed. const run_kcov = b.addSystemCommand(&.{ "kcov", "--include-path=src" }); const coverage_output = run_kcov.addOutputDirectoryArg("coverage"); run_kcov.addArtifactArg(mod_tests); const coverage_step = b.step("coverage", "Generate a test coverage report with kcov"); coverage_step.dependOn(&b.addInstallDirectory(.{ .source_dir = coverage_output, .install_dir = .prefix, .install_subdir = "coverage", }).step); }