Libghostty 1.0: lecciones de diseño de ABI estable en C
Libghostty 1.0 muestra cómo diseñar una ABI estable en C: handles opacos, setters con enums, versionado de símbolos en CI y arquitectura library-first.

Imagina que estás en el equipo que se encarga del terminal de los IDEs de JetBrains. Tu emulador, JediTerm, tiene un bug: del tipo que los emuladores de terminal dominan, donde alguna secuencia de escape oscura se renderiza mal y es exasperante de reproducir. Podrías parchearlo. O podrías eliminar una década de código de emulación acumulado y enlazar contra una biblioteca C con ABI estable que otro equipo mantiene, prueba con fuzzing y porta a nueve sistemas operativos por ti. JetBrains eligió la segunda opción. Cada usuario de IntelliJ, PyCharm y GoLand, más de 12,5 millones de usuarios activos según el propio reporte de JetBrains, ahora usa un terminal impulsado por libghostty, que llegó a la 1.0 esta semana.
Ese es el dato llamativo, pero la historia más interesante está debajo. Libghostty es el núcleo de emulación de terminal extraído de Ghostty, el terminal acelerado por GPU de Mitchell Hashimoto, y se publica como biblioteca C independiente con una política de estabilidad de ABI aplicada. Hace un año no tenía API C y tenía exactamente un consumidor. Hoy tiene una 1.0 etiquetada, empaquetado listo para distribuir y una lista de adopción que parece un who's who de herramientas para desarrolladores. Cómo pasar de «aplicación con internals» a «biblioteca en la que confía la industria» es una lección de disciplina de ingeniería que va mucho más allá de los terminales.
De la aplicación a la biblioteca: cómo se extrajo libghostty
La emulación de terminal es de esos dominios que parecen fáciles de lejos y son silenciosamente brutales de cerca. Décadas de secuencias de escape, protocolos gráficos en competencia, agrupación de grafemas Unicode, reflujo del scrollback al redimensionar: cada autor de terminal redescubre el mismo campo minado. He escrito antes sobre cómo funcionan los terminales modernos acelerados por GPU, desde el parseo de TTY hasta los atlas de glifos, y el tema constante es que la capa de emulación es donde la corrección va a morir. Es exactamente el tipo de código que quieres escribir una vez, probar hasta el cansancio y compartir.
El autor de Ghostty parece haberlo entendido desde el principio. La aplicación se construyó en Zig con su núcleo de emulación estructurado para poder separarse: primero como módulo de Zig, luego detrás de una API C, y ahora como libghostty-vt 1.0 con su propio ciclo de lanzamientos, sus propios tarballs y sus propios consumidores. La extracción no fue una ocurrencia tardía ni un gesto de marketing; el proyecto anunció la intención más de un año antes de que existiera la API C, y luego pasó ese año haciendo real el límite. El orden importa: la biblioteca no se promovió a 1.0 cuando el código funcionaba, sino cuando el contrato alrededor del código era lo bastante estable como para prometer cosas sobre él.
La lista de consumidores sugiere que la apuesta valió la pena. Neovim tiene un pull request aprobado que reemplaza libvterm por libghostty-vt, un cambio que cierra un issue de diez años sobre el reflujo del scrollback al redimensionar, lo que dice mucho de cuánto tardan en cerrarse estas heridas cuando cada proyecto mantiene su propio emulador. Los desarrolladores de KDE están prototipando un sucesor de Konsole sobre él. Turborepo de Vercel lo usa para renderizar la salida de tareas. Antithesis lo usó para hacer fuzzing de programas TUI y encontró errores reales en btop. Alguien construyó un terminal para Emacs sobre él, y existe una build en WebAssembly con una API compatible con xterm.js. Hay bindings de la comunidad para Rust, Go, JavaScript, Swift, Python, .NET, Elixir, Dart y Java.
Diseñar una ABI estable en C: handles opacos y claves enum
Aquí está la parte que vale la pena robar para tus propios proyectos. La mayoría de las bibliotecas C fallan en longevidad no porque el código se pudra, sino porque la ABI se calcifica: una struct gana un campo y todos los consumidores necesitan recompilar, una firma de función cambia y los símbolos desaparecen, un enum crece y sus valores se desplazan. El diseño de libghostty es una breve clase magistral para evitar los tres problemas, y las técnicas son antiguas, probadas y crónicamente infrautilizadas.
/* 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);
Tres decisiones hacen el trabajo pesado. Primero, cada objeto es un handle opaco: quien llama sostiene punteros, nunca structs, así que la biblioteca puede reorganizar sus internals libremente entre versiones. Segundo, los cientos de valores legibles y escribibles viven detrás de un pequeño conjunto de getters y setters indexados por enum. Una funcionalidad nueva significa una constante de enum nueva, no un símbolo exportado nuevo, y un programa compilado con cabeceras más nuevas pero ejecutado contra una biblioteca más antigua recibe un resultado limpio GHOSTTY_UNSUPPORTED en lugar de un crash o basura silenciosa. Ese detalle marca la diferencia entre una degradación elegante y un segfault a las 3 a. m. en el producto de otra persona.
Tercero, las pocas structs que sí son públicas llevan su propio tamaño o reservan padding, de modo que se pueden añadir campos sin romper el layout, el mismo truco que usan sockaddr y la API de Win32 desde hace décadas. Los enums están fijados a int en todos los compiladores, en la medida en que el estándar C lo permite, porque un enum cuyo tipo subyacente cambia entre compiladores es una bomba de tiempo para la ABI. Nada de esto es exótico. Todo es el tipo de cosa que solo haces si decides desde el primer día que la ABI es una funcionalidad del producto y no un accidente del layout actual del código. Es la brecha entre especificación e implementación en su forma más pura: la ABI es la especificación, y todo lo demás es negociable.
- Handles opacos para todo. Quien llama nunca ve el layout, así que el layout puede cambiar libremente.
- Getters y setters indexados por enum. Las configuraciones nuevas son constantes nuevas, no símbolos nuevos, y las bibliotecas antiguas responden GHOSTTY_UNSUPPORTED en lugar de romperse.
- Structs públicas con tamaño propio. Un campo struct_size permite añadir campos después; el padding reservado da espacio para el futuro.
- Enums con tipo fijo. Enums fijados a int para que la ABI no cambie entre compiladores.
- Símbolos versionados en ELF. El cargador dinámico rechaza una biblioteca no coincidente por nombre, de forma ruidosa, en el momento de la carga, no de forma misteriosa en tiempo de ejecución.
Aplicar la estabilidad de ABI en CI, no con buenas intenciones
Todos los proyectos afirman ser compatibles hacia atrás. Casi ninguno puede demostrarlo un martes cualquiera. El CI de libghostty ejecuta libabigail contra una línea base comprometida en Linux, comprobando cada cambio por deriva de ABI, y compara manifiestos de tipos de referencia en macOS y WebAssembly. Los símbolos exportados en plataformas ELF están versionados, así que el propio cargador se convierte en un mecanismo de aplicación. La promesa no se mantiene con revisiones de código y vigilancia; se mantiene con máquinas que fallan la build cuando una persona se equivoca.
Una ABI no es un contrato que firmas una vez. Es una promesa que tu CI tiene que cumplir en cada commit.
Esta es la pieza que le recomendaría a todo autor de bibliotecas copiar primero, antes de cualquier diseño de API. Comprobar la ABI automáticamente es barato de configurar (abidiff de libabigail es una sola herramienta) y convierte una promesa social difusa («intentamos no romper cosas») en un artefacto duro y revisable («aquí está la línea base; aquí está el diff; este cambio es o no es compatible»). Las distribuciones que deciden si empaquetar tu biblioteca, y las empresas que deciden si enlazarla dinámicamente, en realidad están evaluando ese artefacto. La razón por la que los mantenedores de Neovim esperaron a una versión etiquetada antes de hacer merge no es ceremonia: es que las distribuciones necesitan una dependencia versionada, empaquetable por separado, con una historia de compatibilidad que puedan defender.

Empaquetado y licencias: el trabajo aburrido que hace que las bibliotecas lleguen a producción
Pregunta a cualquier mantenedor de distribuciones qué mata las posibilidades de una biblioteca y rara vez dirá «el código». Es la build que no respeta --prefix o DESTDIR, el SONAME que falta, las dependencias vendorizadas con licencias poco claras, el tarball que no puede compilarse sin conexión. Libghostty 1.0 trata todo esto como parte de la superficie de la release: tarballs de código fuente firmados, un tarball complementario de dependencias en el formato de caché de Zig para builds totalmente offline, SONAMEs correctos, archivos pkg-config, configuraciones de paquete CMake, e información de depuración conservada por defecto para que las distros puedan eliminarla. Hay un PACKAGING-LIBGHOSTTY.md que viene dentro del tarball, escrito para quien empaqueta, no para el usuario final.
Las licencias recibieron el mismo tratamiento, y es más estratégico de lo que parece. La biblioteca es MIT, no necesita nada más que libc en tiempo de ejecución (y puede compilarse en modo freestanding sin siquiera eso) e incorpora unas pocas dependencias con licencias permisivas: simdutf y Google Highway para SIMD, una tabla compacta de Unicode, Wuffs para decodificar gráficos de Kitty, todo compilado sin libc++ para que no haya dependencia de la biblioteca estándar de C++. Cero copyleft en todo el árbol. Cada dependencia figura en un manifiesto legible por máquina con versión, licencia SPDX y hash, específicamente para que las distros puedan completar los metadatos de bibliotecas incluidas sin hacer arqueología. Incluso hay un flag de build para enlazar dinámicamente simdutf o Highway del sistema en su lugar.
Cada una de esas decisiones elimina una objeción concreta que plantearía un guardián específico. Eso es lo que significa «listo para empresas» en la práctica: no una página de ventas, sino cientos de pequeñas fricciones eliminadas antes de que alguien tuviera que preguntar. También es un recordatorio de por qué el buen software lleva tiempo: nada de este trabajo es difícil, y todo es lento.
Portabilidad y disciplina de recursos como promesas de API
La matriz de plataformas probadas abarca Linux (glibc y musl), macOS, iOS, FreeBSD, Windows, Android y WebAssembly freestanding, con un segundo nivel (RISC-V y ARM thumb bare-metal, WASI, Windows ARM64, illumos, x86 de 32 bits) que compila en CI pero todavía no ejecuta tests. Cada plataforma recibe los artefactos que espera su ecosistema: dylibs con @rpath y XCFrameworks para Apple, una DLL con PDB y biblioteca de importación para Windows (enlazado MSVC verificado en CI), una build de Android con páginas de 16 KB para Android 15+, y un módulo WASM de menos de un megabyte con todas las funcionalidades activadas, reducible a la mitad compilando sin subsistemas como búsqueda, selección y gráficos de Kitty, con todas las funciones aún exportadas y devolviendo GHOSTTY_UNSUPPORTED para que el código de quien la integra nunca tenga que cambiar.
Pero la historia de portabilidad a la que sigo volviendo es de comportamiento. La biblioteca no crea hilos. Solo asigna memoria a través de un allocator que tú proporcionas. El autor informa que ejecutó 10.000 terminales en vivo, cada una manejando una shell real que produce salida, en un servidor Linux de 4 núcleos y 8 GB, y señala que el cuello de botella fue el apetito de memoria de bash, no la biblioteca; tuvo que cambiar a dash para que las shells cupieran en RAM mientras libghostty-vt funcionaba sin problemas. «No creamos hilos» y «no nos adueñamos de tu allocator» son promesas de API tan reales como cualquier firma de función, y son lo que hace que una biblioteca pueda integrarse en contextos (motores de juegos, dispositivos embebidos, arneses de fuzzing, los event loops de otros) donde una dependencia aficionada a los hilos sería un impedimento.
Lo que libghostty enseña sobre arquitectura library-first
La comparación obvia es libvte, la biblioteca de emulación ligada a GTK que está debajo de GNOME Terminal, el terminal de XFCE y media docena más. Libvte demostró el modelo hace años (un núcleo compartido, muchos envoltorios finos), pero su acoplamiento con GTK redujo su mundo a escritorios Linux con un toolkit específico. La apuesta de libghostty es que el mismo modelo, desacoplado de cualquier toolkit de UI y endurecido como ABI C estable, llega mucho más lejos: a IDEs escritos en Java, editores escritos en C, TUIs escritas en Go, navegadores vía WASM y productos comerciales que nunca podrían incluir una dependencia de GTK. La evidencia temprana dice que la apuesta es acertada. Ya hay más personas usando un terminal con libghostty que usando el propio Ghostty, por un margen amplio.
La lección más profunda es sobre el orden de los pasos. Diseñar primero una biblioteca no significa escribirla antes de tener un caso de uso; eso es lo que produce abstracciones bonitas que nadie necesita. Ghostty hizo lo contrario: construyó una aplicación real, dejó que los límites del dominio emergieran bajo presión de producción y luego endureció la costura que había mantenido todo el tiempo. La API C llegó tarde, y precisamente por eso llegó limpia. Si tienes una aplicación con un núcleo realmente difícil y reutilizable (un parser, un emulador, un motor de layout, una pila de protocolos), el manual está a la vista: mantén el límite honesto desde el principio, expónlo mediante el contrato más estrecho posible, pon la ABI bajo vigilancia de CI y haz el trabajo tedioso de empaquetado en serio. Los efectos del ecosistema se acumulan a partir de ahí. Cada bug que reporta un integrador mejora el terminal de todos los demás consumidores, y cada protocolo nuevo llega a todas partes a la vez en lugar de fragmentarse en una docena de forks privados.
Hashimoto afirma que ahora se puede construir un terminal en unas 1.500 líneas de C que supera casi cualquier cosa que existiera hace un año. Normalmente archivaría esa frase bajo entusiasmo de mantenedor, salvo que más de cien proyectos rastreados y toda la flota de IDEs de JetBrains sugieren que la afirmación sobrevive al contacto con la realidad. La era de que cada aplicación escriba a mano su propio emulador de terminal quizá esté terminando, y está terminando como suelen terminar estas cosas: no con una mejor aplicación, sino con una mejor biblioteca.


