Libghostty 1.0: уроки проектирования стабильного C ABI
Libghostty 1.0 показывает, как спроектировать стабильный C ABI: непрозрачные дескрипторы, сеттеры с enum-ключами, контроль версий символов в CI и архитектура library-first.

Представьте, что вы в команде, которая отвечает за терминал внутри IDE JetBrains. Ваш эмулятор, JediTerm, содержит баг, из тех, в которых специализируются эмуляторы терминалов: какая-то малоизвестная escape-последовательность отрисовывается неправильно, и воспроизвести это — сущее мучение. Можно залатать баг. А можно удалить десятилетие накопленного кода эмуляции и подключить C-библиотеку со стабильным ABI, которую кто-то другой поддерживает, фаззит и портирует на девять операционных систем. JetBrains выбрали второй вариант. Каждый пользователь IntelliJ, PyCharm и GoLand (более 12,5 миллиона активных пользователей по данным самой JetBrains) теперь работает с терминалом на базе libghostty, которая на этой неделе вышла в версии 1.0.
Но это лишь заголовок, а интереснее история под ним. Libghostty — это ядро эмуляции терминала, выделенное из Ghostty, GPU-ускоренного терминала Митчелла Хашимото, и выпущенное как самостоятельная C-библиотека с обязательной политикой стабильности ABI. Год назад у неё не было C API и ровно одного потребителя. Сегодня есть помеченный тегом релиз 1.0, готовые пакеты для дистрибутивов и список адоптеров, который читается как перечень лидеров инструментов для разработчиков. Путь от «приложения с внутренностями» до «библиотеки, которой доверяет индустрия» — это урок инженерной дисциплины, применимый far beyond терминалов.
От приложения к библиотеке: как libghostty отделили от Ghostty
Эмуляция терминала — одна из тех предметных областей, которые издалека кажутся простыми, а вблизи тихо оказываются жестокими. Десятилетия escape-последовательностей, конкурирующие графические протоколы, группировка графем в Unicode, перекомпоновка scrollback при изменении размера — каждый автор терминала заново открывает одно и то же минное поле. Я уже писал о том, как работают современные GPU-ускоренные терминалы, от разбора TTY до атласов глифов, и общий вывод такой: слой эмуляции — это место, где корректность умирает. Это именно тот код, который стоит написать один раз, протестировать до посинения и поделиться им.
Похоже, автор Ghostty понял это с самого начала. Приложение написано на Zig, а ядро эмуляции устроено так, чтобы его можно было отделить: сначала как модуль Zig, затем за C API, а теперь как libghostty-vt 1.0 со своим циклом релизов, своими tarball-архивами и своими потребителями. Выделение не было запоздалой мыслью или маркетинговым жестом: проект объявил о намерении за год до появления C API, а потом потратил этот год на то, чтобы граница стала реальной. Порядок действий важен: библиотеку выпустили как 1.0 не тогда, когда код заработал, а когда контракт вокруг кода стал достаточно стабильным, чтобы что-то о нём обещать.
Список потребителей говорит, что ставка сыграла. У Neovim есть одобренный pull request, заменяющий libvterm на libghostty-vt. Это изменение закрывает десятилетнюю issue о перекомпоновке scrollback при изменении размера, и это хорошо показывает, как долго такие раны не заживают, когда каждый проект поддерживает собственный эмулятор. Разработчики KDE прототипируют преемника Konsole на её основе. Turborepo от Vercel использует её для вывода задач. Antithesis применила её для фаззинга TUI-программ и нашла реальные баги в btop. Кто-то собрал терминал для Emacs на её основе, а также есть сборка для WebAssembly с API, совместимым с xterm.js. Для неё существуют сторонние биндинги для Rust, Go, JavaScript, Swift, Python, .NET, Elixir, Dart и Java.
Проектирование стабильного C ABI: непрозрачные дескрипторы и enum-ключи
Вот часть, которую стоит позаимствовать для собственных проектов. Большинство C-библиотек теряют долговечность не потому, что код гниёт, а потому, что ABI костенеет: структура получает новое поле, и всем потребителям приходится перекомпилироваться; сигнатура функции меняется, и символы исчезают; enum растёт и сдвигает значения. Дизайн 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);
Три решения делают основную работу. Во-первых, каждый объект — непрозрачный дескриптор: вызывающая сторона держит указатели, а не структуры, поэтому библиотека может свободно менять внутреннее устройство между релизами. Во-вторых, сотни читаемых и записываемых значений доступны через небольшой набор геттеров и сеттеров с ключами-enum. Новая функциональность означает новую константу enum, а не новый экспортируемый символ, и программа, собранная с более новыми заголовками, но работающая со старой библиотекой, получает чистый результат GHOSTTY_UNSUPPORTED вместо падения или тихого мусора в данных. Эта деталь отделяет корректную деградацию от ночного segfault в чужом продакшене в три часа утра.
В-третьих, немногие публичные структуры несут собственный размер или зарезервированный padding, поэтому поля можно дописывать без поломки раскладки. Это тот же трюк, что используют sockaddr и Win32 API на протяжении десятилетий. Enum'ы привязаны к int на всех компиляторах, насколько это позволяет стандарт C, потому что enum, у которого базовый тип меняется от компилятора к компилятору, — это бомба замедленного действия для ABI. Ничего из этого не экзотика. Всё это делают только тогда, когда в первый день решают, что ABI — это свойство продукта, а не побочный эффект текущей структуры исходников. Это разрыв между спецификацией и реализацией в чистом виде: ABI и есть спецификация, а всё остальное подлежит обсуждению.
- Непрозрачные дескрипторы для всего. Вызывающая сторона никогда не видит раскладку, поэтому её можно свободно менять.
- Геттеры и сеттеры с enum-ключами. Новые настройки — это новые константы, а не новые символы; старые библиотеки отвечают GHOSTTY_UNSUPPORTED вместо падения.
- Публичные структуры, знающие свой размер. Поле struct_size позволяет дописывать поля позже; зарезервированный padding даёт запас на будущее.
- Зафиксированные типы enum. Enum'ы привязаны к int, чтобы ABI не менялся между компиляторами.
- Версионированные символы в ELF. Динамический загрузчик отказывается загружать несовместимую библиотеку по имени, громко и на этапе загрузки, а не загадочно, во время выполнения.
Обеспечение стабильности ABI в CI, а не на честном слове
Каждый проект заявляет о обратной совместимости. Почти никто не может это доказать в случайный вторник. CI libghostty запускает libabigail против закоммиченной базовой линии на Linux, проверяя каждое изменение на дрейф ABI, и сравнивает эталонные манифесты типов на macOS и WebAssembly. Экспортируемые символы на ELF-платформах версионированы, так что сам загрузчик становится механизмом принуждения. Обещание поддерживается не код-ревью и бдительностью, а машинами, которые роняют сборку, когда человек оплошал.
ABI — это не контракт, который подписывают один раз. Это обещание, которое CI должен выполнять в каждом коммите.
Это первое, что я бы советовал скопировать каждому автору библиотеки, ещё до любого дизайна API. Автоматическая проверка ABI дешева в настройке (abidiff из libabigail — это один инструмент), и она превращает расплывчатое социальное обещание («мы стараемся не ломать») в жёсткий, проверяемый артефакт («вот базовая линия; вот diff; это изменение совместимо или нет»). Дистрибутивы, решающие, упаковывать ли вашу библиотеку, и компании, решающие, линковать ли её динамически, на самом деле оценивают именно этот артефакт. Причина, по которой мейнтейнеры Neovim ждали помеченного релиза перед слиянием, не в формализме: дистрибутивам нужна версионированная, отдельно пакуемая зависимость с историей совместимости, которую они могут защитить.

