深度解析塑造未来的技术文章。

Libghostty 1.0:稳定 C ABI 设计启示

Libghostty 1.0 解析稳定 C ABI 设计:不透明句柄、枚举键访问器、CI 符号版本控制与库优先架构。

一幅插图:一个共享的发光内核为许多终端风格的屏幕供能,它们由光线般的线条相连。
一个模拟内核,多副面孔:libghostty 现在同时运行在 IDE、编辑器、TUI 和新式终端之中。

想象你在负责 JetBrains IDE 内置终端的团队。你们的模拟器 JediTerm 出了个 bug,就是终端模拟器最擅长制造的那种:某个晦涩的转义序列渲染错了,而且极难复现,让人抓狂。你可以自己修补,也可以删掉十年积累下来的模拟代码,改为链接一个稳定 ABI 的 C 库。这个库由别人维护、做模糊测试,还替你移植到九个操作系统上。JetBrains 选了第二条路。根据 JetBrains 自己的数据,超过 1250 万活跃用户(每个 IntelliJ、PyCharm 和 GoLand 用户)现在都在使用由 libghostty 驱动的终端,而 libghostty 本周刚发布 1.0。

这个数字很亮眼,但更有意思的故事藏在下面。Libghostty 是从 Ghostty(Mitchell Hashimoto 开发的 GPU 加速终端)中拆分出来的终端模拟核心,以独立 C 库的形式发布,并执行严格的 ABI 稳定性策略。一年前,它还没有 C API,唯一的使用者就是 Ghostty 自己。如今它有了正式的 1.0 版本、可直接分发的打包,以及一份堪称开发者工具“名人录”的采用名单。如何从“带内部实现的应用”走到“业界信赖的库”,这是一堂工程纪律课,远不止适用于终端。

从应用到库:libghostty 是如何被拆分出来的

终端模拟是那种远看很简单、近看却暗藏残酷的问题领域。几十年的转义序列、相互竞争的图形协议、Unicode 字形簇、调整大小时的回滚区重排,每个终端作者都会重新踩一遍同样的雷区。我之前写过现代 GPU 加速终端的工作原理,从 TTY 解析到字形图集,我反复得出的结论是:模拟层正是正确性“埋骨之地”。它正是那种你希望只写一次、测到极致、然后共享出去的代码。

Ghostty 的作者似乎从一开始就想明白了这一点。应用本身用 Zig 编写,模拟核心的结构从设计上就允许分离:先是一个 Zig 模块,然后是 C API 之后的形态,现在则是拥有独立发布周期、独立压缩包和独立使用者的 libghostty-vt 1.0。这次拆分不是事后补救,也不是营销噱头;项目在 C API 出现前一年多就宣布了这一意图,然后用这一年让边界真正落地。操作顺序很重要:这个库并非在代码“能跑”时升为 1.0,而是在围绕代码的契约稳定到足以对其作出承诺时才升的。

使用者名单说明这场赌注得到了回报。Neovim 有一个已获批准的 PR,用 libghostty-vt 替换 libvterm,这一改动关闭了一个存在十年的、关于调整大小时回滚区重排的 issue,也说明了当每个项目都自己维护一套模拟器时,这类伤口可以敞开多久。KDE 开发者正在基于它原型开发 Konsole 的继任者。Vercel 的 Turborepo 用它渲染任务输出。Antithesis 用它对 TUI 程序做模糊测试,并在 btop 中发现了真实的 bug。有人基于它做了一个 Emacs 终端,还有一个提供 xterm.js 兼容 API 的 WebAssembly 版本。社区已有 Rust、Go、JavaScript、Swift、Python、.NET、Elixir、Dart 和 Java 的绑定。

设计稳定的 C ABI:不透明句柄与枚举键

这部分值得你搬进自己的项目。大多数 C 库长寿失败,并不是因为代码腐烂,而是 ABI 逐渐僵化:结构体加了个字段,所有使用者都得重新编译;函数签名一变,符号就消失;枚举一扩展,值就发生偏移。Libghostty 的设计堪称一堂避开这三种问题的简短大师课,而这些技巧古老、经过验证,却长期被严重低估。

/* The clunky way: the struct IS the ABI.
* Add a field and every consumer recompiles or corrupts memory. */
typedef struct {
int rows;
int cols;
int scrollback_limit;
/* ... forty more fields your ABI now depends on forever */
} term_config_t;
/* The libghostty way: an opaque handle plus enum-keyed access.
* The library can add a hundred new settings without one new symbol. */
typedef struct ghostty_terminal_s ghostty_terminal_t;
typedef enum {
GHOSTTY_TERMINAL_ROWS,
GHOSTTY_TERMINAL_COLS,
GHOSTTY_TERMINAL_SCROLLBACK_LIMIT,
/* new keys append here, forever */
} ghostty_terminal_key_t;
ghostty_result_t ghostty_terminal_get(
const ghostty_terminal_t *terminal,
ghostty_terminal_key_t key,
void *out);
ghostty_result_t ghostty_terminal_set(
ghostty_terminal_t *terminal,
ghostty_terminal_key_t key,
const void *value);

