Articoli approfonditi sulla tecnologia che plasma il futuro.

Libghostty 1.0: lezioni su come progettare una C ABI stabile

Libghostty 1.0 mostra come progettare una C ABI stabile: handle opachi, setter con chiavi enum, versionamento dei simboli in CI e architettura library-first.

Illustrazione di un unico nucleo luminoso che alimenta molti schermi diversi in stile terminale, collegati da fili di luce.
Un unico nucleo di emulazione, molte facce: libghostty oggi sta dentro IDE, editor, TUI e nuovi terminali.

Immagina di far parte del team che gestisce il terminale negli IDE di JetBrains. Il tuo emulatore, JediTerm, ha un bug: il genere di problema in cui gli emulatori di terminale danno il meglio, con una sequenza di escape oscura che viene renderizzata male in un modo esasperante da riprodurre. Potresti correggerlo a mano. Oppure potresti eliminare un decennio di codice di emulazione accumulato e collegarti a una libreria C con ABI stabile, mantenuta, testata con il fuzzing e portata su nove sistemi operativi da qualcun altro. JetBrains ha scelto la seconda strada. Ogni utente di IntelliJ, PyCharm e GoLand, oltre 12,5 milioni di utenti attivi secondo i dati dello stesso JetBrains, oggi usa un terminale basato su libghostty, che questa settimana ha raggiunto la versione 1.0.

Questo è il numero di copertina, ma la storia più interessante sta sotto. Libghostty è il nucleo di emulazione del terminale estratto da Ghostty, il terminale accelerato via GPU di Mitchell Hashimoto, ed è stato rilasciato come libreria C autonoma con una policy di stabilità dell'ABI applicata. Un anno fa non aveva un'API C e aveva esattamente un consumatore. Oggi ha una 1.0 taggata, pacchetti pronti per la distribuzione e un elenco di adozioni che sembra un who's who degli strumenti per sviluppatori. Il percorso da "app con degli interni" a "libreria di cui l'industria si fida" è una lezione di disciplina ingegneristica che va ben oltre i terminali.

Da app a libreria: come è nato libghostty

L'emulazione del terminale è uno di quei problemi che da lontano sembrano semplici e da vicino sono silenziosamente brutali. Decenni di sequenze di escape, protocolli grafici in competizione, clustering dei grapheme Unicode, riflusso dello scrollback al ridimensionamento: ogni autore di terminali riscopre lo stesso campo minato. Ho già scritto di come funzionano i moderni terminali accelerati via GPU, dal parsing del TTY agli atlas di glifi, e il filo conduttore è sempre lo stesso: il livello di emulazione è il posto dove la correttezza va a morire. È esattamente il tipo di codice che vorresti scrivere una volta, testare fino allo sfinimento e condividere.

L'autore di Ghostty sembra averlo capito fin dall'inizio. L'applicazione è stata scritta in Zig, con un nucleo di emulazione strutturato in modo da poter essere separato: prima come modulo Zig, poi dietro un'API C, e oggi come libghostty-vt 1.0 con un ciclo di rilascio proprio, tarball propri e consumatori propri. L'estrazione non è stata un ripensamento né un gesto di marketing: il progetto ha annunciato l'intento più di un anno prima che esistesse l'API C, e poi ha passato quell'anno a rendere reale il confine. L'ordine delle operazioni conta: la libreria non è stata promossa a 1.0 quando il codice funzionava, ma quando il contratto attorno al codice era abbastanza stabile da poterci promettere qualcosa.

