Buildroot 增量构建成功，干净构建却失败：怎样找出缺失依赖
同一个软件包在旧 output 中能编译，换全新目录却失败，最有价值的线索往往就在两次构建的差异里：残留库、预先生成的文件，或数周前缓存的探测结果。先保留成功与失败现场，再把隐含输入写成受控依赖。本文沿用包审查入口，适用于人工或 AI 辅助编写的配方；教学片段以 Buildroot 2025.02.18 为固定参考，没有完整交叉构建通过记录。
用同一输入对照增量与干净构建
保留增量成功的 output，保存配置、源码版本与原始日志。再使用相同 Buildroot、外部树、defconfig、包源码和工具链创建新的 O= 目录，并记录环境差异。虽然末尾都执行同一包名，若编译器或功能开关不同，就不能直接当作受控对照。
在详细日志中定位第一个有意义的失败。下载问题应先解决来源；配置阶段常涉及功能探测；缺头文件、未定义符号和安装错误则属于不同阶段。递归 make 最后一行通常只说明错误传播。保留出错命令前后的内容、工作目录和缺失输入，再提出可验证的解释，避免一边试错一边丢失证据。
找出旧输出目录提供了什么隐藏条件
为缺失文件或命令找到应当负责生成它的包。旧 staging 可能留有已经取消选择的软件库，host 可能留有构建生成器，包 build 目录可能缓存了生成源码或配置探测。target 表达运行期安装内容，不能代替开发 sysroot；“在 output 里找到过”还不足以说明依赖关系正确。
如果手工复制头文件后错误消失，把这个现象记下来，再从测试配置撤回临时操作。继续查文件属于哪个版本、由什么安装步骤产生、消费者为何没有等待它。把开发文件塞进 target，或每次先手工 make 另一个包，都会掩盖生产者与消费者关系，让下一位工程师再次遇到相同失败。
区分配置可见性与构建顺序依赖
Config.in 表达配置选项及其约束，.mk 则声明配置包之前要准备好的构建依赖。选中一个库，并不能代替消费者自己的依赖声明。准确规则以固定版本的配置说明和包基础设施为准。
教学示例 telemetry 的可选 zlib 功能在 Config.in 中选择 BR2_PACKAGE_ZLIB，并遵守相应配置要求。.mk 同时需要声明依赖与开关；故意删掉依赖行便构成待验证的缺陷样例。
ifeq ($(BR2_PACKAGE_TELEMETRY_ZLIB),y)
TELEMETRY_DEPENDENCIES += zlib
TELEMETRY_CONF_OPTS += -DTELEMETRY_WITH_ZLIB=ON
else
TELEMETRY_CONF_OPTS += -DTELEMETRY_WITH_ZLIB=OFF
endif这只是配方片段。上游源码仍需真实实现该 CMake 选项，并以支持交叉编译的方式寻找 zlib。
| 修改内容 | 局部迭代入口 | 仍需补齐的证据 |
|---|---|---|
| 仅修改源码实现 | package-rebuild | 编译日志及新目录回归 |
| 配置参数或可选功能 | package-reconfigure | 功能摘要及消费者重建审查 |
| 补丁或解压输入 | package-dirclean 后正常构建 | 全新源码的补丁重放 |
| 工具链、ABI 或移除已选包 | 全新输出目录完整构建 | 完整镜像与相关运行测试 |
| 怀疑残留依赖 | 最小配置及新 O= 目录 | 无需旧 staging/host 即引入依赖 |
检查可选特性与自动探测
比较成功与失败两次的 configure 摘要或 CMake 缓存。某些 auto 功能可能仅因为别的包曾安装库而被打开，造成两次构建即使都成功，功能也不同。为每个可选项明确要求开启、要求关闭或由产品配置选择。
开启时同时声明依赖与上游启用参数；关闭时传入有效的禁用参数，并检查探测结果确实关闭。不要以为未主动使用某个库就不会被自动发现。目标库与主机构建工具也要分开：编译期间执行的生成器必须能在主机运行，链接到应用里的库需要目标架构版本，不能随意互换依赖名称。
正确选择 rebuild reconfigure 与 dirclean
明确需要重走哪一步后，再用局部重建加快迭代。该版本 package-rebuild 从编译重来，package-reconfigure 重做配置，package-dirclean 删除包构建目录以便重新准备。它们不会自动清除所有已安装文件，也不会替你重建所有消费者，范围见固定版本重建说明。
补丁变化通常要重新解压和应用，功能参数变化需重做配置，工具链变化则应安排完整干净构建。完成包级操作后，还要通过正常构建目标重新生成所需镜像。前面的决策表区分了方便调试的命令与证明不依赖残留所需的全新目录验证。
让依赖修复可以被反证
把配置缩减到消费者真正需要的架构、工具链能力和包，移除可能偶然提供依赖的无关应用，再测试功能开启与关闭两条分支。本例打开时应包含 zlib 与 ON，关闭时应传 OFF 且不引入该依赖。Make 变量小样例可以检查声明逻辑，但不能证明完整目标构建。
随后在实际环境运行干净构建并保留日志，在选定配置支持的情况下改变并行度，验证顺序依赖而非偶然调度。故意缺依赖的版本可作为受控测试分支中的负例；必须确认它因预期缺陷而失败，网络下载错误不能算负例验证成功。人工与 AI 生成的包使用相同要求。
交付最小失败样例与修复检查表
把失败与修复配方、Config.in、最小配置、源码标识和完整日志放在一起，解释找到哪个缺失生产者，以及依赖和功能控制为何能解决它。剩余工具链假设、设备运行期需要的文件也应列明，不能以语法样例通过就宣布可发布。
若证据指向编译器路径或 ELF 架构混用，继续交叉编译污染排查；修复成立后，用包级 CI 门槛保持覆盖。AI 辅助嵌入式修改同样需要受控输入、可反证测试和他人能查看的结果，配方文字看起来合理只是审查的开始。
资料与版本边界
示例用于说明固定版本下的工程方法；本文未执行实板验收、完整交叉构建、性能基准或现场部署，不将示意内容作为通过证据。
- Buildroot 2025.02.18 source archive
- Buildroot manual package and rebuild guidance
- Buildroot 2025.02.18 package configuration
- Buildroot 2025.02.18 generic package infrastructure
- Buildroot 2025.02.18 package rebuild boundaries
需要明确 BSP 维护或构建审查范围时，可向Obeita 提供基础材料：失败包的 .mk 与 Config.in, Buildroot 和工具链版本, 第一处错误及完整构建日志, 最小 defconfig。先脱敏，并写明希望确认的结果。
