add build system notes from ghostty and bun

- organization.md: modular build.zig, Config struct, SharedDeps
- dependencies.md: lazy deps, vendored vs system libs, pinning
- codegen.md: generating zig source at build time
- cross-compilation.md: cpu targeting, glibc, universal binaries

patterns from studying two large production zig projects

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

languages/ziglang/README.md

···
 # zig
 
-notes on [zig](https://ziglang.org/) patterns from building atproto/bluesky infrastructure.
+notes on [zig](https://ziglang.org/) patterns.
 
-## versions
+## topics
 
-- [0.15](./0.15/) - major i/o overhaul, new build system patterns ([release notes](https://ziglang.org/download/0.15.1/release-notes.html))
+- [0.15](./0.15/) - version-specific patterns (i/o overhaul, arraylist, concurrency)
+- [build](./build/) - build system patterns from large projects
 
-## projects
+## sources
 
-these notes are derived from:
+patterns derived from building and studying:
 
-| project | description |
-|---------|-------------|
-| [music-atmosphere-feed](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed) | bluesky feed generator - http server, jetstream consumer, jwt verification |
-| [find-bufo](https://tangled.sh/@zzstoatzz.io/find-bufo) | bluesky bot - websocket client, bluesky api, image posting |
-| [leaflet-search](https://tangled.sh/@zzstoatzz.io/leaflet-search) | fts search backend - sqlite fts5, http server, dashboard |
-| [zql](https://tangled.sh/@zzstoatzz.io/zql) | comptime sql parsing - parameter extraction, struct mapping |
+| project | what it is |
+|---------|------------|
+| [music-atmosphere-feed](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed) | bluesky feed generator |
+| [find-bufo](https://tangled.sh/@zzstoatzz.io/find-bufo) | bluesky bot |
+| [leaflet-search](https://tangled.sh/@zzstoatzz.io/leaflet-search) | fts search backend |
+| [zql](https://tangled.sh/@zzstoatzz.io/zql) | comptime sql parsing |
+| [ghostty](https://github.com/ghostty-org/ghostty) | terminal emulator (build system) |
+| [bun](https://github.com/oven-sh/bun) | javascript runtime (build system) |
 
-## dependencies
+## libraries
 
-- [websocket.zig](https://github.com/karlseguin/websocket.zig) - websocket client with tls support
+- [websocket.zig](https://github.com/karlseguin/websocket.zig) - websocket client with tls
 - [zqlite.zig](https://github.com/karlseguin/zqlite.zig) - sqlite wrapper

languages/ziglang/build/README.md

···
+# build system
+
+notes on zig's build system, drawn from studying [ghostty](https://github.com/ghostty-org/ghostty) (terminal emulator) and [bun](https://github.com/oven-sh/bun) (javascript runtime). both are large, production zig projects with sophisticated builds.
+
+## notes
+
+- [organization](./organization.md) - structuring build.zig for large projects
+- [dependencies](./dependencies.md) - vendored vs system libs, lazy deps, pinning
+- [codegen](./codegen.md) - generating zig source at build time
+- [cross-compilation](./cross-compilation.md) - targeting multiple platforms

languages/ziglang/build/codegen.md

···
+# code generation
+
+generating zig source at build time - for help text, unicode tables, bindings, anything derived from data.
+
+## the pattern
+
+build an executable, run it, capture output, import as zig source:
+
+```zig
+// 1. build the generator (always for host, not target)
+const gen_exe = b.addExecutable(.{
+    .name = "helpgen",
+    .root_module = b.createModule(.{
+        .root_source_file = b.path("src/helpgen.zig"),
+        .target = b.graph.host,  // runs on build machine
+    }),
+});
+
+// 2. run it and capture stdout
+const gen_run = b.addRunArtifact(gen_exe);
+const gen_output = gen_run.captureStdOut();
+
+// 3. make it available as an import
+step.root_module.addAnonymousImport("help_strings", .{
+    .root_source_file = gen_output,
+});
+```
+
+now your code can `@import("help_strings")` and get the generated content.
+
+## why `.target = b.graph.host`
+
+the generator runs during the build, on your machine. even if you're cross-compiling to arm64-linux, the generator needs to run on your x86-macos (or whatever you're building from).
+
+`b.graph.host` gives you the host target - the machine running the build.
+
+## writing to files instead
+
+if you need the output as a file (not just an import):
+
+```zig
+const wf = b.addWriteFiles();
+const output_path = wf.addCopyFile(
+    gen_run.captureStdOut(),
+    "generated.zig",
+);
+// output_path is a LazyPath you can use elsewhere
+```
+
+## custom build steps for external tools
+
+wrap non-zig tools (metal shader compiler, lipo, etc.) as build steps:
+
+```zig
+pub const MetallibStep = struct {
+    step: std.Build.Step,
+    output: std.Build.LazyPath,
+
+    pub fn create(b: *std.Build, shader_source: []const u8) *MetallibStep {
+        const run = b.addSystemCommand(&.{
+            "/usr/bin/xcrun", "-sdk", "macosx", "metal",
+            "-c", "-o",
+        });
+        const ir_output = run.addOutputFileArg("shader.ir");
+        run.addFileArg(b.path(shader_source));
+
+        // chain another command for metallib...
+        const self = b.allocator.create(MetallibStep) catch @panic("OOM");
+        self.* = .{
+            .step = std.Build.Step.init(.{ ... }),
+            .output = ir_output,
+        };
+        return self;
+    }
+};
+```
+
+key points:
+- `addOutputFileArg()` creates a LazyPath for the output
+- `addFileArg()` adds a dependency on an input file
+- proper dependency tracking means the step reruns when inputs change
+
+## conditional embedding
+
+bun embeds javascript runtime code in release builds but loads from disk in debug:
+
+```zig
+pub fn shouldEmbedCode(opts: *const BuildOptions) bool {
+    return opts.optimize != .Debug or opts.force_embed;
+}
+```
+
+debug builds iterate faster (no recompile to change js). release builds are self-contained.
+
+sources:
+- [ghostty/src/build/HelpStrings.zig](https://github.com/ghostty-org/ghostty/blob/main/src/build/HelpStrings.zig)
+- [ghostty/src/build/MetallibStep.zig](https://github.com/ghostty-org/ghostty/blob/main/src/build/MetallibStep.zig)

languages/ziglang/build/cross-compilation.md

···
+# cross-compilation
+
+building for platforms other than the one you're on. zig makes this unusually easy, but there are still patterns to know.
+
+## basic cross-compilation
+
+zig can target any platform from any platform:
+
+```zig
+const target = b.standardTargetOptions(.{});  // from -Dtarget=...
+```
+
+user runs: `zig build -Dtarget=aarch64-linux-gnu`
+
+that's it for pure zig. c dependencies complicate things.
+
+## cpu targeting
+
+bun explicitly sets cpu models per platform:
+
+```zig
+pub fn getCpuModel(os: OperatingSystem, arch: Arch) ?Target.Query.CpuModel {
+    if (os == .linux and arch == .aarch64) {
+        return .{ .explicit = &Target.aarch64.cpu.cortex_a35 };
+    }
+    if (os == .mac and arch == .aarch64) {
+        return .{ .explicit = &Target.aarch64.cpu.apple_m1 };
+    }
+    // x86_64 defaults to haswell for avx2
+    return null;
+}
+```
+
+and offers a "baseline" mode for maximum compatibility:
+
+```zig
+if (opts.baseline) {
+    // target nehalem (~2008) instead of haswell (~2013)
+    return .{ .explicit = &Target.x86_64.cpu.nehalem };
+}
+```
+
+baseline builds run on older hardware but miss avx2 optimizations.
+
+## glibc version
+
+linux binaries link against glibc. if you build against glibc 2.34, it won't run on systems with glibc 2.17.
+
+```zig
+pub fn getOSGlibCVersion(os: OperatingSystem) ?Version {
+    return switch (os) {
+        .linux => .{ .major = 2, .minor = 26, .patch = 0 },
+        else => null,
+    };
+}
+```
+
+bun targets glibc 2.26 (from ~2017) for broad compatibility.
+
+## macos universal binaries
+
+ghostty builds for both x86_64 and aarch64, then combines with lipo:
+
+```zig
+// build for both architectures
+const x86_lib = try buildLib(b, deps.retarget(b, x86_64_macos));
+const arm_lib = try buildLib(b, deps.retarget(b, aarch64_macos));
+
+// combine into universal binary
+const lipo_step = LipoStep.create(b, .{
+    .input_a = x86_lib.getEmittedBin(),
+    .input_b = arm_lib.getEmittedBin(),
+    .out_name = "libghostty.a",
+});
+```
+
+the `deps.retarget()` pattern creates a copy of SharedDeps pointing at a different target.
+
+## xcframework for apple platforms
+
+for ios apps, you need an xcframework containing:
+- macos universal (x86_64 + arm64)
+- ios arm64
+- ios simulator (arm64 + x86_64)
+
+```zig
+const macos = try buildMacOSUniversal(b, deps);
+const ios = try buildLib(b, deps.retarget(b, .{ .os_tag = .ios, .cpu_arch = .aarch64 }));
+const ios_sim = try buildLib(b, deps.retarget(b, .{ .os_tag = .ios, .abi = .simulator }));
+
+// xcodebuild -create-xcframework ...
+```
+
+## minimum os versions
+
+centralize version requirements:
+
+```zig
+pub fn osVersionMin(os: std.Target.Os.Tag) std.Target.Os.SemVer {
+    return switch (os) {
+        .macos => .{ .major = 13, .minor = 0, .patch = 0 },
+        .ios => .{ .major = 17, .minor = 0, .patch = 0 },
+        else => .{ .major = 0, .minor = 0, .patch = 0 },
+    };
+}
+```
+
+apply when creating targets:
+
+```zig
+const target = b.resolveTargetQuery(.{
+    .os_tag = .macos,
+    .os_version_min = Config.osVersionMin(.macos),
+});
+```
+
+## environment detection
+
+helpful warnings for common mistakes:
+
+```zig
+fn checkNixShell(exe: *std.Build.Step.Compile, cfg: *const Config) !void {
+    std.fs.accessAbsolute("/etc/NIXOS", .{}) catch return;  // not nixos
+    if (cfg.env.get("IN_NIX_SHELL") != null) return;  // in nix shell, good
+
+    try exe.step.addError(
+        "Building on NixOS outside nix shell. " ++
+        "Use: nix develop -c zig build",
+        .{},
+    );
+}
+```
+
+sources:
+- [ghostty/src/build/GhosttyLib.zig](https://github.com/ghostty-org/ghostty/blob/main/src/build/GhosttyLib.zig)
+- [bun/build.zig](https://github.com/oven-sh/bun/blob/main/build.zig)

languages/ziglang/build/dependencies.md

···
+# dependencies
+
+managing external code - when to vendor, when to use system libs, how to keep things reproducible.
+
+## lazy dependencies
+
+dependencies marked `.lazy = true` in build.zig.zon are only fetched when actually used:
+
+```zig
+// build.zig.zon
+.dependencies = .{
+    .harfbuzz = .{ .path = "./pkg/harfbuzz", .lazy = true },
+    .macos = .{ .path = "./pkg/macos", .lazy = true },
+},
+```
+
+```zig
+// build.zig
+if (b.lazyDependency("harfbuzz", .{ .target = target })) |dep| {
+    step.linkLibrary(dep.artifact("harfbuzz"));
+}
+```
+
+why: platform-specific deps (like `macos`) don't slow down linux builds. optional features don't fetch deps when disabled.
+
+## vendored vs system libraries
+
+ghostty supports both - vendored for reproducibility, system for distro integration:
+
+```zig
+if (b.systemIntegrationOption("freetype", .{})) {
+    step.linkSystemLibrary2("freetype2", .{});
+} else {
+    step.linkLibrary(freetype_dep.artifact("freetype"));
+}
+```
+
+with smart defaults:
+
+```zig
+_ = b.systemIntegrationOption("freetype", .{
+    .default = if (target.result.os.tag.isDarwin()) false else null,
+});
+```
+
+macos defaults to vendored (for universal binaries). linux defaults to "ask pkg-config".
+
+users override with `-Dsystem-freetype=true` or `-Dsystem-freetype=false`.
+
+## c library wrappers
+
+each c dependency gets its own package with a build.zig:
+
+```
+pkg/
+├── freetype/
+│   ├── build.zig      # builds the C library
+│   ├── build.zig.zon  # declares the package
+│   └── main.zig       # zig bindings
+├── harfbuzz/
+└── libpng/
+```
+
+the wrapper handles:
+- platform-specific source file selection
+- compiler flags for c code
+- exposing a zig module with bindings
+
+## pinning for reproducibility
+
+bun pins every dependency to exact git commits:
+
+```cmake
+register_repository(
+  NAME boringssl
+  REPOSITORY oven-sh/boringssl
+  COMMIT f1ffd9e83d4f5c28a9c70d73f9a4e6fcf310062f
+)
+```
+
+and forks dependencies to their own org (`oven-sh/boringssl`). no surprise breakage from upstream.
+
+in zig terms, this means using `.hash` in build.zig.zon and avoiding `.url` pointing to `master` branches.
+
+## detecting what's installed
+
+before defaulting to system libs, check what's available:
+
+```zig
+pub fn gtkTargets(b: *std.Build) struct { x11: bool, wayland: bool } {
+    var code: u8 = undefined;
+    const output = b.runAllowFail(
+        &.{ "pkg-config", "--variable=targets", "gtk4" },
+        &code,
+        .Ignore,
+    ) catch return .{ .x11 = false, .wayland = false };
+
+    return .{
+        .x11 = std.mem.indexOf(u8, output, "x11") != null,
+        .wayland = std.mem.indexOf(u8, output, "wayland") != null,
+    };
+}
+```
+
+fails gracefully when pkg-config isn't available.
+
+sources:
+- [ghostty/build.zig.zon](https://github.com/ghostty-org/ghostty/blob/main/build.zig.zon)
+- [ghostty/pkg/](https://github.com/ghostty-org/ghostty/tree/main/pkg)

languages/ziglang/build/organization.md

···
+# build organization
+
+as projects grow, a single `build.zig` becomes unwieldy. ghostty's solution: treat build logic as a package.
+
+## the pattern
+
+instead of one giant build.zig, create `src/build/` as a zig package:
+
+```
+src/build/
+├── main.zig          # exports everything
+├── Config.zig        # all -D options in one struct
+├── SharedDeps.zig    # dependency wiring
+├── GhosttyExe.zig    # executable-specific logic
+├── GhosttyLib.zig    # library-specific logic
+└── steps/            # custom build steps
+```
+
+the root `build.zig` becomes a thin shell:
+
+```zig
+const buildpkg = @import("src/build/main.zig");
+
+pub fn build(b: *std.Build) !void {
+    const config = buildpkg.Config.fromOptions(b);
+    const deps = try buildpkg.SharedDeps.init(b, &config);
+
+    if (config.emit_exe) {
+        _ = try buildpkg.GhosttyExe.init(b, &deps);
+    }
+    if (config.emit_lib) {
+        _ = try buildpkg.GhosttyLib.init(b, &deps);
+    }
+}
+```
+
+## centralized configuration
+
+all `-D` options live in one struct. this makes them discoverable and passable:
+
+```zig
+// Config.zig
+pub const Config = @This();
+
+// features
+x11: bool = false,
+wayland: bool = false,
+sentry: bool = true,
+
+// artifacts to emit
+emit_exe: bool = false,
+emit_lib: bool = false,
+emit_docs: bool = false,
+
+pub fn fromOptions(b: *std.Build) Config {
+    return .{
+        .x11 = b.option(bool, "x11", "Enable X11") orelse false,
+        .wayland = b.option(bool, "wayland", "Enable Wayland") orelse false,
+        // ...
+    };
+}
+
+// export to comptime for runtime introspection
+pub fn addOptions(self: *const Config, step: *std.Build.Step.Compile) void {
+    const opts = step.root_module.addOptions();
+    opts.addOption(bool, "x11", self.x11);
+    opts.addOption(bool, "wayland", self.wayland);
+    // now @import("build_options").x11 works in source
+}
+```
+
+## shared dependencies
+
+avoid duplicating dependency wiring across artifacts:
+
+```zig
+// SharedDeps.zig
+pub const SharedDeps = @This();
+
+config: *const Config,
+freetype: *std.Build.Dependency,
+harfbuzz: *std.Build.Dependency,
+
+pub fn add(self: *const SharedDeps, step: *std.Build.Step.Compile) void {
+    step.linkLibrary(self.freetype.artifact("freetype"));
+    step.linkLibrary(self.harfbuzz.artifact("harfbuzz"));
+    // add all the deps once, use everywhere
+}
+```
+
+now both `GhosttyExe` and `GhosttyLib` just call `deps.add(step)`.
+
+## when to split
+
+small projects don't need this. consider splitting when:
+- build.zig exceeds ~500 lines
+- you have multiple artifacts (exe, lib, tests) sharing deps
+- platform-specific logic is getting tangled
+- you want to test build logic itself
+
+source: [ghostty/src/build/](https://github.com/ghostty-org/ghostty/tree/main/src/build)