Something went wrong. Try again.
A URI parser and formatter for Zig, modelled on Python's hyperlink package, with LDAP URLs, file: URIs and sdns:// DNS stamps beside it.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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, \\<!doctype html> \\<html lang="en"> \\<meta charset="utf-8"> \\<meta name="viewport" content="width=device-width, initial-scale=1"> \\<title>zig-uri API documentation</title> \\<style> \\body { font-family: system-ui, sans-serif; max-width: 44rem; \\ margin: 4rem auto; padding: 0 1rem; line-height: 1.5 } \\td, th { text-align: left; vertical-align: top; padding: 0.3rem 1.5rem 0.3rem 0 } \\code { background: #eee; padding: 0 0.2rem } \\</style> \\<h1>zig-uri</h1> \\<p>A URI parser and formatter for Zig, modelled on Python's \\<code>hyperlink</code> package. Generated from the doc comments. \\<p>Two modules, so that only what needs Unicode tables pays for them. \\<table> \\<tr><th>Module<th>Depends on<th> \\ ) 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, "<tr><td><a href=\"{s}/\"><code>{s}</code></a><td>{s}<td>{s}\n", .{ d.name, d.name, d.needs, d.what, }) catch @panic("OOM"); } index.appendSlice(b.allocator, "</table>\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);}