libghostty-vt 1.0: 터미널 도구에 붙이기 전 ABI·렌더링·배포 점검하기

바이트 스트림을 터미널 상태로 해석하는 공용 엔진과 여러 화면을 표현한 AI 생성 개념 일러스트. 실제 제품 화면이나 성능 측정 결과가 아니다.

웹 콘솔이나 IDE 안에 터미널을 넣을 때, 텍스트를 화면에 출력하는 것만으로는 충분하지 않다. 커서 이동, 화면 지우기, 한글과 이모지의 너비, 창 크기 변경, 스크롤백까지 같은 입력을 일관된 화면 상태로 해석해야 한다.

11월 6일 공개된 libghostty-vt 1.0은 이 해석 엔진을 재사용하려는 개발자에게 중요한 전환점이다. Ghostty에서 분리된 C 라이브러리가 안정적인 C ABI를 약속하기 시작했다. 애플리케이션 Ghostty와는 별도 릴리스이며, 공식 저장소에도 vt-1.0.0 태그가 공개됐다. 공식 발표, 1.0.0 태그

이 글은 터미널을 포함한 개발 도구를 만들거나 TUI 출력을 자동으로 검사하는 팀을 위한 도입 점검이다. 라이브러리를 실제로 빌드하거나 벤치마크한 실습기는 아니며, 아래 명령과 검증 목록은 대상 환경에서 실행할 절차다.

어디까지 라이브러리가 맡는가

libghostty-vt는 프로그램이 출력한 바이트를 받아 화면 셀, 커서, 스크롤백 등의 상태로 바꾼다. 입력은 PTY, 네트워크 연결, 저장된 세션에서 올 수 있다. 공식 문서는 터미널 앱뿐 아니라 세션 재생, TUI 테스트, 화면을 읽는 자동화도 활용 예로 든다. 라이브러리 소개

프로젝트에서는 다음 세 영역의 담당을 먼저 정하는 편이 좋다.

입출력 연결: 셸 프로세스의 시작과 종료, PTY 또는 원격 연결, 인증과 접근 권한.

터미널 해석: 출력 바이트를 받아 커서와 셀 상태를 갱신하는 libghostty-vt.

사용자 경험: 폰트, 화면 그리기, 키보드 포커스, 접근성, 연결이 끊겼을 때의 안내.

이 구분은 도입 설계를 위한 제안이다. 라이브러리를 연결한 뒤에도 원격 세션의 수명과 권한 정책을 애플리케이션이 책임져야 한다. 도입 범위를 작게 잡으려면 먼저 저장된 출력으로 읽기 전용 뷰어나 테스트 도구를 만들고, 이후 실제 셸 연결을 붙일 수 있다.

ABI 안정성의 방향을 정확히 읽기

API가 소스 코드에서 호출하는 약속이라면 ABI는 이미 컴파일된 프로그램과 라이브러리가 만나는 약속이다. 동적 링크에서는 빌드할 때 본 헤더와 실행할 때 로드된 파일의 버전이 달라질 수 있다.

공식 안정성 정책은 어떤 1.x 버전에 맞춰 빌드한 프로그램이 이후 1.x 라이브러리에서도 동작하는 방향을 보장한다. 반대로 더 새로운 함수에 의존하는 프로그램을 오래된 라이브러리에 연결하는 경우까지 자동으로 해결되지는 않는다. 새 함수 자체가 없을 수 있기 때문이다. 또 스냅샷의 바이트 형식은 별도로 버전 관리되며 ABI 보장에 포함되지 않는다. Stability

GHOSTTY_UNSUPPORTED의 의미도 구분해야 한다. 기존 함수에 새 옵션 키를 전달했거나 빌드에서 기능을 제외한 경우에 받을 수 있는 결과다. 이를 모든 버전 불일치를 해결하는 장치로 해석하면 안 된다. 반환값을 무시하지 말고 필수 기능은 초기화 단계에서 확인한다. API Conventions

운영 로그에는 애플리케이션 버전과 함께 헤더 버전, 실제 라이브러리 버전, 필요한 기능을 남기는 것이 좋다. 문제가 생겼을 때 “1.0으로 빌드했다”는 정보와 “배포 환경에서 무엇을 로드했다”는 정보를 따로 비교할 수 있다.

설치와 빌드 경로를 섞지 않기

