ZCDB

为 Zig 构建系统生成 compile_commands.json，开箱即用，无需额外配置。

快速开始

1. 添加依赖

具体版本见 Tags 页面。

zig fetch --save=zcdb https://github.com/zfl9/zcdb/archive/refs/tags/v1.0.0.tar.gz

2. 集成到 build.zig

const zcdb = @import("zcdb");

pub fn build(b: *std.Build) void {
    // 创建 zcdb 实例
    const zcdb_instance = zcdb.Instance.create(b);
    defer zcdb_instance.finalize();

    // 正常构建逻辑（addExecutable、addLibrary、installArtifact 等）
}

zcdb.Instance.create() 与 finalize() 均应在 configure 阶段调用， 推荐在 build() 函数开头创建、通过 defer 在末尾 finalize。

3. 使用

zig build cdb    # 生成 compile_commands.json

• 生成的 compile_commands.json 直接写入项目根目录（原子替换，无 symlink）。
• 覆盖所有 Step.Compile 的 C/C++ 源文件，包括 Zig 静态库、动态库、可执行文件的 C/C++ 源码，以及通过 linkLibrary/linkObject 引入的库。
• 条目包含：clang/clang++、--target=<triple>、include 路径（-I/-isystem/ -idirafter/-F/-iframework）、宏定义（-D，含 ReleaseFast/Small 的 -DNDEBUG）、 以及每个源文件自己的编译 flags。

CLI 选项

选项	默认	说明
-Dcdb_bear	否	注入 ZMAKE_USE_BEAR 环境变量，让 zmake 使用 bear -- make 输出真实 cdb

API

Instance.create(b) → *Instance

在 configure 阶段创建 zcdb 实例。只有 root 包（直接执行 zig build 的包）会注册 cdb 顶层 step；作为 dependency 引入时自动跳过（通过 b.dependency() 获得子 *Build，pkg_hash 非空）。

instance.finalize()

遍历 install step 的依赖图，收集所有 C/C++ 编译步骤及其模块信息（源文件、include 路径、宏定义、target 等），并注册 LazyPath 依赖。通过 defer 调用。

zmake 集成

zcdb 能自动发现并合并 zmake 构建的 C/C++ 库的 compile_commands.json：

• 若某个 LazyPath（include 路径或 C 源文件）由名为 zmake:* 的 step 生成， zcdb 会假定其输出目录下存在 build_out/compile_commands.json，注册依赖并合并。
• 合并时按源文件绝对路径去重，zcdb 自身收集的条目优先。
• zmake 默认写入空的 []（未使用 bear 时），合并时优雅跳过； 若传入 -Dcdb_bear，zmake 会改用 bear -- make 输出真实的编译命令。

设计说明

• 直接读取编译配置，而非编译日志：数据来自 configure 阶段收集的 Step.Compile / Module 元数据，与 Zig 编译缓存无关，不存在 cdb 滞后问题。
• cdb 是独立顶层 step：zig build cdb 只生成 cdb，不触发编译； 生成过程只需等待必要的文件路径（如 WriteFile 产物）就绪。
• 单文件容错：某个源文件被删除等异常情况下，跳过该条目而不是整体失败。
• zmake cdb 容错：空文件视为空数组，字段缺失的条目自动跳过。