L'elenco dei consumatori suggerisce che la scommessa ha pagato. Neovim ha una pull request approvata che sostituisce libvterm con libghostty-vt, una modifica che chiude una issue di dieci anni fa sul riflusso dello scrollback al ridimensionamento: un segno di quanto restino aperte certe ferite quando ogni progetto mantiene il proprio emulatore. Gli sviluppatori di KDE stanno prototipando un successore di Konsole basato su di essa. Il Turborepo di Vercel la usa per mostrare l'output dei task. Antithesis l'ha usata per fare fuzzing dei programmi TUI e ha portato alla luce bug reali in btop. Qualcuno ha costruito un terminale per Emacs su di essa, ed esiste una build WebAssembly con un'API compatibile con xterm.js. Esistono binding della community per Rust, Go, JavaScript, Swift, Python, .NET, Elixir, Dart e Java.

Progettare una C ABI stabile: handle opachi e chiavi enum

Ecco la parte che vale la pena rubare per i tuoi progetti. La maggior parte delle librerie C non invecchia bene non perché il codice marcisca, ma perché l'ABI si irrigidisce: una struct guadagna un campo e ogni consumatore va ricompilato, la firma di una funzione cambia e i simboli scompaiono, un enum cresce e i valori si spostano. Il design di libghostty è una piccola lezione magistrale su come evitare tutti e tre i problemi, e le tecniche sono vecchie, collaudate e cronicamente sottoutilizzate.

