Libghostty 1.0: Lições de Design de C ABI Estável
Libghostty 1.0 mostra como criar uma C ABI estável com handles opacos, setters por enum, versionamento de símbolos no CI e arquitetura library-first.

Imagine que você faz parte da equipe responsável pelo terminal dentro das IDEs da JetBrains. Seu emulador, o JediTerm, tem um bug, do tipo que emuladores de terminal adoram criar, em que alguma sequência de escape obscura é renderizada errada de um jeito irritante de reproduzir. Você poderia corrigir na mão. Ou poderia jogar fora uma década de código de emulação acumulado e linkar com uma biblioteca C de ABI estável, mantida, testada com fuzzing e portada para nove sistemas operacionais por outra equipe. A JetBrains escolheu a segunda opção. Cada usuário do IntelliJ, PyCharm e GoLand, mais de 12,5 milhões de usuários ativos segundo a própria JetBrains, agora usa um terminal alimentado pelo libghostty, que chegou à versão 1.0 nesta semana.
Esse é o número principal, mas a história mais interessante está por baixo dele. O libghostty é o núcleo de emulação de terminal extraído do Ghostty, o terminal acelerado por GPU de Mitchell Hashimoto, e foi lançado como uma biblioteca C independente com uma política de estabilidade de ABI aplicada. Um ano atrás, ele não tinha API C e tinha exatamente um consumidor. Hoje tem uma versão 1.0 marcada, empacotamento pronto para distribuição e uma lista de adotantes que parece um who's who de ferramentas para desenvolvedores. Como se vai de “app com internals” a “biblioteca em que a indústria confia” é uma lição de disciplina de engenharia que vale muito além dos terminais.
Do App à Biblioteca: Como o libghostty foi extraído
Emulação de terminal é um desses domínios que parecem fáceis de longe e são silenciosamente brutais de perto. Décadas de sequências de escape, protocolos de gráficos concorrentes, clusterização de grafemas Unicode, reflow do scrollback ao redimensionar: todo autor de terminal redescobre o mesmo campo minado. Já escrevi antes sobre como funcionam os terminais modernos acelerados por GPU, desde o parsing de TTY até os atlas de glifos, e o tema constante é que a camada de emulação é onde a correção vai para morrer. É exatamente o tipo de código que você quer escrever uma vez, testar até a exaustão e compartilhar.
O autor do Ghostty parece ter entendido isso desde o início. A aplicação foi construída em Zig, com o núcleo de emulação estruturado para poder ser separado: primeiro como um módulo Zig, depois atrás de uma API C e agora como libghostty-vt 1.0, com ciclo de release próprio, tarballs próprios e consumidores próprios. A extração não foi uma reflexão tardia nem um gesto de marketing; o projeto anunciou a intenção mais de um ano antes de existir uma API C, e então passou esse ano tornando a fronteira real. A ordem das coisas importa: a biblioteca não foi promovida a 1.0 quando o código funcionou, mas quando o contrato em volta do código estava estável o bastante para prometer coisas sobre ele.
A lista de consumidores sugere que a aposta deu certo. O Neovim tem um pull request aprovado substituindo o libvterm pelo libghostty-vt, uma mudança que fecha uma issue de dez anos sobre reflow do scrollback ao redimensionar, o que mostra quanto tempo essas feridas ficam abertas quando todo projeto mantém seu próprio emulador. Desenvolvedores do KDE estão prototipando um sucessor do Konsole em cima dele. O Turborepo, da Vercel, usa a biblioteca para renderizar a saída das tarefas. A Antithesis a usou para fazer fuzzing de programas TUI e encontrou bugs reais no btop. Alguém construiu um terminal para Emacs sobre ela, e existe um build em WebAssembly com uma API compatível com o xterm.js. Há bindings da comunidade para Rust, Go, JavaScript, Swift, Python, .NET, Elixir, Dart e Java.
Projetando uma C ABI Estável: Handles Opacos e Chaves por Enum
Aqui está a parte que vale copiar para os seus próprios projetos. A maioria das bibliotecas C não envelhece bem não porque o código apodrece, mas porque a ABI se cristaliza: uma struct ganha um campo e todos os consumidores precisam recompilar, a assinatura de uma função muda e símbolos somem, um enum cresce e os valores mudam de lugar. O design do libghostty é uma pequena aula de como evitar essas três coisas, e as técnicas são antigas, comprovadas e cronicamente subutilizadas.
/* 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);
Três decisões fazem o trabalho pesado. Primeiro, todo objeto é um handle opaco: quem chama segura ponteiros, nunca structs, então a biblioteca pode remodelar os internos livremente entre versões. Segundo, as centenas de valores legíveis e graváveis ficam atrás de um pequeno conjunto de getters e setters indexados por enum. Nova funcionalidade significa uma nova constante de enum, não um novo símbolo exportado, e um programa compilado com headers mais novos, mas executando contra uma biblioteca mais antiga, recebe um resultado limpo GHOSTTY_UNSUPPORTED em vez de um crash ou lixo silencioso. Esse detalhe é a diferença entre uma degradação elegante e um segfault às 3 da manhã no produto de outra pessoa.
Terceiro, as poucas structs que são públicas carregam o próprio tamanho ou reservam padding, então campos podem ser acrescentados sem quebrar o layout, o mesmo truque que sockaddr e a API Win32 usam há décadas. Os enums são fixados em int em todos os compiladores, na medida em que o padrão C permite, porque um enum cujo tipo subjacente muda entre compiladores é uma bomba-relógio na ABI. Nada disso é exótico. Tudo isso é o tipo de coisa que você só faz se decidir, no primeiro dia, que a ABI é uma funcionalidade do produto e não um acidente do layout atual do código-fonte. Este é o gap entre especificação e implementação em sua forma mais pura: a ABI é a especificação, e todo o resto é negociável.
- Handles opacos para tudo. Quem chama nunca vê o layout, então o layout é livre para mudar.
- Getters e setters indexados por enum. Novas configurações são novas constantes, não novos símbolos, e bibliotecas antigas respondem GHOSTTY_UNSUPPORTED em vez de travar.
- Structs públicas que se dimensionam. Um campo struct_size permite acrescentar campos depois; o padding reservado garante espaço para o futuro.
- Tipos de enum fixados. Enums fixados em int para que a ABI não mude entre compiladores.
- Símbolos versionados em ELF. O carregador dinâmico recusa uma biblioteca incompatível pelo nome, de forma explícita, na hora do load, e não de forma misteriosa, em tempo de execução.
Aplicando a Estabilidade de ABI no CI, Não em Boas Intenções
Todo projeto diz que é compatível com versões anteriores. Quase nenhum consegue provar isso numa terça-feira qualquer. O CI do libghostty roda o libabigail contra uma baseline versionada no Linux, verificando cada mudança quanto a desvios de ABI, e compara manifestos de tipos de referência no macOS e no WebAssembly. Os símbolos exportados em plataformas ELF são versionados, então o próprio carregador vira um mecanismo de aplicação. A promessa não é mantida por code review e vigilância; é mantida por máquinas que quebram o build quando um humano escorrega.
Uma ABI não é um contrato que você assina uma vez. É uma promessa que seu CI precisa cumprir em cada commit.
Esta é a peça que eu recomendaria a todo autor de biblioteca copiar primeiro, antes de qualquer desenho de API. Checagem automatizada de ABI é barata de configurar (o abidiff do libabigail é uma única ferramenta) e transforma uma promessa social vaga, “tentamos não quebrar nada”, em um artefato concreto e revisável: “aqui está a baseline; aqui está o diff; esta mudança é ou não é compatível”. Distribuições que decidem empacotar sua biblioteca, e empresas que decidem linkar dinamicamente com ela, estão na prática avaliando esse artefato. O motivo de os mantenedores do Neovim terem esperado uma release marcada antes de fazer o merge não é burocracia: distribuições precisam de uma dependência versionada, empacotável separadamente, com uma história de compatibilidade que possam defender.

Empacotamento e Licenciamento: O Trabalho Chato que Entrega Bibliotecas
Pergunte a qualquer mantenedor de distribuição o que mata as chances de uma biblioteca e raramente ele vai dizer “o código”. É o build que não respeita --prefix ou DESTDIR, o SONAME que falta, as dependências vendorizadas com licenças pouco claras, o tarball que não builda offline. O Libghostty 1.0 trata tudo isso como superfície de release: tarballs de código-fonte assinados, um tarball companheiro de dependências no layout de cache do Zig para builds totalmente offline, SONAMEs adequados, arquivos pkg-config, configs de pacote CMake e informações de depuração mantidas por padrão para que as distros possam removê-las. Há um PACKAGING-LIBGHOSTTY.md que vai dentro do tarball, escrito para quem empacota, não para o usuário final.
A licença recebeu o mesmo tratamento, e é mais estratégica do que parece. A biblioteca é MIT, não precisa de nada além da libc em tempo de execução (e pode ser compilada em modo freestanding, sem nem isso) e incorpora um punhado de dependências com licenças permissivas: simdutf e Google Highway para SIMD, uma tabela Unicode compacta, Wuffs para decodificar gráficos do Kitty. Todas são construídas sem libc++, então não há dependência da biblioteca padrão C++. Zero copyleft em toda a árvore. Cada dependência está listada em um manifesto legível por máquina, com versão, licença SPDX e hash, justamente para que as distros possam preencher os metadados de bibliotecas embutidas sem arqueologia. Existe até uma flag de build para linkar dinamicamente o simdutf ou o Highway do sistema.
Cada uma dessas escolhas remove uma objeção específica que um guardião específico levantaria. É isso que “pronto para empresas” realmente significa na prática: não uma página de vendas, mas uma centena de pequenos atritos lixados antes que alguém precisasse perguntar. É também um lembrete de por que um bom software leva tempo: nenhum desse trabalho é difícil, e todo ele é lento.
Portabilidade e Disciplina de Recursos como Promessas de API
A matriz de plataformas testadas cobre Linux (glibc e musl), macOS, iOS, FreeBSD, Windows, Android e WebAssembly freestanding, com um segundo nível (RISC-V e ARM thumb bare-metal, WASI, Windows ARM64, illumos, x86 de 32 bits) que builda no CI mas ainda não roda testes. Cada plataforma recebe os artefatos que seu ecossistema espera: dylibs com @rpath e XCFrameworks para a Apple, uma DLL com PDB e biblioteca de importação para Windows (linkagem MSVC verificada no CI), um build Android com páginas de 16 KB para Android 15+, e um módulo WASM com menos de um megabyte com todas as funcionalidades ativadas. Esse módulo pode ser reduzido removendo subsistemas como busca, seleção e gráficos Kitty, com todas as funções ainda exportadas e retornando GHOSTTY_UNSUPPORTED, para que o código do embedder nunca precise mudar.
Mas a história de portabilidade em que sempre volto é comportamental. A biblioteca não cria threads. Ela só aloca através de um alocador que você fornece. O autor relata ter rodado 10.000 terminais vivos, cada um dirigindo um shell real produzindo saída, num servidor Linux com 4 núcleos e 8 GB, e observa que o gargalo foi o apetite de memória do bash, não da biblioteca; ele precisou trocar para o dash para caber os shells na RAM enquanto o libghostty-vt seguia tranquilo. “Não criamos threads” e “não somos donos do seu alocador” são promessas de API tão reais quanto qualquer assinatura de função, e são o que torna uma biblioteca embutível em contextos como game engines, dispositivos embarcados, harnesses de fuzzing e event loops alheios, onde uma dependência que cria threads seria um impeditivo.
O Que o libghostty Ensina sobre Arquitetura Library-First
A comparação óbvia é o libvte, a biblioteca de emulação atrelada ao GTK por trás do GNOME Terminal, do terminal do XFCE e de meia dúzia de outros. O libvte provou o modelo anos atrás (um núcleo compartilhado, muitos wrappers finos), mas seu acoplamento ao GTK restringiu seu mundo a desktops Linux com um toolkit específico. A aposta do libghostty é que o mesmo modelo, desacoplado de qualquer toolkit de UI e endurecido numa ABI C estável, chega muito mais longe: a IDEs escritas em Java, editores escritos em C, TUIs escritas em Go, navegadores via WASM e produtos comerciais que jamais poderiam enviar uma dependência de GTK. As primeiras evidências dizem que a aposta está certa. Mais pessoas já usam um terminal alimentado pelo libghostty do que usam o próprio Ghostty, por um múltiplo grande.
A lição mais profunda é sobre sequenciamento. Arquitetura library-first não significa escrever uma biblioteca antes de ter um caso de uso, porque isso é como você acaba com abstrações lindas que ninguém precisa. O Ghostty fez o oposto: construiu uma aplicação real, deixou as fronteiras do domínio emergirem sob pressão de produção e então endureceu a costura que vinha mantendo o tempo todo. A API C chegou tarde, e é exatamente por isso que chegou limpa. Se você tem uma aplicação com um núcleo genuinamente difícil e reutilizável (um parser, um emulador, um motor de layout, uma pilha de protocolo), o roteiro está visível aqui: mantenha a fronteira honesta desde o início, exponha-a pelo contrato mais estreito possível, coloque a ABI sob vigilância do CI e faça o trabalho chato de empacotamento como se você realmente se importasse. Os efeitos no ecossistema se acumulam a partir daí. Cada bug que um embedder reporta melhora o terminal de todos os outros consumidores, e cada novo protocolo chega a todos ao mesmo tempo, em vez de se fragmentar em uma dúzia de forks privados.
Hashimoto afirma que hoje dá para construir um terminal com cerca de 1.500 linhas de C que tem mais recursos do que quase qualquer coisa que existia há um ano. Esse é o tipo de frase que eu normalmente arquivaria como entusiasmo de mantenedor, exceto que mais de cem projetos rastreados e toda a frota de IDEs da JetBrains sugerem que a afirmação sobrevive ao contato com a realidade. A era de cada aplicação criar à mão seu próprio emulador de terminal talvez esteja finalmente acabando, e está acabando do jeito que essas coisas costumam acabar: não com uma aplicação melhor, mas com uma biblioteca melhor.


