Ghostty libghostty-vt C 库入门：c-vt 示例的完整解析与构建实践

Ghostty 除了是终端模拟器本体，还从核心代码中抽离出了一个独立的 C 语言虚拟终端库 libghostty-vt。本文以仓库中的 c-vt 示例 为主体，完整讲解如何用任意 C 工具链消费这个标准 C 库：从 ghostty_osc_* 解析器 API 的调用顺序，到示例程序逐行代码分析，再到示例项目 build.zig 的构建细节与运行方式，帮助读者在自己的项目中嵌入 Ghostty 的终端转义序列解析能力。

1. 示例的定位：标准 C 库的最小用法

c-vt 示例 是 Ghostty 仓库 example/ 目录下的一组示例项目之一，官方描述为：

This contains a simple example of how to use the ghostty-vt C library with a C program.

这个示例只做了两件事：创建 OSC（Operating System Command）解析器 和 逐字节喂入一个"修改窗口标题"的 OSC 序列，最终提取出解析得到的命令类型和标题字符串。它的价值在于展示了一个完整的、可运行的最小调用闭环，是理解 libghostty-vt 其余 API（SGR 解析、Terminal 状态机、渲染状态等）的入门路径。

需要强调的是 README 中的另一段关键说明：

This uses a build.zig and Zig to build the C program so that we can reuse a lot of our build logic and depend directly on our source tree, but Ghostty emits a standard C library that can be used with any C tooling.

也就是说，示例之所以用 Zig 构建，仅仅是为了复用仓库的构建逻辑、直接依赖源码树；而 Ghostty 产出的是一个标准 C 库，你可以用 GCC、Clang、CMake 等任何 C 工具链来链接和使用它，Zig 并不是前提条件。

2. 运行方式

README 给出的操作步骤只有两条命令：

cd example/c-vt
zig build run

zig build run 会先编译出名为 c_vt 的可执行文件（build.zig 中通过 b.addExecutable 指定，可执行名使用下划线而非连字符，这是 example/AGENTS.md 中约定的命名规范），然后立即运行它。成功运行的程序会输出两行：

Command type: 1
Extracted title: hello

其中 1 对应枚举值 GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_TITLE（修改窗口标题命令，见 osc.h 中的 GhosttyOscCommandType 枚举定义），hello 是从 OSC 序列中还原出的标题字符串。

3. 示例源码逐行解析：src/main.c

完整示例代码位于 example/c-vt/src/main.c，全文只有 36 行：

#include <stddef.h>
#include <stdio.h>
#include <string.h>
#include <ghostty/vt.h>

int main() {
  GhosttyOscParser parser;
  if (ghostty_osc_new(NULL, &parser) != GHOSTTY_SUCCESS) {
    return 1;
  }

  // Setup change window title command to change the title to "hello"
  ghostty_osc_next(parser, '0');
  ghostty_osc_next(parser, ';');
  const char *title = "hello";
  for (size_t i = 0; i < strlen(title); i++) {
    ghostty_osc_next(parser, title[i]);
  }

  // End parsing and get command
  GhosttyOscCommand command = ghostty_osc_end(parser, 0);

  // Get and print command type
  GhosttyOscCommandType type = ghostty_osc_command_type(command);
  printf("Command type: %d\n", type);

  // Extract and print the title
  if (ghostty_osc_command_data(command, GHOSTTY_OSC_DATA_CHANGE_WINDOW_TITLE_STR, &title)) {
    printf("Extracted title: %s\n", title);
  } else {
    printf("Failed to extract title\n");
  }

  ghostty_osc_free(parser);
  return 0;
}

这段代码与 include/ghostty/vt/osc.h 头部文档中列出的五步标准流程完全对应：

1. 创建解析器：ghostty_osc_new(NULL, &parser)。第一个参数是指向 GhosttyAllocator 的指针，传 NULL 表示使用库的默认分配器；生产环境可以传入自定义分配器以便接管内存生命周期。返回 GHOSTTY_SUCCESS 表示创建成功，示例中对失败情况直接返回非零退出码。

2. 逐字节喂入数据：ghostty_osc_next(parser, byte) 每次处理一个字节。示例中喂入的字节序列是 '0'、';' 以及 "hello" 的每个字符——这模拟了终端协议中 ESC ] 0 ; hello BEL 形式的 OSC 序列的"数据段"（OSC 的起始符 ESC ] 与结束符 BEL/ST 由上游解析器截断后交给 OSC 解析器处理）。头文件文档特别说明了设计动机：

   The parser operates in a streaming fashion, processing input byte-by-byte to handle OSC sequences that may arrive in fragments across multiple reads.

   即解析器是**流式（streaming）**工作的，可以处理跨多次 I/O 读取到达的碎片化 OSC 序列，从而避免过度分配缓冲区——这正是它适合嵌入到任意 I/O 框架中的原因。

3. 结束解析并取得命令：ghostty_osc_end(parser, 0) 返回一个 GhosttyOscCommand 值类型，封装了解析完成的命令。

4. 查询命令类型与提取数据：

   • ghostty_osc_command_type(command) 返回 GhosttyOscCommandType 枚举。枚举覆盖了窗口标题、窗口图标、剪贴板内容、Kitty 颜色协议、语义提示、超链接起止、ConEmu 扩展命令、Kitty 桌面通知等二十余种 OSC 命令类型（完整列表见 osc.h 中的 GhosttyOscCommandType）。
   • ghostty_osc_command_data(command, GHOSTTY_OSC_DATA_CHANGE_WINDOW_TITLE_STR, &title) 按"数据类型 + 输出指针"的方式提取命令数据。对于标题命令，输出类型是 const char **（指向 NUL 终止字符串的指针）。头文件同时明确了内存生命周期：提取出的字符串由 parser 持有，"Valid until the next call to any ghostty_osc_* function with the same parser instance"——即在同一次 ghostty_osc_* 调用之前有效，需要留存时应自行拷贝。

