summaryrefslogtreecommitdiff
path: root/docs/shared-libs.md
blob: 52457bf18d02e45e426559d45ee5e8d5462714ff (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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
# 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=tui|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.

## PDF panes became an addon (2026-11-06)

`lib/pardes/addons/pdf.so` (addons/pdf/pdf.c and pdf_bridge.c) holds MuPDF,
built against the build's FreeType and zlib and linked into the library
with them, all three compiled position-independent; it exports
`pardes_addon` alone (a version script), so its FreeType and zlib never
meet the window's. The binaries hold no MuPDF: the tty none of FreeType or
zlib either, the window the one FreeType its glyph atlas uses. MuPDF and
the bridge allocate through pardes's heap for kinds (`pa_api.heap` over the
`addon` region, memory.zig), never their own malloc, so the Debug leak check
sees them. A window that loads pdf.so holds a second FreeType and zlib
beside its own: a library apart, as image.so's decoders are. The rows below
are the binaries before both addons.

## Image panes became an addon (2026-11-06)

`lib/pardes/addons/image.so` (addons/image/image.c) decodes image panes with
its own stb_image, PNG, JPEG and inflate included: the binaries keep none of
stb_image but its resize (a kitty PNG's downscale; the decoder and the writer
are patched out of zstbi.c), and a kitty `f=100` PNG is wuffs's alone. A
process that loads image.so holds a second PNG and JPEG decoder and inflate
beside wuffs and zlib: a library apart, outside this policy's reach (it links
nothing of the binary), and allocating through pardes's arenas and job
buffers, never its own malloc. The rows below are the binaries before it.

## 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 |
| On-disk databases: the state file (Recent, the dumps) and a far client's blob cache (2026-11-05) | xitdb (pure Zig, a pinned commit of github.com/xit-vcs/xitdb, MIT) | src/Db.zig | 0 → 1 | | Zig: it allocates through the allocators it is given (a database's buffer, a read's), so it has no hook of its own; no C |

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
  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 a `-Dmupdf=false` build 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`).