다음에 올 것을 만들어가는 기술에 대한 심층 기사.

Libghostty 1.0: 안정적인 C ABI 설계의 교훈

Libghostty 1.0으로 배우는 안정적인 C ABI 설계: 불투명 핸들, enum 키 setter, CI 기반 심볼 버전 관리와 라이브러리 우선 아키텍처.

하나의 공유된 빛나는 코어가 빛의 실로 연결된 여러 터미널 같은 화면에 동력을 공급하는 일러스트.
하나의 에뮬레이션 코어, 여러 얼굴: libghostty는 이제 IDE, 에디터, TUI, 새로운 터미널 안에서 모두 동작합니다.

JetBrains IDE의 터미널을 담당하는 팀에 있다고 상상해 보세요. 자체 에뮬레이터인 JediTerm에 버그가 있습니다. 터미널 에뮬레이터가 주로 다루는, 재현하기 어렵고 답답한 종류의 버그입니다. 특정 이스케이프 시퀀스가 엉뚱하게 렌더링되는데, 원인을 찾기가 쉽지 않습니다. 직접 패치할 수도 있지만, 10년 동안 쌓인 에뮬레이션 코드를 걷어내고 다른 팀이 유지보수하고 퍼징하며 아홉 개 운영체제에 맞춰 포팅해 준 안정적인 ABI의 C 라이브러리에 링크하는 방법도 있습니다. JetBrains는 두 번째를 택했습니다. JetBrains 자체 발표에 따르면 IntelliJ, PyCharm, GoLand 사용자 1,250만 명 이상이 이제 libghostty로 구동되는 터미널을 씁니다. 그리고 libghostty가 이번 주에 1.0에 도달했습니다.

이 숫자가 헤드라인이지만, 더 흥미로운 이야기는 그 아래에 있습니다. Libghostty는 Mitchell Hashimoto의 GPU 가속 터미널 Ghostty에서 떼어낸 터미널 에뮬레이션 코어이고, 엄격한 ABI 안정성 정책과 함께 독립형 C 라이브러리로 공개되었습니다. 1년 전만 해도 C API가 없었고 사용처도 딱 하나였습니다. 지금은 태그가 붙은 1.0 릴리스, 배포 가능한 패키징, 개발자 도구 업계의 명단처럼 읽히는 채택 목록을 갖추고 있습니다. “내부 구조가 있는 앱”에서 “업계가 신뢰하는 라이브러리”로 가는 과정은 터미널을 넘어 훨씬 넓은 영역에 적용되는 엔지니어링 규율의 교훈입니다.

앱에서 라이브러리로: libghostty는 어떻게 분리되었나

터미널 에뮬레이션은 멀리서 보면 쉬워 보이지만 가까이서 보면 조용히 가혹한 문제 영역입니다. 수십 년 된 이스케이프 시퀀스, 경쟁하는 그래픽 프로토콜, 유니코드 그래핌 클러스터링, 리사이즈 시 스크롤백 리플로우 같은 문제가 있고, 터미널을 만드는 사람은 누구나 같은 지뢰밭을 다시 밟습니다. 제가 전에 최신 GPU 가속 터미널이 어떻게 동작하는지, TTY 파싱부터 글리프 아틀라스까지 다룬 적이 있는데, 그때 반복해서 드러난 주제는 에뮬레이션 계층이 바로 정확성이 죽어 나가는 곳이라는 것이었습니다. 한 번 잘 작성하고, 죽을 때까지 테스트하고, 공유하고 싶은 코드가 바로 이런 종류입니다.

Ghostty의 작성자는 처음부터 이 점을 이해한 것으로 보입니다. 애플리케이션은 Zig로 만들어졌고, 에뮬레이션 코어는 분리될 수 있도록 구성되었습니다. 처음에는 Zig 모듈로, 그다음에는 C API 뒤에서, 지금은 자체 릴리스 주기, 자체 타볼, 자체 소비자를 가진 libghostty-vt 1.0으로 나왔습니다. 이 분리는 뒤늦은 생각이나 마케팅 제스처가 아니었습니다. 프로젝트는 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의 설계는 이 세 가지를 모두 피하는 방법을 보여 주는 짧은 마스터클래스입니다. 사용된 기법은 오래되고 검증되었지만 만성적으로 충분히 쓰이지 않습니다.

