summaryrefslogtreecommitdiff
path: root/docs/shared-libs.md
blob: ce0c7d3f4b5ec7f799677f2c24a2a9e08b4bbc1a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# 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` |
| Compress and decompress a far replica's stream (2026-10-30) | zstd 1.5.7 (the upstream tarball; build.zig compiles its lib/: no assembly, no threads, the dfast and lazy block compressors alone) | src/replica.zig | 0 → 1 | 380 KiB tty (516 with every block compressor) | `ZSTD_customMem` → c_heap |

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`).