summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-06 22:36:07 -0300
committerGabriel Schneider <[email protected]>2026-11-06 23:38:31 -0300
commit227111c84a2945087abb4395daf63c7b23ba5bab (patch)
treefbd17789bdb0feb9cc7739b0bcc443315c5c7336
parent8facd769003b970e7a2c933f1887e09bffb4bd08 (diff)
downloadpardes-227111c84a2945087abb4395daf63c7b23ba5bab.tar.gz
pardes-227111c84a2945087abb4395daf63c7b23ba5bab.zip
kinds #47, MuPDF and FreeType lazy: Zig 0.17's configure is handed the -D options and never the steps asked for (the configurer's argv, and the configure cache keyed on it), so no step can fetch for itself; the guard is `-Dpdf`, on by itself once MuPDF is fetched (std.Build.package_map's `available`) and off Linux, which asks `b.lazyDependency` for MuPDF, and FreeType (with the zlib and libpng it brings) is lazy too and asked by it or a window: a fresh checkout's `zig build -Dplatform=tui` fetches none of them, and without `-Dpdf` the pdf, addons, static, mupdf-check, pdf-harness and bench steps say to add it; building.typ, install.typ and shared-libs.md say so
Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
-rw-r--r--build.zig62
-rw-r--r--build.zig.zon6
-rw-r--r--docs/shared-libs.md9
-rw-r--r--docs/typ/building.typ12
-rw-r--r--docs/typ/install.typ5
5 files changed, 66 insertions, 28 deletions
diff --git a/build.zig b/build.zig
index ab180cc4..4e4d0408 100644
--- a/build.zig
+++ b/build.zig
@@ -455,19 +455,25 @@ pub fn build(b: *std.Build) void {
.root_source_file = b.path("src/c_heap.zig"),
});
+ // MuPDF, and the FreeType and zlib it is built against, are lazy: a
+ // build asks for them only when it builds the pdf addon (or a window,
+ // FreeType). Zig 0.17's configure is told the -D options and never the
+ // steps asked for, so "the pdf step's" is an option, on once MuPDF is
+ // fetched (and off Linux, where the addons are compiled in): a fresh
+ // checkout's plain build fetches none of the three, and -Dpdf fetches
+ // MuPDF once.
+ const pdf = b.option(bool, "pdf", "build the pdf addon over MuPDF (default: on once MuPDF is fetched, as -Dpdf does)") orelse
+ (std.Build.package_map.get(zon.dependencies.mupdf.hash).?.available or target.result.os.tag != .linux);
+ const mupdf_dep = if (pdf) b.lazyDependency("mupdf", .{}) else null;
// One FreeType in a binary: the gui's glyph atlas links it and MuPDF is
// built against it (see mupdf.zig). At c_optimize with the rest of the
// vendored C, since MuPDF rasterizes a PDF's text through it.
- const freetype_dep = b.dependency("freetype", .{
+ const freetype_dep = if (pdf or also_gui or platform == .gui) b.lazyDependency("freetype", .{
.target = target,
.optimize = c_optimize,
.@"enable-libpng" = false,
- });
- const freetype = freetype_dep.artifact("freetype");
- // ...and one zlib, the one FreeType links for its gzip module. Asked of
- // FreeType's build with the options it asks with, the dependency cache
- // hands back that same artifact rather than a second copy.
- const zlib = freetype_dep.builder.dependency("zlib", .{ .target = target, .optimize = c_optimize }).artifact("z");
+ }) else null;
+ const freetype = if (freetype_dep) |d| d.artifact("freetype") else null;
// The kinds' C ABI (src/kinds/pardes_addon.h), translated once: the core's
// records are the header's, never a mirror of it.
@@ -476,21 +482,24 @@ pub fn build(b: *std.Build) void {
const addon_mod = b.createModule(.{ .root_source_file = b.path("src/kinds/addon.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "pardes_addon", .module = kind_mod }} });
// The PDF addon (addons/pdf/pdf.zig over MuPDF through pdf_bridge.c), built
// and installed as the image addon is: compiled only for a step that
- // needs it (`pdf`, the tests), though fetched at the first configure,
- // which Zig runs alike for every step. MuPDF is compiled against the
- // build's FreeType and zlib and links them into the library, which holds
- // its own copy of each beside a window's FreeType (docs/shared-libs.md);
- // so all three are position-independent, and the library exports its
+ // needs it (`pdf`, the tests). MuPDF is compiled against the build's
+ // FreeType and zlib and links them into the library, which holds its
+ // own copy of each beside a window's FreeType (docs/shared-libs.md); so
+ // all three are position-independent, and the library exports its
// `pardes_addon` alone.
var pdf_addon: ?*std.Build.Step.Compile = null;
- if (b.lazyDependency("mupdf", .{})) |mupdf_dep| {
- freetype.root_module.pic = true;
+ if (mupdf_dep) |md| if (freetype_dep) |fd| {
+ // ...and one zlib, the one FreeType links for its gzip module. Asked
+ // of FreeType's build with the options it asks with, the dependency
+ // cache hands back that same artifact rather than a second copy.
+ const zlib = fd.builder.dependency("zlib", .{ .target = target, .optimize = c_optimize }).artifact("z");
+ freetype.?.root_module.pic = true;
zlib.root_module.pic = true;
- const mupdf = mupdf_build.add(b, io, mupdf_dep, .{
+ const mupdf = mupdf_build.add(b, io, md, .{
.target = target,
.optimize = c_optimize,
.jpx = enable_jpx,
- .freetype = freetype,
+ .freetype = freetype.?,
.zlib = zlib,
.pic = true,
});
@@ -529,7 +538,10 @@ pub fn build(b: *std.Build) void {
run.setCwd(b.path("."));
bench.step.dependOn(&run.step);
}
- }
+ };
+ // Without it, what needs it says how to have it.
+ const no_pdf: ?*std.Build.Step = if (pdf_addon == null) &b.addFail("this step needs the pdf addon, over MuPDF: add -Dpdf (it is fetched once, and on from then)").step else null;
+ if (no_pdf) |s| for ([_]*std.Build.Step{ mupdf_check, pdf_pointer_bench_step, pdf_scroll_bench_step }) |step| step.dependOn(s);
const uucode_config = b.path("uucode_config.zig");
const uucode_tables = b.dependency("uucode", .{
@@ -918,7 +930,8 @@ pub fn build(b: *std.Build) void {
gui_c.addIncludePath(b.path("src/gui"));
gm.addImport("gui_c", gui_c.createModule());
}
- gm.linkLibrary(freetype);
+ const ft = freetype orelse continue;
+ gm.linkLibrary(ft);
// HarfBuzz from source, like FreeType: its FreeType integration
// (HAVE_FREETYPE, hb-ft) links the freetype artifact above, so the two
// share one FreeType. The flags are the ones Ghostty builds it with,
@@ -935,7 +948,7 @@ pub fn build(b: *std.Build) void {
.link_libcpp = true,
}),
});
- harfbuzz.root_module.linkLibrary(freetype);
+ harfbuzz.root_module.linkLibrary(ft);
harfbuzz.root_module.addIncludePath(upstream.path("src"));
harfbuzz.root_module.addCSourceFile(.{
.file = upstream.path("src/harfbuzz.cc"),
@@ -1151,7 +1164,10 @@ pub fn build(b: *std.Build) void {
for ([_]?*std.Build.Step.Compile{ image_addon, pdf_addon }, [_][]const u8{ "image", "pdf" }) |lib, name| {
const step = b.step(name, b.fmt("install the {s} addon, <prefix>/lib/pardes/addons/{s}.so", .{ name, name }));
addons_step.dependOn(step);
- const l = lib orelse continue;
+ const l = lib orelse {
+ step.dependOn(no_pdf.?);
+ continue;
+ };
step.dependOn(&b.addInstallFileWithDir(l.getEmittedBin(), .lib, b.fmt("pardes/addons/{s}.so", .{name})).step);
if (home_bin) |dir| {
const copy = b.addSystemCommand(&.{ "install", "-Dm755" });
@@ -1176,7 +1192,7 @@ pub fn build(b: *std.Build) void {
// also how a build for macOS, whose loader has no memfd, could have
// image and PDF panes.
const static_step = b.step("static", "a pardes with the image and pdf addons in it: the terminal's static (-Dplatform=tui -Dtarget=x86_64-linux-musl), the gui's dynamic (-Dplatform=gui)");
- if (static_mod) |m|
+ if (no_pdf) |s| static_step.dependOn(s) else if (static_mod) |m|
static_step.dependOn(&b.addInstallArtifact(b.addExecutable(.{ .name = exe_name, .linkage = if (platform == .gui) null else static_linkage, .root_module = m }), .{}).step)
else
static_step.dependOn(&b.addFail("static is the terminal's on musl (-Dplatform=tui -Dtarget=x86_64-linux-musl) or the gui's (-Dplatform=gui)").step);
@@ -1194,7 +1210,7 @@ pub fn build(b: *std.Build) void {
iso_step.dependOn(&run_iso.step);
}
- const addons: []const *std.Build.Step.Compile = if (pdf_addon) |pdf| b.allocator.dupe(*std.Build.Step.Compile, &.{ image_addon, pdf }) catch @panic("OOM") else &.{image_addon};
+ const addons: []const *std.Build.Step.Compile = if (pdf_addon) |l| b.allocator.dupe(*std.Build.Step.Compile, &.{ image_addon, l }) catch @panic("OOM") else &.{image_addon};
snap_build.addTty(b, .{
.exe = exe,
.addons = addons,
@@ -1261,7 +1277,7 @@ pub fn build(b: *std.Build) void {
b.step("kitty-harness", "kitty graphics through a terminal pane end to end (a client inside, a kitty terminal or the GPU capture outside)").dependOn(&run_kitty_harness.step);
const pdf_harness_step = b.step("pdf-harness", "exercise continuous PDF rendering, search, and sections navigation end to end");
- if (pdf_addon != null) {
+ if (no_pdf) |s| pdf_harness_step.dependOn(s) else {
const run_pdf_harness = b.addRunArtifact(image_harness);
run_pdf_harness.addArtifactArg(exe);
run_pdf_harness.addArtifactArg(image_addon);
diff --git a/build.zig.zon b/build.zig.zon
index c79bd483..23efe9d0 100644
--- a/build.zig.zon
+++ b/build.zig.zon
@@ -171,16 +171,20 @@
.url = "git+https://github.com/mnemnion/mvzr#3efcfe339bd32e122c36b8f1db25b237f93a7ec2",
.hash = "mvzr-0.3.9-ZSOky6t2AQCA7efmm5EYbPb5sOdbXa4EFsUgYbQ6hZv9",
},
+ // MuPDF for the pdf addon (mupdf.zig). Lazy: -Dpdf fetches it, once.
.mupdf = .{
.url = "https://mupdf.com/downloads/archive/mupdf-1.27.0-source.tar.gz",
.hash = "N-V-__8AAAa9gQo4C4cIEpZfRqQLBv-ZnRIB4NQqsMOy8bNx",
.lazy = true,
},
// FreeType's native/light hinter and grayscale rasterizer for the SDL
- // glyph atlas. Added with `zig fetch --save=freetype` and pinned.
+ // glyph atlas, and the one MuPDF is built against. Added with `zig
+ // fetch --save=freetype` and pinned. Lazy: a window or the pdf addon
+ // fetches it (and the zlib and libpng it brings).
.freetype = .{
.url = "git+https://github.com/allyourcodebase/freetype#884fd2235e6ae1ec4306eda30b3259f20930ed2e",
.hash = "freetype-2.14.3-C3-WdXSKAAB-kHs4qgRoeoFnRkNQn6M_SSlUGZ6ywgBQ",
+ .lazy = true,
},
// HarfBuzz shapes the SDL shell's text runs, which is what turns `->`
// into a font's arrow ligature. The upstream source release (the same
diff --git a/docs/shared-libs.md b/docs/shared-libs.md
index b9f64fdf..f6031a0d 100644
--- a/docs/shared-libs.md
+++ b/docs/shared-libs.md
@@ -29,6 +29,15 @@ pdf` (or `zig build addons`, both) builds and installs each library in
home install). MuPDF is compiled only for a step that needs it (`pdf`, the
tests); `-Dmupdf` is gone.
+Since 2026-11-07 MuPDF, and FreeType with the zlib and libpng it brings,
+are lazy dependencies: a build fetches MuPDF only with `-Dpdf` (on by
+itself once MuPDF is fetched, and off Linux), and FreeType only for it or a
+window, so a fresh checkout's `zig build -Dplatform=tui` downloads none of
+them. Zig 0.17's configure is handed the options and never the steps, so
+the guard is that option, not the step: without it `pdf`, `addons`,
+`static`, `mupdf-check`, `pdf-harness` and the PDF benches say to add
+`-Dpdf`, and the tests leave their PDF cases out.
+
## One static pardes (2026-11-06)
`zig build static -Dplatform=tui -Dtarget=x86_64-linux-musl` links the
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index 8520fbbf..151d4b3f 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -14,8 +14,15 @@ fetched and pinned by the manifest; the terminal build needs no system
package. The SDL shell builds SDL3 and FreeType from source. Pictures and
PDFs are addons, each its own step: `zig build image`, `zig build pdf`
(`pdf.so`, over MuPDF, its own FreeType and zlib in it), or `zig build
-addons` for both; the binaries hold neither, and MuPDF is compiled only
-for the `pdf` step and the tests.
+addons` for both; the binaries hold neither. MuPDF, and the FreeType and
+zlib the terminal build takes only for it, are lazy: a build fetches them
+only with `-Dpdf`, which is on by itself once MuPDF is fetched, so a fresh
+checkout's `zig build -Dplatform=tui` downloads none of them, and its
+first `zig build pdf -Dpdf` (or `addons`, `static`, `mupdf-check`, a PDF
+bench) fetches MuPDF once; without it those steps say to add `-Dpdf`, and
+the tests leave their PDF cases out. (Zig 0.17's configure is handed the
+options and never the steps asked for, so a step cannot fetch for itself.)
+MuPDF is compiled only for the steps and tests that use `pdf.so`.
#pairs(
[`zig build`], [the terminal shell and the SDL window together, *installed into `~/.local/bin`* (`pardes` and `pardes-gui`)],
@@ -41,6 +48,7 @@ must share with its session; `pardes --help` lists every flag.
#pairs(
[`-Dplatform`], [`tui`, `gui`, `macos`; absent: the tui and SDL shells together, installed into `~/.local`],
+ [`-Dpdf`], [bool: build the pdf addon, fetching MuPDF the first time; default on once MuPDF is fetched, and off Linux],
[`-Djpx`], [bool, `true`: JPEG 2000, and with it scanned PDFs],
[`-Dtree-sitter`], [`disabled`, `zig`, `minimal`, `full`; `full`],
[`-Dembed-sources`], [bool, `false`: serve the sources under #file("/src")],
diff --git a/docs/typ/install.typ b/docs/typ/install.typ
index 28ed67c8..9b23669f 100644
--- a/docs/typ/install.typ
+++ b/docs/typ/install.typ
@@ -22,9 +22,10 @@ With Zig 0.17 (the build fetches everything else; once that is
downloaded, a first build from a clean cache took 62 seconds on 16 cores):
#cmd("# pardes, in a terminal\nzig build -Dplatform=tui --prefix ~/.local")
#cmd("# pardes-gui, its own window\nzig build -Dplatform=gui --prefix ~/.local")
-#cmd("# the image and PDF addons (or `zig build image pdf`)\nzig build addons -Dplatform=tui --prefix ~/.local")
+#cmd("# the image and PDF addons (or `zig build image pdf`)\nzig build addons -Dpdf -Dplatform=tui --prefix ~/.local")
Then run `pardes` or `pardes FILE`. The addons are steps of their own:
`lib/pardes/addons/image.so`, the image addon, and
-`lib/pardes/addons/pdf.so`, the PDF addon (over MuPDF), which pardes
+`lib/pardes/addons/pdf.so`, the PDF addon (over MuPDF, which `-Dpdf`
+fetches the first time and every build after takes as fetched), which pardes
loads at start from its prefix; a pardes without them (a downloaded binary
alone) shows image files and PDFs as text.