build: mark most dependencies as lazy

Lazy dependencies are only fetched if the build script would actually
reach a usage of that dependency at runtime (when the `lazyDependency`
function is called). This can save a lot of network traffic, disk uage,
and time because we don't have to fetch and build dependencies that we
don't actually need.

Prior to this commit, Ghostty fetched almost everything for all
platforms and configurations all the time. This commit reverses that to
fetching almost nothing until it's actually needed.

There are very little downsides to doing this[1]. One downside is `zig
build --fetch` doesn't fetch lazy dependencies, but we don't rely on
this command for packaging and suggest using our custom shell script
that downloads a cached list of URLs (`build.zig.zon.txt`).

This commit doesn't cover 100% of dependencies, since some provide no
benefit to make lazy while the complexity to make them lazy is higher
(in code style typically).

Conversely, some simple dependencies are marked lazy even if they're
almost always needed if they don't introduce any real complexity to the
code, because there is very little downside to do so.

[1]: https://ziggit.dev/t/lazy-dependencies-best-dependencies/5509/5

Author: mitchellh

build.zig.zon

@@ -10,30 +10,36 @@
             // mitchellh/libxev
             .url = "https://github.com/mitchellh/libxev/archive/3df9337a9e84450a58a2c4af434ec1a036f7b494.tar.gz",
             .hash = "libxev-0.0.0-86vtc-ziEgDbLP0vihUn1MhsxNKY4GJEga6BEr7oyHpz",
+            .lazy = true,
         },
         .vaxis = .{
             // rockorager/libvaxis
             .url = "git+https://github.com/rockorager/libvaxis#1e24e0dfb509e974e1c8713bcd119d0ae032a8c7",
             .hash = "vaxis-0.1.0-BWNV_MHyCAARemSCSwwc3sA1etNgv7ge0BCIXspX6CZv",
+            .lazy = true,
         },
         .z2d = .{
             // vancluever/z2d
             .url = "https://github.com/vancluever/z2d/archive/1e89605a624940c310c7a1d81b46a7c5c05919e3.tar.gz",
             .hash = "z2d-0.6.0-j5P_HvLdCABu-dXpCeRM7Uk4m16vULg1980lMNCQj4_C",
+            .lazy = true,
         },
         .zig_objc = .{
             // mitchellh/zig-objc
             .url = "https://github.com/mitchellh/zig-objc/archive/3ab0d37c7d6b933d6ded1b3a35b6b60f05590a98.tar.gz",
             .hash = "zig_objc-0.0.0-Ir_Sp3TyAADEVRTxXlScq3t_uKAM91MYNerZkHfbD0yt",
+            .lazy = true,
         },
         .zig_js = .{
             // mitchellh/zig-js
             .url = "https://deps.files.ghostty.org/zig_js-12205a66d423259567764fa0fc60c82be35365c21aeb76c5a7dc99698401f4f6fefc.tar.gz",
             .hash = "N-V-__8AAB9YCQBaZtQjJZVndk-g_GDIK-NTZcIa63bFp9yZ",
+            .lazy = true,
         },
         .ziglyph = .{
             .url = "https://deps.files.ghostty.org/ziglyph-b89d43d1e3fb01b6074bc1f7fc980324b04d26a5.tar.gz",
             .hash = "ziglyph-0.11.2-AAAAAHPtHwB4Mbzn1KvOV7Wpjo82NYEc_v0WC8oCLrkf",
+            .lazy = true,
         },
         .zig_wayland = .{
             // codeberg ifreund/zig-wayland
@@ -44,56 +50,62 @@
             // natecraddock/zf
             .url = "https://github.com/natecraddock/zf/archive/03176fcf23fda543cc02a8675e92c1fe3b1ee2eb.tar.gz",
             .hash = "zf-0.10.3-OIRy8bKIAACV6JaNNncXA68Nw2BUAD9JVfQdzjyoZQ-J",
+            .lazy = true,
         },
         .gobject = .{
             // https://github.com/jcollie/ghostty-gobject based on zig_gobject
             // Temporary until we generate them at build time automatically.
             .url = "https://github.com/jcollie/ghostty-gobject/releases/download/0.14.0-2025-03-11-16-1/ghostty-gobject-0.14.0-2025-03-11-16-1.tar.gz",
             .hash = "gobject-0.2.0-Skun7H6DlQDWCiNQtdE5TXYcCvx7MyjW01OQe5M_n_jV",
+            .lazy = true,
         },
 
         // C libs