Упаковка и лицензирование: скучная работа, благодаря которой библиотеки доходят до пользователей
Спросите любого мейнтейнера дистрибутива, что губит шансы библиотеки, и он редко скажет «код». Чаще это сборка, которая не учитывает --prefix или DESTDIR, отсутствующий SONAME, вендоренные зависимости с неясными лицензиями, tarball, который не собирается офлайн. Libghostty 1.0 рассматривает всё это как часть релиза: подписанные исходные tarball-архивы, отдельный tarball с зависимостями в формате кэша Zig для полностью офлайн-сборок, правильные SONAME, файлы pkg-config, конфиги пакетов CMake, отладочная информация по умолчанию, чтобы дистрибутивы могли её удалить. Есть файл PACKAGING-LIBGHOSTTY.md, который поставляется внутри tarball и написан для упаковщика, а не для конечного пользователя.
Лицензированию уделено то же внимание, и оно важнее, чем кажется. Библиотека распространяется под MIT, для работы во время выполнения ей не нужно ничего, кроме libc (а можно собрать и freestanding, даже без неё), и она включает несколько зависимостей с permissive-лицензиями: simdutf и Google Highway для SIMD, компактную таблицу Unicode, Wuffs для декодирования графики Kitty. Всё собрано без libc++, поэтому нет зависимости от стандартной библиотеки C++. Ни одного copyleft в дереве. Каждая зависимость перечислена в машиночитаемом манифесте с версией, SPDX-лицензией и хешем, специально для того, чтобы дистрибутивы могли заполнить метаданные встроенных библиотек без археологии. Есть даже флаг сборки, позволяющий динамически линковать системные simdutf или Highway вместо встроенных.
Каждый из этих выборов снимает конкретное возражение конкретного привратника. Именно так на практике выглядит «готовность к enterprise»: не лендинг с обещаниями, а сотня мелких шероховатостей, отшлифованных до того, как кто-то об этом спросил. Это также напоминание о том, почему хорошее ПО требует времени: ни одна из этих задач не сложна, а все вместе они медленные.
Переносимость и бережное отношение к ресурсам как обещания API
Протестированная матрица платформ охватывает Linux (glibc и musl), macOS, iOS, FreeBSD, Windows, Android и freestanding WebAssembly, а также второй уровень: bare-metal RISC-V и ARM thumb, WASI, Windows ARM64, illumos, 32-битный x86. Они собираются в CI, но тесты пока не запускают. Каждая платформа получает артефакты, которые ожидает её экосистема: dylib с @rpath и XCFramework для Apple, DLL с PDB и import library для Windows (компоновка MSVC проверяется в CI), сборку для Android 15+ с размером страницы 16 КБ, а также модуль WASM менее мегабайта со всеми включёнными возможностями. Его можно уменьшить вдвое, исключив подсистемы вроде поиска, выделения и графики Kitty; при этом все функции остаются экспортированными и возвращают GHOSTTY_UNSUPPORTED, так что код встраивающего приложения никогда не нужно менять.
Но история переносимости, к которой я постоянно возвращаюсь, — поведенческая. Библиотека не создаёт потоков. Она выделяет память только через аллокатор, который вы предоставляете. Автор сообщает, что запустил 10 000 живых терминалов, каждый из которых управлял настоящей оболочкой и выдавал вывод, на Linux-сервере с 4 ядрами и 8 ГБ памяти. Он отметил, что узким местом оказался аппетит bash к памяти, а не библиотека: пришлось перейти на dash, чтобы уместить оболочки в ОЗУ, пока libghostty-vt спокойно работала. «Мы не создаём потоки» и «мы не владеем вашим аллокатором» — это обещания API не меньше любой сигнатуры функции, и именно они делают библиотеку встраиваемой в контекстах (игровые движки, встраиваемые устройства, фаззинг-обвязки, чужие event loop), где зависимость, охочая до потоков, стала бы стоп-фактором.
Что libghostty учит нас об архитектуре library-first
Очевидное сравнение — libvte, библиотека эмуляции на GTK, лежащая в основе GNOME Terminal, терминала XFCE и ещё полдюжины других. libvte доказала эту модель годы назад: одно общее ядро, много тонких оберток. Но привязка к GTK сузила её мир до Linux-десктопов с конкретным тулкитом. Ставка libghostty в том, что та же модель, отвязанная от любого UI-тулкита и закалённая в стабильный C ABI, работает гораздо дальше: в IDE на Java, редакторах на C, TUI на Go, браузерах через WASM и коммерческих продуктах, которые никогда не смогли бы поставить зависимость от GTK. Ранние данные говорят, что ставка верна. Людей, которые пользуются терминалом на базе libghostty, уже больше, чем тех, кто пользуется самим Ghostty, и разрыв в разы.
Более глубокий урок касается последовательности действий. Архитектура library-first не означает писать библиотеку до того, как появился сценарий использования: так получаются красивые абстракции, которые никому не нужны. Ghostty поступил наоборот: построил настоящее приложение, позволил границам доменов проявиться под давлением продакшена, а потом укрепил шов, который поддерживал всё это время. C API появилось поздно, и именно поэтому оно вышло чистым. Если у вас есть приложение с действительно сложным, переиспользуемым ядром (парсером, эмулятором, движком вёрстки, стеком протокола), схема здесь видна: держите границу честной с самого начала, выставляйте её через максимально узкий контракт, ставьте ABI под наблюдение CI и с душой делайте рутинную работу по упаковке. Эффекты для экосистемы копятся дальше: каждый баг, о котором сообщает один встраивающий проект, делает терминал каждого другого потребителя лучше, а каждый новый протокол появляется везде сразу, а не разваливается на десятки приватных форков.
Хашимото утверждает, что сейчас можно написать терминал примерно в 1 500 строках на C, который по возможностям обойдёт почти всё, что существовало год назад. Обычно я отнёс бы такую фразу к энтузиазму мейнтейнера, но сотня с лишним отслеживаемых проектов и весь парк IDE JetBrains говорят, что это утверждение выдерживает столкновение с реальностью. Эпоха, когда каждое приложение писало собственный эмулятор терминала вручную, возможно, наконец заканчивается, и заканчивается она так, как обычно и бывает: не появлением лучшего приложения, а появлением лучшей библиотеки.


