summaryrefslogtreecommitdiff
path: root/docs/shared-libs.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-30 17:35:06 -0300
committerGabriel Schneider <[email protected]>2026-10-30 17:35:06 -0300
commit6d8da8721141284cf33bb901168b26135893eb86 (patch)
tree791d63401d4e85fbca1d597a8ce0326e70efd545 /docs/shared-libs.md
parentefd43a3a2cf03bb741366331158b368abf9ac583 (diff)
parentbf6810a8f9d6cc82050e7d9c0cfb06358301b574 (diff)
downloadpardes-6d8da8721141284cf33bb901168b26135893eb86.tar.gz
pardes-6d8da8721141284cf33bb901168b26135893eb86.zip
Merge latest upstream into the macOS branch for Zig 0.17
Retain the macOS branch history and local Acme selection color while adopting upstream's current core and platform changes. Pin Zig and ZLS to 0.17.0, and fetch the existing zstbi compatibility commit through upstream after its original fork was removed.
Diffstat (limited to 'docs/shared-libs.md')
-rw-r--r--docs/shared-libs.md120
1 files changed, 120 insertions, 0 deletions
diff --git a/docs/shared-libs.md b/docs/shared-libs.md
new file mode 100644
index 00000000..79f3cdb9
--- /dev/null
+++ b/docs/shared-libs.md
@@ -0,0 +1,120 @@
+# One copy of each library
+
+The policy (2026-09-24):
+
+- **One copy per library in a binary.** When a dependency bundles a library
+ the build also has, a build change makes it use the build's copy. Duplicates
+ link silently: same symbol names, the linker keeps one of each, and the two
+ copies were compiled with different options.
+- **Every C library allocates through a Zig allocator** where it has a hook,
+ so tests run its allocations under the Debug allocator.
+- **Patches to fetched packages are applied in build.zig at build time**, each
+ behind a count-checked anchor (as for vaxis and mvzr), because a fresh fetch
+ would clobber a patch made in zig-pkg.
+- **This file lists what is shared, and where the policy could not be met.**
+
+`zig build shared-libs-check -Dplatform=tty|gui` (it also runs with every
+`unit-test`) reads the linked binary's ELF symbol table. It fails when a family
+the build chose against is linked again: stb_image's PNG, JPEG or inflate
+beside wuffs, a second stb_image, stb_image_write's deflate, a second zlib, or
+a second FreeType (tools/shared_libs_check.zig). It counts static functions
+too, and several functions per family, because a release build inlines some
+of them.
+
+## Inventory (ghostty 1.4.0, 2026-10-28)
+
+Sizes are function bytes in the ReleaseFast symbol tables (`nm -S`). The tty
+and gui columns are the two binaries.
+
+| Job | Implementation | Who uses it | Copies before → after | Bytes before → after (tty / gui) | Allocator |
+|---|---|---|---|---|---|
+| PNG decode | wuffs (ghostty-vt's `pkg/wuffs`) | ghostty-vt; **now pardes's image panes and its kitty `f=100` hook** | 1 → 1 | 35.0 KiB, unchanged (already linked: wuffs's function tables keep its decoders in) | Zig allocator: ghostty's wrapper allocates every work buffer |
+| PNG decode | stb_image (zstbi) | image panes, kitty `f=100` | 1 / 2 → **0** | 17.9 / 25.2 KiB → 0 | removed |
+| PNG and JPEG decode | SDL's private stb_image (`SDL_stb.c`) | `SDL_LoadPNG` and camera MJPEG, which pardes never calls | gui 1 → **0** (`SDL_DISABLE_STB`) | counted in the stb rows; glue 4.9 → 0.6 KiB | (SDL_malloc) |
+| PNG decode | MuPDF's `fz_load_png` (on our zlib) | `fz_new_image_from_buffer` only, which PDF rendering does not call | 1 → 1 | 6.3 KiB | fz allocator |
+| JPEG decode | wuffs | **now image panes** | 1 → 1 | 39.4 KiB, unchanged | Zig allocator |
+| JPEG decode | stb_image | image panes | 1 / 2 → **0** | 18.1 / 38.1 KiB → 0 | removed |
+| JPEG decode | MuPDF's libjpeg | PDF `DCTDecode` | 1 → 1 | 114.9 KiB | fz allocator (MuPDF's memory manager) |
+| GIF, BMP, TGA, PSD, HDR, PIC, PNM | stb_image | image panes | 1 → 1 | 22.3 KiB | Zig allocator (`zstbi.init`) |
+| Image resize | stb_image_resize | image panes (downscale) | 1 → 1 | 28.4 KiB | Zig allocator |
+| Image write (and its deflate) | stb_image_write | nothing | 1 → **0** (patched out of zstbi.c) | 30.6 KiB → 0 | removed |
+| Inflate | zlib (allyourcodebase) | FreeType gzip, MuPDF `FlateDecode` | 1 → 1 (MuPDF links FreeType's, mupdf.zig) | 15.5 + 9.7 + 4.6 KiB | per stream: MuPDF's `fz_zlib_alloc`, FreeType's `FT_Memory` |
+| Inflate | wuffs zlib/deflate | ghostty-vt: kitty `o=z` | 1 → 1 | 17.2 KiB | Zig allocator |
+| Inflate | stb_image's own | stb PNG | 1 / 2 → **0** | 1.1 / 2.3 KiB → 0 (most of it was inlined into the PNG decoder) | removed |
+| Fonts | FreeType (allyourcodebase) | gui glyph atlas, MuPDF (built against it, not its slim bundle) | 1 → 1 | 331 KiB | gui: `ui_malloc` (c_heap); MuPDF's library: `FT_MemoryRec` on fz |
+| Shaping | HarfBuzz 11.0.0 (the tarball ghostty pins) | gui | 1 → 1 | 143 KiB | `hb_*_impl` → `ui_*` |
+| JPEG 2000, JBIG2 | openjpeg, jbig2dec (inside MuPDF) | PDF | 1 → 1 | 66 KiB (jbig2) | `fz_opj_malloc`, `Jbig2Allocator` on fz |
+| Unicode properties | uucode | ghostty-vt, vaxis, pardes: one module (`external_uucode`) | 1 → 1 | | Zig |
+| UTF-8, base64 (SIMD) | simdutf, highway | ghostty-vt | 1 → 1 | 206 KiB (debug) | none: allocates nothing in these paths |
+| Regex | mvzr | pardes | 1 → 1 | 17 KiB | Zig |
+| Parsing | tree-sitter | pardes | 1 → 1 | | `ts_set_allocator` → c_heap |
+| Window, input, GPU | SDL 3.4.18 | gui | 1 → 1 | 1009 KiB | `SDL_SetMemoryFunctions` |
+
+Text section: tty 61,369,343 → 61,294,855 bytes (**−74,488**); gui
+67,336,392 → 67,182,000 bytes (**−154,392**).
+
+## What changed (this change)
+
+- **PNG and JPEG are wuffs's**, the decoders ghostty itself uses. image.zig
+ calls them wherever ghostty-vt is in the build (`wuffs_images`). Each image
+ is sized from its header first: PNG's IHDR, JPEG's first SOF. Other formats,
+ and builds without ghostty-vt (esp32p4, web), stay on stb_image.
+- **zstbi is compiled with `-DSTBI_NO_PNG -DSTBI_NO_JPEG`.** That also drops
+ stb's inflate, which only PNG used. Its `stb_image_write` include is patched
+ out (one count-checked anchor), with a no-op `stbi_flip_vertically_on_write`
+ left for `zstbi.deinit`. Both happen in build.zig, so a fresh fetch keeps
+ them.
+- **SDL is compiled with `SDL_DISABLE_STB`.** `SDL_LoadPNG` and MJPEG camera
+ frames then report unsupported; pardes calls neither.
+
+## Where one copy was not possible
+
+- **Two inflates: zlib and wuffs.** FreeType and MuPDF call zlib's C API
+ (`inflateInit2_`, `inflate`, raw and zlib streams). ghostty-vt calls
+ `wuffs.zlib.decode` for kitty `o=z`. One of them would have to go:
+ - Dropping zlib needs a zlib-API shim over wuffs's streaming decoder.
+ - Dropping wuffs needs a patch to ghostty's `graphics_image.zig` that points
+ away from ghostty's own choice.
+
+ Neither is small, and each copy is about 17 KiB.
+- **Two JPEG decoders: MuPDF's libjpeg and wuffs.** MuPDF's `DCTDecode` filter
+ (`filter-dct.c`) is written against libjpeg's streaming source-manager API.
+ Moving PDFs onto wuffs means a new DCT filter for fitz. Moving image panes
+ onto libjpeg instead would leave the builds without MuPDF (esp32p4, web)
+ with no JPEG decoder.
+- **MuPDF's fitz image loaders** (`fz_load_png`, `_jpeg`, `_gif`, `_bmp`,
+ `_tiff`, `_pnm`, `_psd`; 16.7 KiB together). They are compiled because
+ mupdf.zig builds all of `source/fitz`. They are reachable only through
+ `fz_new_image_from_buffer`, which PDF rendering does not call. Dropping
+ them means stubbing fitz's image-type dispatch (`image.c`) at build time.
+ Left in.
+- **base64**:
+ - Zig's `std.base64`: pardes (dumps, the tty's kitty output) and vaxis.
+ - simdutf's: ghostty-vt, for kitty payloads.
+ - MuPDF's own: unused paths.
+
+ Pure Zig beside C++, so lower priority. Going through simdutf from pardes
+ would mean importing ghostty's SIMD module surface.
+- **Unicode text**: uucode is shared. Each of these still carries its own
+ UTF-8 and property code for its own job:
+ - ghostty's generated `unicode_tables` (built from the same uucode);
+ - HarfBuzz's UCD;
+ - SDL's `SDL_utf8*`;
+ - MuPDF's `fz_chartorune`;
+ - simdutf.
+
+ None of them is a separate copy of the same library.
+- **Image scaling**: stb_image_resize (image panes) beside MuPDF's pixmap
+ scaler and SDL's blitter. These are three algorithms with different jobs,
+ not one library twice.
+- **Zig's `std.compress.flate`** (15 KiB): std.debug pulls it in to read
+ compressed debug sections for stack traces. It is not a codec pardes
+ calls.
+- **zigimg** (vaxis's image loader, pure Zig): vaxis only uses it to load
+ images from paths, which pardes never asks for. Zig compiles only what is
+ referenced, so none of it is linked.
+- **libc++**: simdutf's build links Zig's bundled libc++ (`link_libcpp` unless
+ MSVC). It is one copy, and its `new`/`delete` go to libc's malloc, not a Zig
+ allocator.
+- **simdutf and highway**: no allocator hook, and none needed; the paths
+ ghostty uses allocate nothing (`HWY_NO_LIBCXX`, `SIMDUTF_NO_LIBCXX`).