三个决策承担了主要工作。第一,每个对象都是不透明句柄:调用方持有的是指针而不是结构体,因此库可以在版本之间自由重构内部实现。第二,数百个可读写的值都通过一小组枚举键控的 getter 和 setter 访问。新功能意味着新增一个枚举常量,而不是导出一个新符号。如果程序用较新的头文件编译,却运行在旧库上,它会得到一个干净的 GHOSTTY_UNSUPPORTED 结果,而不是崩溃或静默的垃圾数据。这个细节正是优雅降级与别人产品里凌晨 3 点段错误之间的区别。

第三,少数确实公开的结构体会携带自身的大小,或预留填充字段,因此可以在末尾追加字段而不破坏内存布局,这是 sockaddr 和 Win32 API 几十年来一直在用的技巧。在 C 标准允许的范围内,枚举在所有编译器上都固定为 int,因为如果枚举的底层类型在不同编译器之间变化,那就是一颗 ABI 定时炸弹。这些都不奇特。但它们都是你只有在第一天就决定“ABI 是产品功能,而不是当前源码布局的偶然产物”时才会去做的事情。这正是规范与实现之间的差距最纯粹的体现:ABI 就是规范,其他一切都可以协商。

  • 所有对象都用不透明句柄。调用方永远看不到内部布局,因此布局可以自由变化。
  • 枚举键控的 getter 和 setter。新设置就是新常量,而不是新符号;旧库会返回 GHOSTTY_UNSUPPORTED,而不是崩溃。
  • 自带大小的公开结构体。struct_size 字段让你之后可以追加字段;预留的填充则为未来留出空间。
  • 固定的枚举类型。枚举固定为 int,这样 ABI 就不会因编译器不同而变化。
  • ELF 上的版本化符号。动态加载器会在加载时直接按名称拒绝不匹配的库,明确报错,而不是在运行时莫名其妙地出问题。

在 CI 中强制执行 ABI 稳定性,而不是靠良好意图

每个项目都声称向后兼容,却几乎没有哪个能在随便一个周二证明这一点。Libghostty 的 CI 在 Linux 上针对一份已提交的基线运行 libabigail,检查每次变更是否存在 ABI 漂移,并在 macOS 和 WebAssembly 上比对黄金类型清单。ELF 平台上的导出符号带有版本,因此加载器本身也成了强制执行机制。这个承诺并非靠代码审查和警惕来维持,而是靠机器来维持:一旦有人失误,机器就会让构建失败。

ABI 不是签一次就完事的契约,而是你的 CI 必须在每一次提交上都兑现的承诺。

这是我最希望每位库作者在任何 API 设计之前就先抄走的一环。自动化 ABI 检查的搭建成本很低,libabigail 的 abidiff 就是一个工具,它能把模糊的社会性承诺(“我们尽量不破坏东西”)变成一个硬性、可供审查的产物(“这是基线;这是差异;这次变更兼容或不兼容”)。决定是否打包你的库的发行版,以及决定是否动态链接它的公司,实际上评估的正是这个产物。Neovim 的维护者在合并前一直在等待一个带标签的发布版本,这并非繁文缛节,而是因为发行版需要的是一个有版本号、可单独打包的依赖,并且具备他们能够为之辩护的兼容性保证。

一个哨兵形象在石桥入口处测量桥梁,检查之后才允许通行。
ABI 稳定性就像一道检查关卡:每次变更在通过之前都要先与基线对照。

打包与许可:让库真正交付的枯燥工作

问任何发行版维护者,什么会毁掉一个库的前景,他们很少会说是“代码”。而是那些不遵守 --prefix 或 DESTDIR 的构建、缺失的 SONAME、许可不明的内置依赖,或者无法离线构建的压缩包。Libghostty 1.0 把这些都当作发布范围的一部分:签名的源码压缩包、按 Zig 缓存布局组织的配套依赖压缩包(用于完全离线构建)、正确的 SONAME、pkg-config 文件、CMake 包配置,以及默认保留调试信息以便发行版剥离。还有一份 PACKAGING-LIBGHOSTTY.md,它随压缩包一起发布,是写给打包者的,而不是最终用户。

