summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-28 21:23:53 -0300
committerGabriel Schneider <[email protected]>2026-10-28 21:46:53 -0300
commit3ad8a8117435124d5df8c1d70de62c32dd97e113 (patch)
tree1a62696a04308a64f5122a17a8f0fabeae393677 /docs
parentb250eb6135475699a945324c005890e8e1b4dd0b (diff)
downloadpardes-3ad8a8117435124d5df8c1d70de62c32dd97e113.tar.gz
pardes-3ad8a8117435124d5df8c1d70de62c32dd97e113.zip
one copy of each codec: PNG and JPEG through wuffs (ghostty's, already linked by ghostty-vt), stb_image without them, its writer and its inflate, SDL without its private stb_image; a symbol-table guard; docs/shared-libs.md
ReleaseFast before, both binaries carried stb_image's PNG, JPEG and inflate beside wuffs's (whose function tables keep its decoders linked whatever pardes calls), stb_image_write and its deflate (unused), and the GUI a second stb_image of SDL's (SDL_stb.c, for SDL_LoadPNG and camera MJPEG). Now: - image.zig decodes PNG and JPEG with wuffs (`wuffs_images`, wherever ghostty-vt is in the build), sized from the IHDR or the first SOF before decoding, as stb's info call sized them; other formats and the builds without ghostty-vt keep stb_image. - build.zig compiles zstbi with -DSTBI_NO_PNG -DSTBI_NO_JPEG and patches its stb_image_write include out (one count-checked anchor; a no-op stbi_flip_vertically_on_write stays for zstbi.deinit), and SDL with SDL_DISABLE_STB. Text: tty -74,488 bytes, gui -154,392. `zig build shared-libs-check` (in unit-test, ELF) reads the linked symbol table and fails on a family the build chose against: stb's PNG/JPEG/inflate beside wuffs, a second stb_image, stb_image_write's deflate, a second zlib or FreeType. Checked against the old binaries: it names every one. docs/shared-libs.md: the inventory (implementation, users, copies and bytes before and after, allocator hook) and where one copy was not possible: zlib and wuffs both inflate (FreeType's and MuPDF's zlib API vs ghostty's kitty o=z), MuPDF's libjpeg beside wuffs (filter-dct.c is libjpeg's API), MuPDF's unreached fitz image loaders, base64 in Zig std/simdutf/MuPDF, per-library Unicode code, std.debug's flate. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'docs')
-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`).