공식 패키징 안내는 라이브러리 전용 소스 묶음과 같은 버전의 의존성 묶음을 사용하도록 한다. GitHub 자동 생성 아카이브와 공식 배포 파일은 동일하지 않다. 1.0.0 빌드에는 Zig 0.17.x가 필요하며, --system에 준비한 의존성 디렉터리를 지정하면 빌드 중 패키지를 인터넷에서 가져오지 않는다. 서명과 체크섬 확인은 다운로드가 끝난 뒤 별도로 수행해야 한다. 다른 버전을 도입할 때는 그 릴리스에 포함된 패키징 문서를 기준으로 삼는다. 패키징 안내

애플리케이션에서 이미 설치된 라이브러리를 찾을 때와 소스를 함께 빌드할 때도 구분한다. 설치된 패키지를 쓰는 최소 CMake 구성은 다음과 같다.

이 구성은 라이브러리를 설치해 주지 않는다. 먼저 배포판 패키지나 검증한 빌드 산출물이 있어야 한다. 별도 설치 경로라면 CMAKE_PREFIX_PATH를 맞춘다. 소스를 받는 FetchContent 경로는 빌드 시 Zig가 필요하고 배포 파일의 해시도 고정해야 한다. CMake 지원 안내

probe.c는 복잡한 화면을 만들기 전에 링크와 로딩 경로부터 확인하는 용도다.

위 실행 경로는 일반적인 Unix 계열의 단일 구성 빌드 예다. Windows나 다중 구성 생성기에서는 실행 파일 위치가 달라질 수 있다. 출력 버전이 같다고 전체 통합이 검증된 것은 아니다. 이 단계는 의도한 라이브러리를 찾고 로드하는지 확인하는 첫 검사다.

바이트 입력과 화면 갱신에서 놓치기 쉬운 것

네트워크나 파이프의 한 번의 읽기가 한 글자나 한 제어 시퀀스와 일치할 필요는 없다. 공식 시작 안내는 UTF-8 문자와 제어 시퀀스가 여러 ghostty_terminal_vt_write() 호출에 나뉘어 들어와도 파서가 상태를 이어간다고 설명한다. 따라서 앞단에서 임의로 줄 단위 디코딩이나 제어 문자 삭제를 해 버리지 않도록 확인한다. 첫 터미널 만들기

정적인 화면을 텍스트로 내보낼 때는 formatter가 유용하다. 실시간 렌더러는 RenderState의 갱신·그리기·정리 흐름을 사용한다. 한 번 읽은 행과 셀 정보는 다음 갱신 이후까지 보관하면 안 된다. 테스트에서는 같은 바이트열을 통째로 전달했을 때와 여러 조각으로 나눴을 때의 최종 화면을 비교해 볼 수 있다.

스레드 안전성도 호출자가 설계해야 한다. 라이브러리가 자체 스레드를 만들지는 않으며, 같은 핸들이나 거기서 빌린 핸들을 동시에 사용해서는 안 된다. 반환된 버퍼와 빌린 참조의 수명을 구분하고, formatter보다 terminal을 먼저 해제하지 않는 등 문서의 소유권 규칙을 지킨다. 스레드와 핸들 규칙

화면 표시와 외부 동작의 권한 분리

터미널 출력도 외부 입력이다. 공식 안내는 기본 파싱과 별개로 클립보드 접근, 이미지의 파일·공유 메모리 로딩 같은 기능을 켤 때 주의를 요구한다. 출력에서 읽어 온 창 제목 역시 신뢰할 수 없는 데이터로 취급해야 한다. 입력과 부수 효과의 경계

실무에서는 표시 기능을 먼저 붙인 뒤 필요한 외부 동작만 허용하는 순서가 좋다. 예를 들어 웹 터미널에서 클립보드 접근 요청이 들어왔다고 서버 권한으로 파일을 읽거나 브라우저 권한을 자동 승인해서는 안 된다. 각 동작을 어느 프로세스가 수행하는지, 어떤 사용자 동의를 받는지 문서로 남긴다.

특히 AI 도구가 TUI 화면을 읽는다면 터미널 출력 안의 문장을 실행 지시로 승격하지 않아야 한다. 화면 해석 결과는 관찰 자료로 전달하고, 실제 명령 실행의 허용 범위는 별도의 정책과 사용자 요청으로 결정하는 설계가 필요하다.