// 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(.{}); // Off by default, because it does not pay. `zig build bench` measures // both: the ISBN-13 checksum comes out about level and the ISBN-10 one // comes out slower, since nine lanes of multiply-and-add do not earn // back the cost of widening the digits and assembling the vector. The // option stays so the two implementations can be compared, and so // anyone whose target says otherwise can turn it on. const simd = b.option(bool, "simd", "Use SIMD for computing check digits.") orelse false; const options = b.addOptions(); options.addOption(bool, "simd", simd); const mod = b.addModule("isbn", .{ .root_source_file = b.path("src/isbn.zig"), .target = target, .optimize = optimize, .imports = &.{}, }); mod.addOptions("options", options); const mod_tests = b.addTest(.{ .root_module = mod, }); const run_mod_tests = b.addRunArtifact(mod_tests); const test_step = b.step("test", "Run tests"); test_step.dependOn(&run_mod_tests.step); // Everything that is built but not run by `zig build test`, gathered // so that it cannot quietly stop compiling. The tools are reached only // by steps nobody runs in the ordinary way -- the benchmark by `bench`, // the documentation server by `docs-serve`, the range generator by // `update-ranges` -- so without this a change to the library that broke // one of them would pass CI. const check_step = b.step("check", "Compile everything without running it"); // The benchmark selects each implementation explicitly through // computeCheckDigitWith, so a single ReleaseFast module instance // covers both variants regardless of the -Dsimd setting. const bench_isbn_mod = b.createModule(.{ .root_source_file = b.path("src/isbn.zig"), .target = target, .optimize = .ReleaseFast, }); bench_isbn_mod.addOptions("options", options); const bench_mod = b.createModule(.{ .root_source_file = b.path("src/benchmark.zig"), .target = target, .optimize = .ReleaseFast, .imports = &.{ .{ .name = "isbn", .module = bench_isbn_mod }, }, }); const bench_exe = b.addExecutable(.{ .name = "benchmark", .root_module = bench_mod, }); const run_bench = b.addRunArtifact(bench_exe); const bench_step = b.step("bench", "Run benchmarks comparing SIMD and scalar check digit computation"); bench_step.dependOn(&run_bench.step); check_step.dependOn(&bench_exe.step); // -- documentation ------------------------------------------------------- // // Zig emits the API documentation as a side effect of compiling, so the // module is built as a library purely to get at it. What comes out is not // a page but a program: a WebAssembly viewer, its javascript, and a tar of // the sources it reads from. const library = b.addLibrary(.{ .name = "isbn", .root_module = mod }); const install_docs = b.addInstallDirectory(.{ .source_dir = library.getEmittedDocs(), .install_dir = .prefix, .install_subdir = "docs", }); const docs_step = b.step("docs", "Build the API documentation into zig-out/docs"); docs_step.dependOn(&install_docs.step); // That 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. It is the same reason `zig std` runs a // server rather than 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); // The server has tests of its own; without this they would never run. test_step.dependOn(&b.addRunArtifact( b.addTest(.{ .root_module = docs_server.root_module }), ).step); check_step.dependOn(&docs_server.step); // The generator runs on the build host and writes into the source // tree, so it ignores -Dtarget and -Doptimize. const update_ranges_step = b.step("update-ranges", "Fetch the ISBN range data and regenerate src/ranges.zig"); // zxml is declared lazy: it is needed only to run the generator, which is // a maintenance tool and is not part of the published package, so nobody // depending on isbn has to fetch it. if (b.lazyDependency("zxml", .{ .target = b.graph.host })) |zxml| { const generate_exe = b.addExecutable(.{ .name = "generate_ranges", .root_module = b.createModule(.{ .root_source_file = b.path("tools/generate_ranges.zig"), .target = b.graph.host, .optimize = .Debug, .imports = &.{ .{ .name = "zxml", .module = zxml.module("zxml") }, }, }), }); const run_generate = b.addRunArtifact(generate_exe); const generated = run_generate.addOutputFileArg("ranges.zig"); // Declaring an output makes the run step cacheable, but the fetch // must happen every time the step is requested. run_generate.has_side_effects = true; const update_source = b.addUpdateSourceFiles(); update_source.addCopyFileToSource(generated, "src/ranges.zig"); update_ranges_step.dependOn(&update_source.step); // Only reachable when zxml has already been fetched, so `zig build // check` on a fresh clone covers everything else and picks this up // the first time `update-ranges` is asked for. check_step.dependOn(&generate_exe.step); } }