5. 释放解析器：ghostty_osc_free(parser) 释放所有资源，释放后句柄不可再使用；另外头文件还提供 ghostty_osc_reset() 用于将解析器重置回初始状态，以便复用同一实例或从解析错误中恢复。

4. 构建系统：build.zig 的关键细节

c-vt/build.zig 展示了如何把一个纯 C 源文件挂进 Ghostty 的构建体系，核心结构如下（按源码顺序摘录并注释）：

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const run_step = b.step("run", "Run the app");

    const exe_mod = b.createModule(.{
        .target = target,
        .optimize = optimize,
    });
    // 1. 把 C 源码加入编译模块（等价于任意 C 工具链里编译 src/main.c）
    exe_mod.addCSourceFiles(.{
        .root = b.path("src"),
        .files = &.{"main.c"},
    });

    // 2. 通过懒依赖获取 Ghostty 源码树并链接 ghostty-vt 库
    if (b.lazyDependency("ghostty", .{
        // 注释原文：将 simd 设为 false 会强制纯静态构建，
        // 甚至不需要 libc，但有明显性能损耗；
        // 如果宿主程序本来就要链接 libc，应保持 simd 开启。
        // .simd = false,
    })) |dep| {
        exe_mod.linkLibrary(dep.artifact("ghostty-vt"));
    }

    // 3. 定义可执行文件 c_vt 并安装
    const exe = b.addExecutable(.{
        .name = "c_vt",
        .root_module = exe_mod,
    });
    b.installArtifact(exe);

    // 4. 注册 run 步骤，透传命令行参数
    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| run_cmd.addArgs(args);
    run_step.dependOn(&run_cmd.step);
}

这里有三个值得注意的点：

• addCSourceFiles：说明构建入口并不要求宿主程序是 Zig 写的——C 源文件只是被当作普通编译输入，任何能产出/链接 libghostty-vt 的工具链都能完成同样的事。
• lazyDependency("ghostty", ...)：使用懒依赖声明对 Ghostty 源码树的依赖，只有真正构建时才拉取。注释中还暴露了一个重要的构建权衡：把 .simd 设为 false 可以得到一个连 libc 都不需要的纯静态构建，但代价是显著的性能损失；如果你的宿主应用反正要链接 libc，就应该保持 SIMD 开启。
• linkLibrary(dep.artifact("ghostty-vt"))：最终链接的是名为 ghostty-vt 的构建产物，即标准 C 库。

5. 与头文件文档体系的对应关系

c-vt 示例并不是孤立的——它在 include/ghostty/vt.h 的 Doxygen 文档体系中被正式登记为 OSC 解析器的参考示例（@example c-vt/src/main.c），整个 libghostty-vt 的公开 API 通过该头文件聚合了 terminal、render、formatter、snapshot、search、osc、sgr、paste、key、mouse 等约二十个子模块。文档中同时给出了 API 状态的重要提示：

WARNING: This is an incomplete, work-in-progress API. It is not yet stable and is definitely going to change.

因此将 libghostty-vt 用于生产代码时需要自行评估 API 变动风险。

按 example/AGENTS.md 的约定，示例源码中的代码片段通过 Doxygen @snippet 标签被头文件直接引用，保证文档中的代码与 example/ 目录下的真实源码始终一致；新增示例时也应遵循"复制现有示例目录、保持 build.zig 模板一致、用 lazyDependency("ghostty", ...) 链接"这套惯例。

6. 进一步延伸：同系列示例

c-vt 只是 example/ 目录下众多 C 示例中最基础的一个，它们共用同一套构建模板，可以按需求横向参考：

示例目录	演示能力
c-vt-sgr	SGR（Select Graphic Rendition）样式序列解析
c-vt-stream	完整的 VT 流式终端集成
c-vt-render	增量渲染状态回调，用于自绘渲染器
c-vt-formatter	将终端内容格式化为纯文本/VT/HTML
c-vt-snapshot	终端状态的快照编码与增量恢复
c-vt-encode-key	基于 Kitty 键盘协议将按键事件编码为转义序列
c-vt-paste	粘贴验证、编码与 Kitty 剪贴板协议
c-vt-search	含滚动回退区的终端内容搜索
c-vt-cmake	用 CMake 而非 Zig 构建 C 示例的对照工程

其中 c-vt-cmake 及其静态链接变体（c-vt-cmake-static）、交叉编译变体（c-vt-cmake-cross）与 c-vt 使用完全相同的 src/main.c，专门演示"不依赖 Zig、只用标准 CMake 工具链"如何构建和分发 libghostty-vt，如果你的工程体系是 CMake，这是最直接的对标参考。

7. 小结

• example/c-vt 展示了 libghostty-vt 的最小可用闭环：ghostty_osc_new → ghostty_osc_next（流式逐字节）→ ghostty_osc_end → ghostty_osc_command_type / ghostty_osc_command_data → ghostty_osc_free。
• 示例用 Zig + build.zig 构建只是为了复用仓库构建逻辑并直接依赖源码树；产物是标准 C 库，任何 C 工具链（含 CMake，见 c-vt-cmake）都可以链接。
• 提取出的字符串数据由 parser 持有、生命周期仅限下一次同 parser 的 ghostty_osc_* 调用之前，需要留存时务必自行拷贝。
• 该 API 目前仍是 work-in-progress 状态，嵌入生产系统前应留意 include/ghostty/vt.h 中的兼容性警告。