许可也得到了同样的对待,而且它比表面看起来更有战略意义。该库采用 MIT 许可,运行时除 libc 外无需任何依赖(甚至可以在完全独立环境中构建,连 libc 都不需要),并编译进了少量宽松许可的依赖:用于 SIMD 的 simdutf 和 Google Highway、一个紧凑的 Unicode 表,以及用于 Kitty 图形解码的 Wuffs。构建时不使用 libc++,因此不依赖 C++ 标准库。整个代码树中没有任何 copyleft 许可。每个依赖都列在一份机器可读的清单中,包含版本、SPDX 许可证和哈希值,专门为了让发行版无需考古就能填写内置库的元数据。甚至还有一个构建选项,可以改为动态链接系统自带的 simdutf 或 Highway。

每一个选择都消除了某个特定把关人可能提出的具体异议。这才是“企业级就绪”在实践中的真正含义:不是销售页面,而是在有人开口问之前,就把上百处小摩擦打磨掉。这也提醒我们伟大的软件为什么需要时间:这些工作都不难,但每一项都很慢。

可移植性与资源纪律作为 API 承诺

经过测试的平台矩阵涵盖 Linux(glibc 与 musl)、macOS、iOS、FreeBSD、Windows、Android 以及独立(freestanding)的 WebAssembly,另有第二梯队:裸机 RISC-V 和 ARM Thumb、WASI、Windows ARM64、illumos、32 位 x86。它们能在 CI 中构建,但尚未运行测试。每个平台都获得其生态系统所期望的产物:Apple 平台上是带 @rpath 的 dylib 和 XCFramework,Windows 上是附带 PDB 和导入库的 DLL(CI 中已验证 MSVC 链接),面向 Android 15+ 的 16 KB 页大小 Android 构建,以及在开启全部功能时体积不到 1 MB 的 WASM 模块。该模块还可以通过编译时裁剪搜索、选择和 Kitty 图形等子系统来将体积减半,且所有函数依然导出并返回 GHOSTTY_UNSUPPORTED,因此嵌入方的代码永远无需修改。

但我反复想到的可移植性故事是行为层面的。该库不创建任何线程,它只通过你提供的分配器分配内存。作者报告说,在一台 4 核、8 GB 内存的 Linux 服务器上,他运行了 10,000 个实时终端,每个都驱动一个真实的 shell 并产生输出。瓶颈在于 bash 的内存消耗,而不是库本身;他不得不切换到 dash,以便把这些 shell 装进内存,而 libghostty-vt 依然运转顺畅。“我们不创建线程”和“我们不接管你的分配器”与任何函数签名一样,都是真实的 API 承诺,正是它们让库能够嵌入到游戏引擎、嵌入式设备、模糊测试工具、他人的事件循环等场景中,而在这些场景里,一个喜欢开线程的依赖就会成为致命缺陷。

libghostty 对库优先架构的启示

最明显的对比对象是 libvte,它是 GNOME Terminal、XFCE 终端以及另外几十个终端的底层 GTK 模拟库。libvte 多年前就证明了这种模式的价值:一个共享核心,多个轻量包装。但它与 GTK 的耦合把它的世界局限在特定工具包下的 Linux 桌面。Libghostty 的赌注是:同样的模式,若与任何 UI 工具包解耦,并锤炼为稳定的 C ABI,就能走得更远,进入用 Java 编写的 IDE、用 C 编写的编辑器、用 Go 编写的 TUI、通过 WASM 运行的浏览器,以及那些永远无法引入 GTK 依赖的商业产品。早期证据表明这个赌注是对的。使用 libghostty 驱动的终端的人,已经远远多于直接使用 Ghostty 本身的人,且差距是数倍。

更深层的教训在于顺序。库优先架构并不意味着在有使用场景之前就先写库,那样只会得到无人需要的漂亮抽象。Ghostty 采取的恰恰是相反的做法:它先构建了一个真实的应用,让领域边界在生产压力下自然浮现,然后再把一直在维护的那道接缝加固。C API 来得晚,恰恰正因如此它才足够干净。如果你手上有一个确实困难且可复用的核心(解析器、模拟器、布局引擎、协议栈),这里可以看到清晰的方法:从一开始就保持边界诚实,通过尽可能窄的契约暴露它,把 ABI 置于 CI 的监控之下,并认真对待打包这类琐碎工作。生态效应会从此不断累积。每一个嵌入方报告的 bug,都会让其他所有使用者的终端变得更好;每一项新协议都会同时落地到所有地方,而不是在十几个私有分支中四分五裂。

Hashimoto 声称,现在你可以用大约 1,500 行 C 代码构建一个终端,其功能超过一年前几乎所有已有的终端。这类话我通常会归入维护者的热情之言,不过,一百多个被追踪的项目以及整个 JetBrains IDE 用户群,表明这个说法经得起现实检验。每个应用都要手写自己终端模拟器的时代,或许终于要结束了,而且它的结束方式通常如此:不是靠一个更好的应用,而是靠一个更好的库。