Libghostty 1.0に学ぶ安定したC ABI設計
Libghostty 1.0に学ぶ、不透明ハンドル、enumキーのAPI、CIでのシンボルバージョン管理によるABI安定性設計の実践ポイント。

想像してみてください。あなたはJetBrainsのIDEに搭載されているターミナルを担当するチームにいます。エミュレータであるJediTermにバグがあり、ターミナルエミュレータが得意とするような、再現が非常に厄介な種類のものです。特定のマイナーなエスケープシーケンスが誤って描画されてしまうのです。パッチを当てることもできますが、もう一つの選択肢は、十年分積み重なったエミュレーションのコードを削除し、他の誰かが保守し、ファジングし、9つのOSへ移植してくれている、安定したABIを持つCライブラリにリンクすることです。JetBrainsは後者を選びました。JetBrains自身の発表によれば、1,250万人を超えるアクティブユーザーを抱えるIntelliJ、PyCharm、GoLandのすべてのユーザーが、今週1.0に到達したlibghostupを基盤としたターミナルを使うようになりました。
見出しの数字は確かに印象的ですが、より興味深い話はその下にあります。libghostty は、Mitchell Hashimoto 氏によるGPUアクセラレーション対応ターミナル Ghostty から切り出されたターミナルエミュレーションのコアで、ABI安定性ポリシーを備えたスタンドアロンのCライブラリとして公開されています。1年前にはC APIも存在せず、利用者は1つだけでした。今日では、タグ付けされた1.0、配布可能なパッケージング、そして開発者ツール界の顔ぶれがそろったような採用リストがあります。「内部実装を持つアプリ」から「業界が信頼するライブラリ」へどう至ったかは、ターミナルの枠を超えて通用するエンジニアリングの規律に関する教訓です。
アプリからライブラリへ: libghostty はどのように切り出されたか
ターミナルエミュレーションは、遠目には簡単そうに見えるのに、近づくと静かに過酷な問題領域です。何十年分ものエスケープシーケンス、競合するグラフィックプロトコル、Unicodeの書記素クラスタリング、リサイズ時のスクロールバックの再フローなど、ターミナルを作る人は皆、同じ地雷原を再発見することになります。以前、GPUアクセラレーション対応のモダンなターミナルの仕組みについて、TTYのパースからグリフアトラスまで書きましたが、一貫したテーマは、エミュレーション層こそ正しさが死んでいく場所だということです。まさに一度書いて、徹底的にテストし、共有したいタイプのコードです。
Ghostty の作者は最初からこのことを理解していたようです。アプリケーションは Zig で書かれ、エミュレーションコアは切り離せるように構造化されていました。最初は Zig モジュールとして、次に C API の背後に、そして今では libghostty-vt 1.0 として、独自のリリースサイクル、独自のtarball、独自の利用者を持っています。この切り出しは後付けや広報的なジェスチャーではありません。プロジェクトは C API が存在するより1年以上前にその意図を発表し、その1年を境界を現実のものにするために費やしました。手順の順序が重要です。ライブラリが1.0に昇格したのはコードが動いたときではなく、そのコードについて約束できるほど周囲の契約が安定したときでした。
利用者のリストは、この賭けが成功したことを示しています。Neovim には libvterm を libghostty-vt に置き換えるプルリクエストが承認済みで、これは10年来のリサイズ時スクロールバック再フローの問題を解決するものです。プロジェクトごとに独自のエミュレータを保守していると、こうした課題がどれほど長く残り続けるかが分かります。KDE の開発者は、これを基盤とした Konsole の後継を試作しています。Vercel の Turborepo はタスク出力のレンダリングに使っています。Antithesis はTUIプログラムのファジングに使い、btop で実際のバグを見つけました。誰かがこれを使って Emacs のターミナルを作り、xterm.js 互換 API を持つ WebAssembly ビルドも存在します。Rust、Go、JavaScript、Swift、Python、.NET、Elixir、Dart、Java 向けのコミュニティ製バインディングもあります。
安定したC ABIの設計: 不透明ハンドルと enum キー
自分のプロジェクトで真似する価値のある部分はここです。多くのCライブラリが長持ちしないのは、コードが腐るからではなく、ABIが硬直化するからです。構造体にフィールドが追加されるたびにすべての利用者の再コンパイルが必要になり、関数シグネチャが変わるとシンボルが消え、enum が増えると値がずれます。libghostty の設計は、この3つすべてを避けるための短いお手本であり、その技術は古くから実証済みなのに、慢性的に十分活用されていません。
/* 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);
重い役割を担うのは3つの決定です。第一に、すべてのオブジェクトは不透明ハンドルです。呼び出し側はポインタを保持するだけで、構造体は見ません。そのためライブラリはリリース間で内部を自由に再構成できます。第二に、読み書き可能な数百の値は、少数の enum キーによる getter と setter の背後に置かれています。新機能は新しい enum 定数を意味し、新しいエクスポートシンボルは必要ありません。新しいヘッダでビルドされたプログラムが古いライブラリで動いた場合でも、クラッシュや不正な値ではなく、きれいに GHOSTTY_UNSUPPORTED が返ります。この細部の違いが、穏やかな機能縮退と、他社製品での午前3時のセグメンテーション違反との違いなのです。
第三に、公開される少数の構造体は自身のサイズを持つか、パディングを予約しているため、レイアウトを壊さずにフィールドを追加できます。これは sockaddr や Win32 API が何十年も使ってきた手法と同じです。enum は C 標準が許す限り、すべてのコンパイラで int に固定されています。コンパイラによって基底型がずれる enum は ABI の時限爆弾だからです。どれも特殊なものではありません。ただ、ABI を現在のソースレイアウトの偶然の産物ではなく、初日から製品の機能として扱うと決めた場合にだけ行うことです。これは最も純粋な形での仕様と実装のギャップです。ABIこそが仕様であり、それ以外はすべて交渉の余地があるのです。
- すべてに不透明ハンドルを。 呼び出し側はレイアウトを見ないため、レイアウトを自由に変更できる。
- enum キーの getter と setter。 新しい設定は新しいシンボルではなく新しい定数であり、古いライブラリはクラッシュせず GHOSTTY_UNSUPPORTED を返す。
- サイズを持つ公開構造体。 struct_size フィールドにより後からフィールドを追加でき、予約パディングで将来の余地を確保する。
- enum 型の固定。 enum を int に固定し、コンパイラ間で ABI がずれないようにする。
- ELF でのバージョン付きシンボル。 動的ローダーは、一致しないライブラリを実行時の不可解な挙動ではなく、ロード時に名前を挙げて明確に拒否する。
ABI安定性は善意ではなく CI で強制する
「後方互換性を保つ」と主張しないプロジェクトはありません。しかし、ランダムな火曜日に証明できるプロジェクトはほとんどありません。libghostty の CI は、Linux 上でコミット済みのベースラインに対して libabigail を実行し、すべての変更で ABI のずれをチェックします。また、macOS と WebAssembly ではゴールデンな型マニフェストを比較します。ELF プラットフォームではエクスポートされたシンボルがバージョン管理されているため、ローダー自体が強制の仕組みになります。この約束は、コードレビューや注意深さで守られているのではなく、人間がミスをしたときにビルドを失敗させる機械によって守られているのです。
ABI は一度署名して終わりの契約ではありません。CI がすべてのコミットで守り続けなければならない約束です。
これは、API 設計より前に、すべてのライブラリ作者が最初にコピーすべき部分だと私は考えています。自動化された ABI チェックは簡単に設定できます。libabigail の abidiff は1つのツールです。そして「なるべく壊さないようにしている」という曖昧な社会的約束を、「ここがベースライン、ここが差分、この変更は互換性がある/ない」というハードでレビュー可能な成果物に変えます。ライブラリをパッケージ化するかどうかを判断するディストリビューション、そして動的リンクするかどうかを判断する企業は、実際にはその成果物を評価しているのです。Neovim のメンテナが、タグ付けされたリリースを待ってからマージしていたのは形式的な理由ではありません。ディストリビューションには、バージョン付きで個別にパッケージ可能な依存関係と、説明できる互換性の根拠が必要だからです。

パッケージングとライセンス: ライブラリを出荷させる地味な作業
ディストリビューションのメンテナに、ライブラリが採用されない原因を尋ねると、「コード」と答えることはほとんどありません。--prefix や DESTDIR を尊重しないビルド、SONAME の欠落、ライセンスが不明確な同梱依存関係、オフラインでビルドできない tarball などが原因です。libghostty 1.0 は、これらすべてをリリースの対象として扱っています。署名付きのソース tarball、完全オフラインビルド用に Zig のキャッシュ構造で作られた依存関係 tarball、適切な SONAME、pkg-config ファイル、CMake パッケージ設定、そしてディストロがstripできるようにデフォルトで保持されるデバッグ情報です。さらに、エンドユーザーではなくパッケージャ向けに書かれた PACKAGING-LIBGHOSTTY.md がtarball の中に同梱されています。
ライセンスにも同じ配慮がなされており、その戦略的な意味は見た目以上です。ライブラリは MIT ライセンスで、実行時には libc 以外を必要とせず(フリースタンディングでビルドすれば libc すら不要)、いくつかの寛容なライセンスの依存関係をコンパイルに含みます。SIMD 用の simdutf と Google Highway、コンパクトな Unicode テーブル、Kitty グラフィックスのデコード用の Wuffs です。これらは libc++ なしでビルドされるため、C++ 標準ライブラリへの依存もありません。ツリー内にコピーレフトのライセンスは一切ありません。すべての依存関係は、バージョン、SPDX ライセンス、ハッシュを含む機械可読なマニフェストに記載されており、ディストロが同梱ライブラリのメタデータを、調査の手間をかけずに埋められるようになっています。さらに、代わりにシステムの simdutf や Highway を動的リンクするためのビルドフラグまであります。
これらの選択は、それぞれ特定のゲートキーパーが挙げたであろう特定の懸念を取り除いています。これこそが「エンタープライズ対応」の実際の意味です。営業資料ではなく、誰かが尋ねる前に、無数の小さな摩擦を取り除いておくことです。また、なぜ優れたソフトウェアには時間がかかるのかを思い出させてくれます。この作業は一つひとつは難しくありませんが、どれも時間がかかるのです。
API の約束としての移植性とリソース管理
テスト対象のプラットフォームは、Linux(glibc と musl)、macOS、iOS、FreeBSD、Windows、Android、そしてフリースタンディングの WebAssembly に及びます。さらに第二層として、ベアメタルの RISC-V と ARM thumb、WASI、Windows ARM64、illumos、32ビット x86 があり、CI ではビルドされますがまだテストは実行されていません。各プラットフォームでは、そのエコシステムが期待する成果物が提供されています。Apple 向けには @rpath 付きの dylib と XCFramework、Windows 向けには PDB とインポートライブラリ付きの DLL(MSVC でのリンクは CI で検証済み)、Android 15 以降向けに 16 KB ページサイズでビルドされた Android 版、そしてすべての機能を有効にした状態でも 1MB 未満の WASM モジュールです。検索、選択、Kitty グラフィックスなどのサブシステムをコンパイルから除外すればサイズを半分程度まで減らせますが、すべての関数はエクスポートされたままで、GHOSTTY_UNSUPPORTED を返すため、組み込み側のコードを変更する必要はありません。
ただ、私が繰り返し立ち返るポータビリティの話は、振る舞いに関するものです。ライブラリはスレッドを作りません。メモリ確保は、提供されたアロケータを通じてのみ行います。作者は、4コア・8GBのLinuxサーバー上で、それぞれ実際のシェルを動かして出力を生成する1万個のライブターミナルを動かしたと報告しています。ボトルネックはライブラリではなく bash のメモリ消費量であり、シェルをRAMに収めるために dash に切り替える必要があったものの、libghostty-vt は問題なく動き続けたとのことです。「スレッドは生成しない」「あなたのアロケータを横取りしない」という約束は、関数シグネチャと同じくらい実質的なAPIの約束であり、それがゲームエンジン、組み込み機器、ファジングのハーネス、他人のイベントループといった、スレッドを多用する依存関係では致命的になる文脈にもライブラリを組み込めるようにしているのです。
libghostty が教えるライブラリ優先アーキテクチャ
当然比較されるのは libvte です。GNOME Terminal、XFCE のターミナルなど、half a dozen 程度のターミナルの基盤となっている GTK 依存のエミュレーションライブラリです。libvte は数年前に、一つの共有コアと多数の薄いラッパーというモデルの有効性を証明しましたが、GTK との結合によって、その活躍の場は特定のツールキットを使う Linux デスクトップに限られてしまいました。libghostty の賭けは、同じモデルを UI ツールキットから切り離し、安定した C ABI として鍛え上げれば、はるかに遠くまで届くというものです。Java で書かれた IDE、C で書かれたエディタ、Go で書かれた TUI、WASM 経由のブラウザ、そして GTK への依存を決して出荷できない商用製品まで。初期の証拠は、この賭けが正しいことを示しています。libghostty を使ったターミナルを利用している人は、Ghostty 本体を使っている人を大きく上回っています。
より深い教訓は、順序についてです。ライブラリ優先のアーキテクチャとは、ユースケースがある前にライブラリを書くことを意味しません。それでは、誰も必要としない美しい抽象化が生まれるだけです。Ghostty はその逆を行いました。実際のアプリケーションを構築し、本番環境の圧力のもとでドメインの境界を自然に浮かび上がらせ、そして最初から維持してきた境界を硬化させたのです。C API が遅れて登場したからこそ、きれいに登場できたのです。もしあなたが、パーサー、エミュレータ、レイアウトエンジン、プロトコルスタックなど、本当に難しく再利用可能なコアを持つアプリケーションを抱えているなら、ここに青写真があります。最初から境界を誠実に保ち、可能な限り狭い契約を通じて公開し、ABI を CI で監視し、パッケージングの地道な作業にも本気で取り組むことです。エコシステムの効果はそこから積み上がっていきます。あるエンベッダーが報告したバグは、他のすべての利用者のターミナルを良くし、新しいプロトコルは、十数個の非公開フォークに分かれることなく、一斉にあらゆる場所へ届くのです。
Hashimoto 氏は、今では約1,500行の C で、1年前に存在したほぼあらゆるものより多機能なターミナルを作れると主張しています。通常なら、それはメンテナの熱意として片付けるような文ですが、100を超える追跡対象プロジェクトと JetBrains IDE 全体がその主張が現実に耐えることを示唆しています。すべてのアプリケーションが独自にターミナルエミュレータを手作りする時代は、ついに終わるのかもしれません。そして、こうしたことはたいてい、そうやって終わるものです。より良いアプリケーションによってではなく、より良いライブラリによって。


