构建脚本和构建期资源/平台衔接

fn main()

作用：这是构建脚本的入口，Cargo 在编译这个 crate 时会先运行它。它决定要不要尝试编译 bubblewrap，并告诉 Cargo 哪些文件或环境变量变化后需要重新跑构建。

数据流：进去的是编译环境里的信息，比如目标操作系统、项目目录、一些控制开关环境变量。它先打印 Cargo 能理解的指令，登记需要监听的环境变量和 C 源码文件；然后检查目标系统是不是 Linux、是否设置了跳过构建。符合条件时，它调用 try_build_bwrap 去真正编译；如果编译失败，就直接让构建报错停止。

调用关系：它是整个文件的总开关。Cargo 调起它后，它先做规则登记和平台判断，再把重活交给 try_build_bwrap；try_build_bwrap 如果返回错误，main 会用 panic! 把错误变成清晰的构建失败。

调用图：调用 1 个内部函数（try_build_bwrap）；外部调用 5 个（from, var, var_os, panic!, println!）。

fn try_build_bwrap() -> Result<(), String>

作用：这个函数真正负责把 bubblewrap 的 C 源码编译进项目。有人会用它，是因为 Rust 项目需要在构建阶段准备好一个可链接的内置沙箱组件。

数据流：进去的是环境变量里的项目目录和输出目录，以及系统里通过 pkg-config 能找到的 libcap 信息。它先找到 bubblewrap 源码目录，再检查 libcap 是否可用；然后在构建输出目录写入 config.h，配置 C 编译器要编译哪些 C 文件、包含哪些头文件目录、定义哪些编译开关。它把 main 改名为 bwrap_main，避免入口函数重名。编译完成后，它把库搜索路径、要链接的库名，以及 bwrap_available 这个编译标记打印给 Cargo。成功时返回 Ok，失败时返回带说明的错误字符串。

调用关系：它由 main 在确认需要构建时调用，是“真正干活”的步骤。它自己不会决定平台和跳过规则，只负责执行构建；其中源码目录的选择交给 resolve_bwrap_source_dir，系统库信息交给外部的 pkg-config 查询，C 编译动作交给 cc 构建工具。

调用图：调用 1 个内部函数（resolve_bwrap_source_dir）；被 1 处调用（main）；外部调用 7 个（from, new, new, var, format!, println!, write）。

fn resolve_bwrap_source_dir(manifest_dir: &Path) -> Result<PathBuf, String>

作用：这个函数负责决定 bubblewrap 源码应该从哪里拿。它让开发者既可以用自己指定的源码 checkout，也可以默认使用项目随代码带着的 vendor 版本。

数据流：进去的是当前 crate 的目录路径。它先看环境变量 CODEX_BWRAP_SOURCE_DIR 有没有设置；如果设置了，并且这个目录真实存在，就把它作为源码目录返回；如果设置了但目录不存在，就返回错误。没有设置时，它会检查项目相对路径 ../vendor/bubblewrap 是否存在；存在就返回这个默认目录，不存在就返回一段说明该怎么修复的错误信息。

调用关系：它被 try_build_bwrap 调用，位置在正式编译之前。try_build_bwrap 需要先知道 C 源码在哪里，才能把 bubblewrap.c、bind-mount.c、network.c、utils.c 交给 C 编译器；这个函数就是专门负责把“源码位置”这件事判断清楚。

调用图：被 1 处调用（try_build_bwrap）；外部调用 4 个（join, from, var, format!）。

fn main() -> Result<(), String>

作用：这是构建脚本的入口。Cargo 在编译这个包时会运行它，用它来决定是否以及怎样把 Windows manifest（清单文件，用来告诉 Windows 程序需要的权限和兼容信息）嵌入到指定的辅助可执行文件中。

数据流：进去的是编译环境里的信息，比如目标操作系统、编译工具链类型、项目目录位置；它先打印一条给 Cargo 的提示，说明清单文件变化时要重新构建。接着如果目标不是 Windows，就直接结束；如果是 Windows，它拼出清单文件路径，再根据 MSVC 或 GNU/LLVM 工具链打印对应的链接参数。出来的结果不是普通返回值，而是一组写到标准输出的 Cargo 指令；如果缺少必要的项目目录环境变量，则返回错误。

调用关系：它由 Cargo 在构建阶段自动调用。它自己不去真正修改可执行文件，而是通过读取环境变量了解当前构建情况，再用 println! 输出 Cargo 能识别的命令，把后续嵌入 manifest 的工作交给 Cargo 和链接器完成。

调用图：外部调用 4 个（from, var, var_os, println!）。

fn main()

作用：这是构建脚本的入口，Cargo 在编译项目前会自动运行它。它判断目标系统是不是 macOS，如果是，就告诉 Rust 编译器在链接时加上一个 macOS 需要的参数。

数据流：它先读取环境变量 CARGO_CFG_TARGET_OS，这个变量由 Cargo 提供，表示当前编译目标的操作系统。然后它把读到的值和 macos 比较；如果相等，就输出一行 cargo:rustc-link-arg=-ObjC。Cargo 会把这行输出当成命令，不是普通日志，并把 -ObjC 传给后面的链接步骤；如果不是 macOS，它什么也不改。

调用关系：这个函数不被项目里的普通运行代码调用，而是在构建阶段由 Cargo 自动执行。它只依赖两个外部能力：读取环境变量 var，以及用 println! 输出给 Cargo 的构建指令；真正的链接工作随后由 Cargo 和 Rust 编译工具链接着完成。

调用图：外部调用 2 个（println!, var）。

fn main()

作用：这是构建脚本的入口。它检查样例资源目录是否存在，并在存在时启动递归扫描，让 Cargo 以后能发现这些资源文件的变化。

数据流：进去的是固定路径 src/assets/samples，它先把这个字符串变成一个路径对象，再检查这个目录在磁盘上是否存在。不存在就什么也不做直接结束；存在就向 Cargo 打印一条“这个目录变了要重新构建”的提示，然后把目录交给 visit_dir 继续扫描里面的内容。

调用关系：Cargo 在构建项目时会自动运行这个 main。它自己只负责确定起点和发出第一条监控指令，真正逐层查看目录内容的工作交给 visit_dir。

调用图：调用 1 个内部函数（visit_dir）；外部调用 2 个（new, println!）。

fn visit_dir(dir: &Path)

作用：这个函数负责走遍一个目录里的所有东西，并把每个文件或子目录都登记给 Cargo 监控。遇到子目录时，它会继续往里走。

数据流：进去的是一个目录路径。它尝试读取这个目录的内容；如果读取失败，比如目录权限不够或突然不存在，就安静退出。读取成功后，它逐个拿到里面的条目，打印“这个路径变了要重新构建”的提示；如果某个条目还是目录，就再次调用自己，继续扫描更深一层。结果不是返回数据，而是通过打印给 Cargo 的指令改变构建系统的监控范围。

调用关系：visit_dir 由 main 在确认样例目录存在后调用。它是整个扫描流程里的“递归小工”，每发现一个子目录就把同样的工作再做一遍，直到所有层级都登记完成。

调用图：被 1 处调用（main）；外部调用 2 个（read_dir, println!）。