自定义扩展：三件套接入任何 C 库

本章导读

39.1 引入

扩展机制的设计目标一句话：新增库 = 声明，不是代码。宿主代码里没有任何 per-library 分支（if sqlite… else if xtp…）——注册表在构建期生成符号聚合头 xs_build_extensions.h，运行期统一经 XS_TccAddExtensions() 注入 TCC。这意味着接入新库不需要改宿主源码，也意味着扩展的边界完全由声明文件决定。

39.2 三件套

{
  "mylib": {
    "macro": "XS_USE_MYLIB",                  /* ① 编译宏：脚本侧可见性开关 */
    "headers": {"mylib.h": "lib/mylib.h"},     /* ② 头文件 → VFS 路径映射 */
    "sources": [{"path": "lib/mylib.c",
                 "flags": ["-O2"]}],               编入宿主的源（含编译参数）*/
    "symbols": "src/script/import_mylib.inc",  /* ③ 符号表 */
    "symbol_macro": "XS_MYLIB_SYMBOL"
  }
}

三件套的关系：源编进宿主（进程里有了实现）、头进 VFS（脚本能 include 到声明）、符号表注入 TCC（脚本的调用按地址解析到实现）。宏 XS_USE_MYLIB 会在嵌套编译器里预定义——脚本可以 #ifdef 探测扩展可用性。单头库（stb 风格）用 defines 字段带实现开关（xtp2 条目就是 XTP2_IMPLEMENTATION 的范例）。

39.3 注册中心校验

注册中心（xs_extensions.py）对每条输入做防御性检查，注册错了构建期就爆：

这套校验有专门的单测看护（test_extensions.py 的 10 个用例之一就是"加一个 demo 条目即生效，零代码分支"）。

39.4 两级测试

• 计划级（test_extensions.py）：注册表解析、构建计划、符号表与头的联动、发布失败保护——纯逻辑，秒级
• 运行级（test_extensions_runtime.py）：真实构建的 XServer 里跑内嵌 C 探针——真实调用扩展 API、嵌套 TCC 里也能用扩展、反向验证"未选扩展时头与符号确实不可用"（编译失败 + 报错点名）

给你的库写扩展时，两级都补上：计划级保证注册不烂，运行级保证"编进去了真的能用、没编进去真的没有"。

39.5 契约

• 声明线：新库三件套 + 一条 json，宿主零改动。
• 一致线：VFS 头、符号表、宿主源三者必须同版本——符号表列了头里没有的函数就是定时炸弹。
• 测试线：两级测试是扩展的验收定义。

常见错误

编程练习