/* 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 키 getter와 setter 집합 뒤에 있습니다. 새로운 기능은 새로운 exported 심볼이 아니라 새로운 enum 상수를 의미합니다. 최신 헤더로 빌드된 프로그램이 구버전 라이브러리에서 실행되면 충돌이나 잘못된 값 대신 깔끔하게 GHOSTTY_UNSUPPORTED 결과를 받습니다. 이 세부 사항 하나가 우아한 성능 저하와 다른 사람의 제품에서 새벽 3시에 터지는 세그멘테이션 폴트의 차이를 만듭니다.

셋째, 공개된 구조체는 소수이지만, 각자 자신의 크기를 담거나 패딩을 예약해 두어서 레이아웃을 깨지 않고 필드를 덧붙일 수 있습니다. sockaddr와 Win32 API가 수십 년 동안 써 온 방식과 같은 기법입니다. C 표준이 허용하는 범위에서 enum은 모든 컴파일러에서 int로 고정됩니다. 컴파일러마다 enum의 기저 타입이 바뀌면 ABI 시한폭탄이 되기 때문입니다. 이 중 어느 것도 특이한 기법은 아닙니다. 모두 ABI를 현재 소스 구조의 우연이 아니라 첫날부터 제품 기능으로 여기기로 결정했을 때만 하는 일입니다. 이것은 가장 순수한 형태의 명세와 구현의 간극입니다. ABI가 곧 명세이고, 나머지는 협상 가능한 부분입니다.

  • 모든 것에 불투명 핸들 사용. 호출자는 레이아웃을 보지 못하므로, 레이아웃은 자유롭게 바뀔 수 있습니다.
  • enum 키 getter와 setter. 새 설정은 새 심볼이 아니라 새 상수이며, 구버전 라이브러리는 충돌하는 대신 GHOSTTY_UNSUPPORTED를 반환합니다.
  • 크기를 담는 공개 구조체. struct_size 필드 덕분에 나중에 필드를 덧붙일 수 있고, 예약된 패딩이 미래의 여유 공간이 됩니다.
  • 고정된 enum 타입. enum을 int로 고정해 컴파일러가 달라져도 ABI가 바뀌지 않도록 합니다.
  • ELF의 버전화된 심볼. 동적 로더가 로드 시점에 맞지 않는 라이브러리를 이름과 함께 명확하게 거부하므로, 런타임에 알 수 없는 방식으로 실패하지 않습니다.

좋은 의도가 아니라 CI에서 ABI 안정성 강제하기

모든 프로젝트가 하위 호환성을 주장합니다. 하지만 아무 화요일이나 골라 그것을 증명할 수 있는 프로젝트는 거의 없습니다. Libghostty의 CI는 리눅스에서 커밋된 기준선을 대상으로 libabigail을 실행해 모든 변경의 ABI 드리프트를 점검하고, macOS와 WebAssembly에서는 골든 타입 매니페스트를 비교합니다. ELF 플랫폼에서 exported 심볼은 버전이 지정되어 있어서, 로더 자체가 강제 메커니즘이 됩니다. 이 약속은 코드 리뷰와 경계심으로 지켜지는 것이 아니라, 사람이 실수하면 빌드를 실패시키는 기계로 지켜집니다.

ABI는 한 번 서명하고 끝나는 계약이 아닙니다. 커밋마다 CI가 지켜 내야 하는 약속입니다.

API 설계보다 먼저, 모든 라이브러리 작성자가 가장 먼저 복사해 갔으면 하는 부분이 바로 이것입니다. 자동화된 ABI 검사는 설정하기 저렴합니다. libabigail의 abidiff는 도구 하나면 충분합니다. 그리고 모호한 사회적 약속(“되도록 깨지 않으려고 노력합니다”)을 명확하고 검토 가능한 산출물(“기준선이 여기 있고, 차이가 여기 있으며, 이 변경은 호환되거나 호환되지 않습니다”)로 바꿔 줍니다. 여러분의 라이브러리를 패키징할지 결정하는 배포판과, 동적으로 링크할지 결정하는 기업은 실제로 이 산출물을 평가하고 있는 것입니다. Neovim 메인테이너들이 병합 전에 태그된 릴리스를 기다린 이유도 형식적인 절차 때문이 아닙니다. 배포판에는 버전이 붙고 별도로 패키징할 수 있으며, 스스로 근거를 댈 수 있는 호환성 이야기가 있는 의존성이 필요하기 때문입니다.

돌다리 입구에서 다리를 측정하며 통과를 허락하기 전에 점검하는 경비병 모습의 일러스트.
체크포인트처럼 강제되는 ABI 안정성: 모든 변경은 통과하기 전에 기준선과 비교됩니다.

패키징과 라이선스: 라이브러리를 실제로 배포하게 만드는 지루한 작업

배포판 메인테이너에게 라이브러리의 성패를 무엇이 가르는지 물어보면 “코드”라고 답하는 경우는 드뭅니다. 답은 --prefix나 DESTDIR를 존중하지 않는 빌드, 빠진 SONAME, 라이선스가 불분명한 벤더링된 의존성, 오프라인에서 빌드할 수 없는 타볼 같은 것들입니다. Libghostty 1.0은 이 모든 것을 릴리스 표면으로 다룹니다. 서명된 소스 타볼, 완전한 오프라인 빌드를 위해 Zig 캐시 레이아웃으로 된 의존성 타볼, 올바른 SONAME, pkg-config 파일, CMake 패키지 설정, 배포판이 제거할 수 있도록 기본으로 유지되는 디버그 정보가 포함됩니다. 최종 사용자가 아니라 패키저를 위해 작성된 PACKAGING-LIBGHOSTTY.md도 있으며, 이 파일은 타볼 안에 들어 있습니다.

라이선스도 같은 방식으로 다뤄졌는데, 겉보기보다 전략적입니다. 이 라이브러리는 MIT 라이선스이며, 런타임에는 libc 외에 아무것도 필요하지 않고(libc 없이 freestanding으로도 빌드할 수 있습니다), SIMD를 위한 simdutf와 Google Highway, 압축된 유니코드 테이블, Kitty 그래픽 디코딩을 위한 Wuffs 등 몇 개의 관대한 라이선스 의존성을 포함합니다. libc++ 없이 빌드되어 C++ 표준 라이브러리 의존성도 없습니다. 트리 안에 카피레프트 라이선스는 하나도 없습니다. 모든 의존성은 버전, SPDX 라이선스, 해시가 담긴 기계 판독 가능한 매니페스트에 나열되어 있어서, 배포판이 번들 라이브러리 메타데이터를 고고학적으로 파헤치지 않고 채울 수 있습니다. 번들된 simdutf나 Highway 대신 시스템 라이브러리를 동적으로 링크하는 빌드 플래그도 있습니다.

이 선택들은 하나하나가 특정 문지기가 제기했을 특정 반론을 제거합니다. 실무에서 “엔터프라이즈 준비 완료”가 실제로 뜻하는 바가 바로 이것입니다. 영업 페이지가 아니라, 누군가 묻기 전에 수많은 작은 마찰을 미리 갈아 없앤 결과입니다. 이것은 좋은 소프트웨어에 시간이 걸리는 이유를 상기시키기도 합니다. 이 작업들은 어렵지 않지만, 모두 느리게 진행됩니다.

API 약속으로서의 이식성과 리소스 규율

테스트된 플랫폼 목록은 Linux(glibc와 musl), macOS, iOS, FreeBSD, Windows, Android, freestanding WebAssembly를 포함합니다. 두 번째 등급에는 베어메탈 RISC-V와 ARM thumb, WASI, Windows ARM64, illumos, 32비트 x86이 있는데, 이들은 CI에서 빌드되지만 아직 테스트를 실행하지는 않습니다. 각 플랫폼은 해당 생태계가 기대하는 산출물을 받습니다. Apple용으로는 @rpath를 가진 dylib과 XCFramework, Windows용으로는 PDB와 import 라이브러리가 포함된 DLL(MSVC 링크는 CI에서 검증됨), Android 15 이상을 위한 16KB 페이지 크기 Android 빌드, 모든 기능을 켰을 때 1MB 미만인 WASM 모듈이 제공됩니다. 이 모듈은 검색, 선택, Kitty 그래픽 같은 하위 시스템을 컴파일에서 제외해 크기를 줄일 수 있습니다. 이때도 모든 함수는 여전히 exported 상태이고 GHOSTTY_UNSUPPORTED를 반환하므로, 임베더의 코드는 바꿀 필요가 없습니다.

하지만 제가 계속 다시 생각하게 되는 이식성 이야기는 동작에 관한 것입니다. 이 라이브러리는 스레드를 만들지 않습니다. 사용자가 제공하는 할당자를 통해서만 메모리를 할당합니다. 작성자는 4코어, 8GB 메모리의 리눅스 서버에서 실제 셸을 구동해 출력을 만드는 1만 개의 실시간 터미널을 실행했다고 보고합니다. 병목은 라이브러리가 아니라 bash의 메모리 소비였고, 라이브러리인 libghostty-vt가 여유롭게 돌아가는 동안 셸들을 RAM에 올리기 위해 dash로 바꿔야 했다고 합니다. “우리는 스레드를 생성하지 않습니다”와 “우리는 여러분의 할당자를 소유하지 않습니다”는 어떤 함수 시그니처만큼이나 실질적인 API 약속이며, 게임 엔진, 임베디드 기기, 퍼징 하네스, 다른 사람의 이벤트 루프처럼 스레드를 많이 쓰는 의존성이라면 치명적일 수 있는 환경에서도 라이브러리를 임베드할 수 있게 만드는 요소입니다.

Libghostty가 가르쳐 주는 라이브러리 우선 아키텍처

가장 당연한 비교 대상은 GNOME Terminal, XFCE 터미널, 그 밖에 여러 터미널의 기반인 libvte입니다. 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 전체 사용자 기반을 보면, 이 주장은 현실과 부딪혀도 살아남는 것으로 보입니다. 모든 애플리케이션이 터미널 에뮬레이터를 직접 손으로 만드는 시대가 마침내 끝나고 있을지도 모릅니다. 그리고 그 끝은 이런 일들이 보통 그렇듯 더 나은 애플리케이션이 아니라 더 나은 라이브러리를 통해 찾아왔습니다.