-        .cimgui = .{ .path = "./pkg/cimgui" },
-        .fontconfig = .{ .path = "./pkg/fontconfig" },
-        .freetype = .{ .path = "./pkg/freetype" },
-        .glfw = .{ .path = "./pkg/glfw" },
-        .gtk4_layer_shell = .{ .path = "./pkg/gtk4-layer-shell" },
-        .harfbuzz = .{ .path = "./pkg/harfbuzz" },
-        .highway = .{ .path = "./pkg/highway" },
-        .libintl = .{ .path = "./pkg/libintl" },
-        .libpng = .{ .path = "./pkg/libpng" },
-        .macos = .{ .path = "./pkg/macos" },
-        .oniguruma = .{ .path = "./pkg/oniguruma" },
-        .opengl = .{ .path = "./pkg/opengl" },
-        .sentry = .{ .path = "./pkg/sentry" },
-        .simdutf = .{ .path = "./pkg/simdutf" },
-        .utfcpp = .{ .path = "./pkg/utfcpp" },
-        .wuffs = .{ .path = "./pkg/wuffs" },
-        .zlib = .{ .path = "./pkg/zlib" },
+        .cimgui = .{ .path = "./pkg/cimgui", .lazy = true },
+        .fontconfig = .{ .path = "./pkg/fontconfig", .lazy = true },
+        .freetype = .{ .path = "./pkg/freetype", .lazy = true },
+        .glfw = .{ .path = "./pkg/glfw", .lazy = true },
+        .gtk4_layer_shell = .{ .path = "./pkg/gtk4-layer-shell", .lazy = true },
+        .harfbuzz = .{ .path = "./pkg/harfbuzz", .lazy = true },
+        .highway = .{ .path = "./pkg/highway", .lazy = true },
+        .libintl = .{ .path = "./pkg/libintl", .lazy = true },
+        .libpng = .{ .path = "./pkg/libpng", .lazy = true },
+        .macos = .{ .path = "./pkg/macos", .lazy = true },
+        .oniguruma = .{ .path = "./pkg/oniguruma", .lazy = true },
+        .opengl = .{ .path = "./pkg/opengl", .lazy = true },
+        .sentry = .{ .path = "./pkg/sentry", .lazy = true },
+        .simdutf = .{ .path = "./pkg/simdutf", .lazy = true },
+        .utfcpp = .{ .path = "./pkg/utfcpp", .lazy = true },
+        .wuffs = .{ .path = "./pkg/wuffs", .lazy = true },
+        .zlib = .{ .path = "./pkg/zlib", .lazy = true },
 
         // Shader translation
-        .glslang = .{ .path = "./pkg/glslang" },
-        .spirv_cross = .{ .path = "./pkg/spirv-cross" },
+        .glslang = .{ .path = "./pkg/glslang", .lazy = true },
+        .spirv_cross = .{ .path = "./pkg/spirv-cross", .lazy = true },
 
         // Wayland
         .wayland = .{
             .url = "https://deps.files.ghostty.org/wayland-9cb3d7aa9dc995ffafdbdef7ab86a949d0fb0e7d.tar.gz",
             .hash = "N-V-__8AAKrHGAAs2shYq8UkE6bGcR1QJtLTyOE_lcosMn6t",
+            .lazy = true,
         },
         .wayland_protocols = .{
             .url = "https://deps.files.ghostty.org/wayland-protocols-258d8f88f2c8c25a830c6316f87d23ce1a0f12d9.tar.gz",
             .hash = "N-V-__8AAKw-DAAaV8bOAAGqA0-oD7o-HNIlPFYKRXSPT03S",
+            .lazy = true,
         },
         .plasma_wayland_protocols = .{
             .url = "https://deps.files.ghostty.org/plasma_wayland_protocols-12207e0851c12acdeee0991e893e0132fc87bb763969a585dc16ecca33e88334c566.tar.gz",
             .hash = "N-V-__8AAKYZBAB-CFHBKs3u4JkeiT4BMvyHu3Y5aaWF3Bbs",
+            .lazy = true,
         },
 
         // Other
         .apple_sdk = .{ .path = "./pkg/apple-sdk" },
         .iterm2_themes = .{
             .url = "https://github.com/mbadolato/iTerm2-Color-Schemes/archive/e21d5ffd19605741d0e3e19d7c5a8c6c25648673.tar.gz",
             .hash = "N-V-__8AAABBKARxrVb9mEr7T5TUQbbqPiHxdBoOAmsChg2a",
+            .lazy = true,
         },
     },
 }

