// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT const std = @import("std"); /// Unicode character properties this library needs from uucode. Listing them /// explicitly keeps the generated tables to only what IDNA actually consults. const uucode_fields: []const []const u8 = &.{ // Canonical composition, for the NFC pass UTS #46 requires. "canonical_combining_class", "decomposition_type", "decomposition_mapping", "is_composition_exclusion", // Validity and the CONTEXTJ/CONTEXTO and Bidi rules. "general_category", "bidi_class", "joining_type", "script", }; /// The `uri_unicode` module, created the first time anything asks for it and /// shared by everything that asks afterwards. Null until uucode has been /// fetched, which the build runner then does and runs the configure phase /// again, so a caller that gets null need do nothing but carry on. /// /// This is how a dependent asks for it, from its own `build.zig`: /// /// ```zig /// const uri_dep = b.dependency("uri", .{ .target = target, .optimize = optimize }); /// if (@import("uri").unicodeModule(uri_dep, target, optimize)) |uri_unicode| { /// mod.addImport("uri_unicode", uri_unicode); /// } /// ``` /// /// It is a function rather than a module `build` adds, because uucode is a /// lazy dependency: `build` cannot tell whether anybody wants Unicode support, /// and a lazy dependency it asked for would be fetched for every dependent /// whether it used it or not. Asking here means only the ones that call this /// fetch uucode. `target` and `optimize` are uucode's, which compiles its own /// table generator; pass the same ones given to `b.dependency`. pub fn unicodeModule( uri_dep: *std.Build.Dependency, target: std.Build.ResolvedTarget, optimize: std.builtin.Optimize, ) ?*std.Build.Module { return addUnicodeModule(uri_dep.builder, target, optimize); } fn addUnicodeModule( b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.Optimize, ) ?*std.Build.Module { if (b.modules.get("uri_unicode")) |m| return m; const uucode = lazyUucode(b, target, optimize) orelse return null; const m = b.addModule("uri_unicode", .{ .root_source_file = b.path("src/unicode/root.zig"), }); m.addImport("uri", b.modules.get("uri").?); m.addImport("uucode", uucode); return m; } fn lazyUucode( b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.Optimize, ) ?*std.Build.Module { const dep = b.lazyDependency("uucode", .{ .target = target, .optimize = optimize, .fields = uucode_fields, }) orelse return null; return dep.module("uucode"); } /// A `uri` module of its own, for a compilation that is not the library's: the /// WebAssembly module and the fuzz driver each build for a target of their /// own, and so each needs its own z46 to go with it. fn createUri(b: *std.Build, z46: *std.Build.Module) *std.Build.Module { const m = b.createModule(.{ .root_source_file = b.path("src/root.zig") }); m.addImport("z46", z46); return m; } /// A `uri_unicode` module of its own, for the same compilations as `createUri`. fn createUnicode(b: *std.Build, uri: *std.Build.Module, uucode: *std.Build.Module) *std.Build.Module { const m = b.createModule(.{ .root_source_file = b.path("src/unicode/root.zig") }); m.addImport("uri", uri); m.addImport("uucode", uucode); return m; } pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); // Address literals are core RFC 3986 syntax rather than an add-on, so z46 // is an unconditional dependency. It is small, allocation-free and has no // dependencies of its own. const z46 = b.dependency("z46", .{ .target = target, .optimize = optimize, }).module("z46"); // The published module carries no target/optimize of its own, so a // dependent builds it for whatever it is building for. It has no // dependency but z46; everything that needs uucode is in `uri_unicode`, // which `unicodeModule` adds on request. const uri = b.addModule("uri", .{ .root_source_file = b.path("src/root.zig"), }); uri.addImport("z46", z46); // Everything below is for working on this library -- its tests, fuzzing, // documentation and WebAssembly build -- and all of it needs uucode. A // dependent never runs any of it, and declaring it there would fetch // uucode for every dependent whether it asked for Unicode or not. if (!b.isRoot()) return; const uri_unicode = addUnicodeModule(b, target, optimize) orelse return; const test_module = b.createModule(.{ .root_source_file = b.path("src/root.zig"), .target = target, .optimize = optimize, }); test_module.addImport("z46", z46); const unicode_test_module = b.createModule(.{ .root_source_file = b.path("src/unicode/root.zig"), .target = target, .optimize = optimize, }); unicode_test_module.addImport("uri", uri); unicode_test_module.addImport("uucode", lazyUucode(b, target, optimize).?); // The fuzz targets are a module of their own, which reaches the library // through `uri` and `uri_unicode` exactly as a dependent would. const fuzz_test_module = b.createModule(.{ .root_source_file = b.path("src/fuzz.zig"), .target = target, .optimize = optimize, }); fuzz_test_module.addImport("uri", uri); fuzz_test_module.addImport("uri_unicode", uri_unicode); fuzz_test_module.addImport("z46", z46); // -- WebAssembly ------------------------------------------------------ // // A freestanding wasm32 module with a flat, string-in/string-out ABI, for // `web/uri.js` to drive from a browser. It is a separate root // (`src/wasm.zig`) rather than the library module itself, because the // exports have to be reachable from the compilation root to be emitted. const wasm_optimize = b.option( std.lang.Optimize, "wasm-optimize", "Optimization mode for `zig build wasm` (default ReleaseSmall)", ) orelse .small; const wasm_target = b.resolveTargetQuery(.{ .cpu_arch = .wasm32, .os_tag = .freestanding, }); const wasm_module = b.createModule(.{ .root_source_file = b.path("src/wasm.zig"), .target = wasm_target, .optimize = wasm_optimize, }); // IDNA and IRI display are much of the reason to want this in a browser // at all, so the module always has `uri_unicode` in it. const wasm_uri = createUri(b, b.dependency("z46", .{ .target = wasm_target, .optimize = wasm_optimize, }).module("z46")); wasm_module.addImport("uri", wasm_uri); wasm_module.addImport("uri_unicode", createUnicode( b, wasm_uri, lazyUucode(b, wasm_target, wasm_optimize) orelse return, )); const wasm = b.addExecutable(.{ .name = "uri", .root_module = wasm_module, }); // No `main`: the module is a bag of exports the host calls into, and // `rdynamic` is what keeps them from being stripped as unreachable. wasm.entry = .disabled; wasm.rdynamic = true; // The loader, the demo page and the module all end up in one directory, // which is the whole of what has to be served. const install_wasm = b.addInstallArtifact(wasm, .{ .dest_dir = .{ .override = .{ .custom = "web" } }, }); const install_web = b.addInstallDirectory(.{ .source_dir = b.path("web"), .install_dir = .prefix, .install_subdir = "web", // The test suite is run from the source tree, and has no business in // a directory whose whole purpose is to be served. .exclude_extensions = &.{".test.js"}, }); const wasm_step = b.step("wasm", "Build the WebAssembly module and its JavaScript loader"); wasm_step.dependOn(&install_wasm.step); wasm_step.dependOn(&install_web.step); // Exercising the JavaScript needs a JavaScript engine, so this is its own // step rather than part of `zig build test`: `node` is in the devshell but // is not something the library itself requires. const run_web_tests = b.addSystemCommand(&.{"node"}); run_web_tests.addFileArg(b.path("web/uri.test.js")); run_web_tests.addFileArg(wasm.getEmittedBin()); run_web_tests.stdio = .inherit; const web_test_step = b.step("test-web", "Run the JavaScript binding's tests under node"); web_test_step.dependOn(&run_web_tests.step); // LLVM rather than the self-hosted backend Debug uses by default, which // emits no coverage instrumentation: without it `zig build test --fuzz` // has an empty table of program counters and cannot steer, and kcov has // nothing to report. // // One binary per module, because a test binary runs only the tests its // root module reaches: `uri`, `uri_unicode`, and the fuzz targets. const test_step = b.step("test", "Run unit tests"); for ([_]struct { []const u8, *std.Build.Module }{ .{ "uri-test", test_module }, .{ "uri-unicode-test", unicode_test_module }, .{ "uri-fuzz-test", fuzz_test_module }, }) |t| { const unit_tests = b.addTest(.{ .name = t[0], .root_module = t[1], .use_llvm = true, }); test_step.dependOn(&b.addRunArtifact(unit_tests).step); } // -- fuzzing ---------------------------------------------------------- // // The targets in `src/fuzz.zig` are ordinary tests as well, so `zig build // test` runs each against one smoke input and they cost that run nothing. // Searching is `zig build test --fuzz=N`, steered by coverage now that the // test binary is built with LLVM. `zig build fuzz-run` is a loop of our own // as well, with a corpus in place of the feedback, which counts what it // did and checks every input for leaks; `tools/fuzz.zig` says what that // costs and what it buys. // // Optimised, because a fuzzer's whole job is how many inputs it gets // through, and ReleaseSafe keeps every check that makes a failure a failure. const fuzz_module = b.createModule(.{ .root_source_file = b.path("src/fuzz.zig"), .target = b.graph.host, .optimize = .safe, }); const fuzz_z46 = b.dependency("z46", .{ .target = b.graph.host, .optimize = .safe, }).module("z46"); const fuzz_uri = createUri(b, fuzz_z46); fuzz_module.addImport("z46", fuzz_z46); fuzz_module.addImport("uri", fuzz_uri); fuzz_module.addImport("uri_unicode", createUnicode( b, fuzz_uri, lazyUucode(b, b.graph.host, .safe) orelse return, )); const fuzz_run = b.addExecutable(.{ .name = "zig-uri-fuzz", .root_module = b.createModule(.{ .root_source_file = b.path("tools/fuzz.zig"), .target = b.graph.host, .optimize = .safe, .imports = &.{.{ .name = "fuzz_targets", .module = fuzz_module }}, }), }); const run_fuzz = b.addRunArtifact(fuzz_run); run_fuzz.stdio = .inherit; run_fuzz.addPassthruArgs(); const fuzz_run_step = b.step("fuzz-run", "Fuzz the targets with a loop of our own"); fuzz_run_step.dependOn(&run_fuzz.step); // Nothing else builds the driver, so without this it could stop compiling // and no test would notice. const check_step = b.step("check", "Compile everything without running it"); check_step.dependOn(&fuzz_run.step); // -- documentation ---------------------------------------------------- // // Zig emits the documentation as a side effect of compiling, one module at // a time, so each module gets a bundle in a subdirectory of its own under // an index that says which is which. const documented = [_]struct { name: []const u8, module: *std.Build.Module, needs: []const u8, what: []const u8, }{ .{ .name = "uri", .module = test_module, .needs = "z46", .what = "Parsing, formatting, resolution and normalization; LDAP, data, file and sdns URLs; Punycode.", }, .{ .name = "uri_unicode", .module = unicode_test_module, .needs = "uri, uucode", .what = "IDNA (UTS #46), Normalization Form C, and converting a host between its URI and IRI forms.", }, }; var index: std.ArrayList(u8) = .empty; index.appendSlice(b.allocator, \\ \\ \\ \\ \\zig-uri API documentation \\ \\