/* 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);

Tre decisioni fanno la parte pesante. Primo, ogni oggetto è un handle opaco: i chiamanti tengono puntatori, mai struct, così la libreria può rimodellare liberamente i propri interni tra una release e l'altra. Secondo, i centinaia di valori leggibili e scrivibili stanno dietro un piccolo insieme di getter e setter con chiavi enum. Una nuova funzionalità significa una nuova costante enum, non un nuovo simbolo esportato, e un programma compilato con header più recenti ma eseguito con una libreria più vecchia riceve un risultato pulito GHOSTTY_UNSUPPORTED invece di un crash o di dati spazzatura. Questo dettaglio fa la differenza tra un degrado elegante e un segfault alle 3 di notte nel prodotto di qualcun altro.

Terzo, le poche struct che sono pubbliche portano con sé la propria dimensione, oppure riservano del padding, così i campi possono essere aggiunti senza rompere il layout: lo stesso trucco che sockaddr e l'API Win32 usano da decenni. Gli enum sono fissati a int su ogni compilatore, nei limiti consentiti dallo standard C, perché un enum il cui tipo sottostante cambia tra compilatori è una bomba a orologeria per l'ABI. Niente di tutto questo è esotico. È tutto ciò che fai solo se decidi, fin dal primo giorno, che l'ABI è una funzionalità del prodotto e non un incidente della struttura attuale del sorgente. Questo è il divario tra specifica e implementazione nella sua forma più pura: l'ABI è la specifica, e tutto il resto è negoziabile.

  • Handle opachi per tutto. I chiamanti non vedono mai il layout, quindi il layout è libero di cambiare.
  • Getter e setter con chiavi enum. Nuove impostazioni sono nuove costanti, non nuovi simboli, e le vecchie librerie rispondono GHOSTTY_UNSUPPORTED invece di crashare.
  • Struct pubbliche che si dimensionano da sole. Un campo struct_size permette di aggiungere campi in seguito; il padding riservato offre spazio per il futuro.
  • Tipi enum fissati. Gli enum sono fissati a int, così l'ABI non cambia da un compilatore all'altro.
  • Simboli versionati su ELF. Il loader dinamico rifiuta una libreria non compatibile per nome, in modo esplicito, al caricamento e non in modo misterioso a runtime.

Far rispettare la stabilità dell'ABI in CI, non affidandosi alle buone intenzioni

Ogni progetto dichiara compatibilità all'indietro. Quasi nessuno riesce a dimostrarlo un martedì qualunque. La CI di libghostty esegue libabigail contro una baseline committata su Linux, controllando ogni modifica per eventuali derive dell'ABI, e confronta i manifest di tipi di riferimento su macOS e WebAssembly. I simboli esportati sulle piattaforme ELF sono versionati, quindi il loader stesso diventa un meccanismo di applicazione. La promessa non è mantenuta dalla code review e dalla vigilanza: è mantenuta da macchine che fanno fallire la build quando un essere umano sbaglia.

Un'ABI non è un contratto che firmi una volta sola. È una promessa che la tua CI deve mantenere a ogni singolo commit.

Questo è il pezzo che consiglierei a ogni autore di librerie di copiare per primo, prima ancora del design dell'API. Il controllo automatico dell'ABI costa poco da configurare (abidiff di libabigail è un singolo strumento) e trasforma una vaga promessa sociale ("cerchiamo di non rompere niente") in un artefatto rigido e verificabile ("ecco la baseline; ecco il diff; questa modifica è compatibile o non lo è"). Le distribuzioni che decidono se impacchettare la tua libreria, e le aziende che decidono se collegarla dinamicamente, stanno in realtà valutando quell'artefatto. Il motivo per cui i manutentori di Neovim aspettavano una release taggata prima di fare il merge non è un formalismo: le distribuzioni hanno bisogno di una dipendenza versionata, pacchettizzabile separatamente, con una storia di compatibilità che possano difendere.

Una figura di guardia che misura un ponte di pietra all'ingresso, controllandolo prima di concedere il passaggio.
L'stabilità dell'ABI applicata come un checkpoint: ogni modifica viene misurata rispetto alla baseline prima di passare.

Packaging e licenza: il lavoro noioso che fa arrivare le librerie agli utenti

Chiedi a un manutentore di distribuzione cosa uccide le possibilità di una libreria e difficilmente ti dirà "il codice". Sono la build che non rispetta --prefix o DESTDIR, il SONAME mancante, le dipendenze vendorizzate con licenze poco chiare, la tarball che non si compila offline. Libghostty 1.0 tratta tutto questo come superficie di rilascio: tarball sorgenti firmate, una tarball companion delle dipendenze nel layout di cache di Zig per build completamente offline, SONAME corretti, file pkg-config, configurazioni di pacchetto CMake, e debug info mantenute di default così le distro possono rimuoverle. C'è un PACKAGING-LIBGHOSTTY.md che viene distribuito nella tarball, scritto per chi impacchetta, non per l'utente finale.

La licenza ha ricevuto lo stesso trattamento, ed è più strategica di quanto sembri. La libreria è MIT, non richiede nulla oltre libc a runtime (e può essere compilata in modalità freestanding senza nemmeno quella), e include poche dipendenze con licenze permissive: simdutf e Google Highway per SIMD, una tabella Unicode compatta, Wuffs per la decodifica della grafica Kitty, il tutto compilato senza libc++, quindi senza dipendenze dalla libreria standard C++. Nessun copyleft in tutto l'albero. Ogni dipendenza è elencata in un manifest leggibile dalla macchina con versione, licenza SPDX e hash, proprio perché le distro possano compilare i metadati delle librerie incluse senza archeologia. Esiste persino un flag di build per collegare dinamicamente simdutf o Highway di sistema.

Ognuna di queste scelte rimuove un'obiezione specifica che un determinato controllore avrebbe sollevato. È questo che significa davvero "pronto per l'enterprise" nella pratica: non una pagina di vendita, ma un centinaio di piccoli attriti eliminati prima che qualcuno dovesse chiedere. È anche un promemoria del perché il software di qualità richiede tempo: nessuno di questi lavori è difficile, ma tutti sono lenti.

Portabilità e disciplina sulle risorse come promesse dell'API

La matrice di piattaforme testate comprende Linux (glibc e musl), macOS, iOS, FreeBSD, Windows, Android e WebAssembly freestanding, con un secondo livello (RISC-V e ARM thumb bare-metal, WASI, Windows ARM64, illumos, x86 a 32 bit) che viene compilato in CI ma non esegue ancora i test. Ogni piattaforma riceve gli artefatti che il suo ecosistema si aspetta: dylib con @rpath e XCFramework per Apple, una DLL con PDB e import library per Windows (linking MSVC verificato in CI), una build Android con pagine da 16 KB per Android 15+, e un modulo WASM sotto il megabyte con tutte le funzionalità attive, riducibile escludendo sottosistemi come ricerca, selezione e grafica Kitty, con ogni funzione comunque esportata e che restituisce GHOSTTY_UNSUPPORTED, così il codice di chi la integra non deve mai cambiare.

Ma la storia della portabilità a cui continuo a tornare è comportamentale. La libreria non crea thread. Alloca solo tramite un allocatore fornito da chi la usa. L'autore riporta di aver fatto girare 10.000 terminali live, ciascuno con una shell reale che produce output, su un server Linux con 4 core e 8 GB di RAM, e nota che il collo di bottiglia era la fame di memoria di bash, non la libreria: ha dovuto passare a dash per far stare le shell in RAM mentre libghostty-vt andava avanti senza problemi. "Non creiamo thread" e "non possediamo il tuo allocatore" sono promesse di API reali quanto qualsiasi firma di funzione, ed è proprio ciò che rende una libreria integrabile in contesti come motori di gioco, dispositivi embedded, harness di fuzzing o event loop altrui, dove una dipendenza che abusa dei thread sarebbe un ostacolo insormontabile.

Cosa insegna libghostty sull'architettura library-first

Il paragone ovvio è libvte, la libreria di emulazione legata a GTK che sta sotto GNOME Terminal, al terminale di XFCE e a una mezza dozzina di altri. libvte ha dimostrato il modello anni fa (un nucleo condiviso, tanti wrapper sottili), ma il suo accoppiamento con GTK ne ha ristretto il mondo ai desktop Linux con un toolkit specifico. La scommessa di libghostty è che lo stesso modello, disaccoppiato da qualsiasi toolkit grafico e irrobustito in un'ABI C stabile, viaggi molto più lontano: negli IDE scritti in Java, negli editor scritti in C, nelle TUI scritte in Go, nei browser via WASM e nei prodotti commerciali che non potrebbero mai includere una dipendenza da GTK. Le prime evidenze dicono che la scommessa è giusta. Più persone usano già un terminale basato su libghostty di quante ne usino Ghostty stesso, di un buon multiplo.

La lezione più profonda riguarda il sequenziamento. Architettura library-first non significa scrivere una libreria prima di avere un caso d'uso: è così che ottieni astrazioni bellissime di cui nessuno ha bisogno. Ghostty ha fatto l'opposto: ha costruito un'applicazione vera, ha lasciato che i confini del dominio emergessero sotto la pressione della produzione e poi ha irrobustito la giuntura che aveva mantenuto per tutto il tempo. L'API C è arrivata tardi, ed è proprio per questo che è arrivata pulita. Se hai un'applicazione con un nucleo riutilizzabile e davvero difficile (un parser, un emulatore, un motore di layout, uno stack di protocollo), il playbook è chiaro: mantieni il confine onesto fin dall'inizio, esponilo attraverso il contratto più stretto possibile, metti l'ABI sotto sorveglianza CI e fai il lavoro noioso di packaging sul serio. Gli effetti sull'ecosistema si compongono da lì. Ogni bug segnalato da un integratore rende migliore il terminale di tutti gli altri consumatori, e ogni nuovo protocollo arriva ovunque nello stesso momento invece di frammentarsi in una dozzina di fork privati.

Hashimoto sostiene che oggi si possa costruire un terminale in circa 1.500 righe di C che supera quasi tutto ciò che esisteva un anno fa. Normalmente archivierei una frase così sotto entusiasmo da manutentore, se non fosse che più di cento progetti tracciati e l'intera flotta di IDE di JetBrains suggeriscono che l'affermazione regge al contatto con la realtà. L'era in cui ogni applicazione scrive a mano il proprio emulatore di terminale potrebbe finalmente essere finita, e sta finendo nel modo in cui di solito finiscono queste cose: non con un'applicazione migliore, ma con una libreria migliore.