pkg/breakpad/build.zig

@@ -4,15 +4,12 @@ pub fn build(b: *std.Build) !void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
 
-    const upstream = b.dependency("breakpad", .{});
-
     const lib = b.addStaticLibrary(.{
         .name = "breakpad",
         .target = target,
         .optimize = optimize,
     });
     lib.linkLibCpp();
-    lib.addIncludePath(upstream.path("src"));
     lib.addIncludePath(b.path("vendor"));
     if (target.result.os.tag.isDarwin()) {
         const apple_sdk = @import("apple_sdk");
@@ -23,67 +20,70 @@ pub fn build(b: *std.Build) !void {
     defer flags.deinit();
     try flags.appendSlice(&.{});
 
-    lib.addCSourceFiles(.{
-        .root = upstream.path(""),
-        .files = common,
-        .flags = flags.items,
-    });
-
-    if (target.result.os.tag.isDarwin()) {
-        lib.addCSourceFiles(.{
-            .root = upstream.path(""),
-            .files = common_apple,
-            .flags = flags.items,
-        });
+    if (b.lazyDependency("breakpad", .{})) |upstream| {
+        lib.addIncludePath(upstream.path("src"));
         lib.addCSourceFiles(.{
             .root = upstream.path(""),
-            .files = client_apple,
+            .files = common,
             .flags = flags.items,
         });
 
-        switch (target.result.os.tag) {
-            .macos => {
-                lib.addCSourceFiles(.{
-                    .root = upstream.path(""),
-                    .files = common_mac,
-                    .flags = flags.items,
-                });
-                lib.addCSourceFiles(.{
+        if (target.result.os.tag.isDarwin()) {
+            lib.addCSourceFiles(.{
+                .root = upstream.path(""),
+                .files = common_apple,
+                .flags = flags.items,
+            });
+            lib.addCSourceFiles(.{
+                .root = upstream.path(""),
+                .files = client_apple,
+                .flags = flags.items,
+            });
+
+            switch (target.result.os.tag) {
+                .macos => {
+                    lib.addCSourceFiles(.{
+                        .root = upstream.path(""),
+                        .files = common_mac,
+                        .flags = flags.items,
+                    });
+                    lib.addCSourceFiles(.{
+                        .root = upstream.path(""),
+                        .files = client_mac,
+                        .flags = flags.items,
+                    });
+                },
+
+                .ios => lib.addCSourceFiles(.{
                     .root = upstream.path(""),
-                    .files = client_mac,
+                    .files = client_ios,
                     .flags = flags.items,
-                });
-            },
+                }),
 
-            .ios => lib.addCSourceFiles(.{
+                else => {},
+            }
+        }
+
+        if (target.result.os.tag == .linux) {
+            lib.addCSourceFiles(.{
                 .root = upstream.path(""),
-                .files = client_ios,
+                .files = common_linux,
                 .flags = flags.items,
-            }),
-
-            else => {},
+            });
+            lib.addCSourceFiles(.{
+                .root = upstream.path(""),
+                .files = client_linux,
+                .flags = flags.items,
+            });
         }
-    }
 
-    if (target.result.os.tag == .linux) {
-        lib.addCSourceFiles(.{
-            .root = upstream.path(""),
-            .files = common_linux,
-            .flags = flags.items,
-        });
-        lib.addCSourceFiles(.{
-            .root = upstream.path(""),
-            .files = client_linux,
-            .flags = flags.items,
-        });
+        lib.installHeadersDirectory(
+            upstream.path("src"),
+            "",
+            .{ .include_extensions = &.{".h"} },
+        );
     }
 
-    lib.installHeadersDirectory(
-        upstream.path("src"),
-        "",
-        .{ .include_extensions = &.{".h"} },
-    );
-
     b.installArtifact(lib);
 }
 

pkg/breakpad/build.zig.zon

@@ -7,6 +7,7 @@
         .breakpad = .{
             .url = "https://deps.files.ghostty.org/breakpad-b99f444ba5f6b98cac261cbb391d8766b34a5918.tar.gz",
             .hash = "N-V-__8AALw2uwF_03u4JRkZwRLc3Y9hakkYV7NKRR9-RIZJ",
+            .lazy = true,
         },
 
         .apple_sdk = .{ .path = "../apple-sdk" },

pkg/cimgui/build.zig

@@ -40,7 +40,13 @@ pub fn build(b: *std.Build) !void {
             .@"enable-libpng" = true,
         });
         lib.linkLibrary(freetype.artifact("freetype"));
-        module.addIncludePath(freetype.builder.dependency("freetype", .{}).path("include"));
+
+        if (freetype.builder.lazyDependency(
+            "freetype",
+            .{},
+        )) |freetype_dep| {
+            module.addIncludePath(freetype_dep.path("include"));
+        }
     }
 
     lib.addIncludePath(imgui.path(""));

pkg/fontconfig/build.zig

@@ -64,7 +64,6 @@ fn buildLib(b: *std.Build, module: *std.Build.Module, options: anytype) !*std.Bu
     const libxml2_iconv_enabled = options.libxml2_iconv_enabled;
     const freetype_enabled = options.freetype_enabled;
 
-    const upstream = b.dependency("fontconfig", .{});
     const lib = b.addStaticLibrary(.{
         .name = "fontconfig",
         .target = target,
@@ -75,9 +74,7 @@ fn buildLib(b: *std.Build, module: *std.Build.Module, options: anytype) !*std.Bu
         lib.linkSystemLibrary("pthread");
     }
 
-    lib.addIncludePath(upstream.path(""));
     lib.addIncludePath(b.path("override/include"));
-    module.addIncludePath(upstream.path(""));
     module.addIncludePath(b.path("override/include"));
 
     var flags = std.ArrayList([]const u8).init(b.allocator);
@@ -188,11 +185,12 @@ fn buildLib(b: *std.Build, module: *std.Build.Module, options: anytype) !*std.Bu
         if (b.systemIntegrationOption("freetype", .{})) {
             lib.linkSystemLibrary2("freetype2", dynamic_link_opts);
         } else {
-            const freetype_dep = b.dependency(
+            if (b.lazyDependency(
                 "freetype",
                 .{ .target = target, .optimize = optimize },
-            );
-            lib.linkLibrary(freetype_dep.artifact("freetype"));
+            )) |freetype_dep| {
+                lib.linkLibrary(freetype_dep.artifact("freetype"));
+            }
         }
     }
 
@@ -214,26 +212,31 @@ fn buildLib(b: *std.Build, module: *std.Build.Module, options: anytype) !*std.Bu
         if (b.systemIntegrationOption("libxml2", .{})) {
             lib.linkSystemLibrary2("libxml-2.0", dynamic_link_opts);
         } else {
-            const libxml2_dep = b.dependency("libxml2", .{
+            if (b.lazyDependency("libxml2", .{
                 .target = target,
                 .optimize = optimize,
                 .iconv = libxml2_iconv_enabled,
-            });
-            lib.linkLibrary(libxml2_dep.artifact("xml2"));
+            })) |libxml2_dep| {
+                lib.linkLibrary(libxml2_dep.artifact("xml2"));
+            }
         }
     }
 
