diff options
Diffstat (limited to 'docs/shared-libs.md')
| -rw-r--r-- | docs/shared-libs.md | 120 |
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`). |