zig-uri

\\

A URI parser and formatter for Zig, modelled on Python's \\hyperlink package. Generated from the doc comments. \\

Two modules, so that only what needs Unicode tables pays for them. \\ \\
ModuleDepends on \\ ) catch @panic("OOM"); const docs_dir = b.addWriteFiles(); for (documented) |d| { const docs = b.addObject(.{ .name = d.name, .root_module = d.module }); _ = docs_dir.addCopyDirectory(docs.getEmittedDocs(), d.name, .{}); index.print(b.allocator, "
{s}{s}{s}\n", .{ d.name, d.name, d.needs, d.what, }) catch @panic("OOM"); } index.appendSlice(b.allocator, "
\n") catch @panic("OOM"); _ = docs_dir.add("index.html", index.items); const install_docs = b.addInstallDirectory(.{ .source_dir = docs_dir.getDirectory(), .install_dir = .prefix, .install_subdir = "docs", }); const docs_step = b.step("docs", "Build the 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.addDirectoryArg(docs_dir.getDirectory()); 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 wasm module fetched from a `file://` page is refused by every browser, // so trying the demo means serving it too. The docs server already knows // the handful of MIME types involved, so it does this job as well. const web_port = b.option(u16, "web-port", "Port for `zig build web-serve` (default 8001)") orelse 8001; // The install prefix is not known while the build is configured, so the // server is handed a directory assembled in the cache with the same // contents `zig build wasm` installs. const web_dir = b.addWriteFiles(); _ = web_dir.addCopyDirectory(b.path("web"), "", .{ .exclude_extensions = &.{".test.js"}, }); _ = web_dir.addCopyFile(wasm.getEmittedBin(), "uri.wasm"); const run_web_server = b.addRunArtifact(docs_server); run_web_server.addDirectoryArg(web_dir.getDirectory()); run_web_server.addArg(b.fmt("{d}", .{web_port})); run_web_server.stdio = .inherit; const web_serve_step = b.step("web-serve", "Serve the WebAssembly demo page over HTTP"); web_serve_step.dependOn(&run_web_server.step); // The server has tests of its own; without this they would never run. const docs_server_tests = b.addTest(.{ .root_module = docs_server.root_module }); test_step.dependOn(&b.addRunArtifact(docs_server_tests).step); check_step.dependOn(&docs_server.step); }