-    lib.addCSourceFiles(.{
-        .root = upstream.path(""),
-        .files = srcs,
-        .flags = flags.items,
-    });
+    if (b.lazyDependency("fontconfig", .{})) |upstream| {
+        lib.addIncludePath(upstream.path(""));
+        module.addIncludePath(upstream.path(""));
+        lib.addCSourceFiles(.{
+            .root = upstream.path(""),
+            .files = srcs,
+            .flags = flags.items,
+        });
 
-    lib.installHeadersDirectory(
-        upstream.path("fontconfig"),
-        "fontconfig",
-        .{ .include_extensions = &.{".h"} },
-    );
+        lib.installHeadersDirectory(
+            upstream.path("fontconfig"),
+            "fontconfig",
+            .{ .include_extensions = &.{".h"} },
+        );
+    }
 
     b.installArtifact(lib);
 

pkg/fontconfig/build.zig.zon

@@ -7,9 +7,10 @@
         .fontconfig = .{
             .url = "https://deps.files.ghostty.org/fontconfig-2.14.2.tar.gz",
             .hash = "N-V-__8AAIrfdwARSa-zMmxWwFuwpXf1T3asIN7s5jqi9c1v",
+            .lazy = true,
         },
 
-        .freetype = .{ .path = "../freetype" },
-        .libxml2 = .{ .path = "../libxml2" },
+        .freetype = .{ .path = "../freetype", .lazy = true },
+        .libxml2 = .{ .path = "../libxml2", .lazy = true },
     },
 }