xcode-build-benchmark

Xcode 构建基准测试

使用此技能，在尝试优化构建时间之前，生成可重复的 Xcode 构建基线。

核心规则

• 先测量，再提出更改建议。
• 分别记录干净构建和增量构建。
• 确保各次运行的命令、目标设备、配置、方案和预热规则保持一致。
• 将带时间戳的 JSON 产物写入 .build-benchmark/。
• 不要在基准测试过程中更改项目文件。

需要收集的输入

确认或推断以下信息：

• 工作区或项目路径
• 方案
• 配置
• 目标设备
• 用户需要模拟器还是设备数据
• 是否需要自定义 DerivedData 路径

如果项目同时存在干净构建和增量构建方面的问题，则对两者都进行基准测试。这是默认做法。

工作树注意事项

在 git 工作树中进行基准测试时，如果 SPM 软件包中的 exclude: 路径引用了被 git 忽略的目录（例如 __Snapshots__），xcodebuild -resolvePackageDependencies 会崩溃。运行任何构建之前，请创建这些缺失的目录。

默认工作流

1. 规范化构建命令，并记录所有会影响缓存或模块复用的标志。
2. 如有需要，运行一次预热构建，以验证命令可以成功执行。
3. 运行 3 次干净构建。
4. 如果检测到 COMPILATION_CACHE_ENABLE_CACHING = YES，则运行 3 次启用缓存的干净构建。这些构建用于测量编译缓存已预热时的干净构建时间，适用于切换分支、拉取更改或执行 Clean Build Folder 等实际场景。脚本会自动先构建一次以预热缓存，然后在每次测量运行前删除 DerivedData（但不删除编译缓存）。传入 --no-cached-clean 可跳过此步骤。
5. 运行 3 次零改动构建（成功构建后不做任何编辑，立即再次构建）。这用于测量固定开销下限：依赖项计算、项目描述传输、构建描述创建、脚本阶段、代码签名和验证。零改动构建耗时超过几秒，说明每次构建都存在可避免的开销。使用默认的 benchmark_builds.py 调用方式（不带 --touch-file 标志）。
6. 可选：通过触碰文件运行 3 次增量构建，以测量真实的编辑后重新构建循环。使用 --touch-file path/to/SomeFile.swift，在每次构建前触碰一个有代表性的源文件。
7. 将原始结果和摘要保存到 .build-benchmark/。
8. 报告中位数和波动范围，而不只是单次最快结果。

首选命令方式

尽可能使用共享辅助工具：

python3 scripts/benchmark_builds.py \
  --workspace App.xcworkspace \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=iPhone 16" \
  --output-dir .build-benchmark

如果无法使用辅助脚本，请运行等效的 xcodebuild 命令，并添加 -showBuildTimingSummary，同时保留原始输出。

必需输出

返回以下内容：

• 干净构建的中位数、最小值、最大值
• 启用 COMPILATION_CACHE_ENABLE_CACHING 时，启用缓存的干净构建中位数、最小值、最大值
• 零改动构建的中位数、最小值、最大值（固定开销下限）
• 增量构建的中位数、最小值、最大值（如果使用了 --touch-file）
• 耗时最多的计时摘要类别
• 可能影响对比结果的环境详情
• 保存的产物路径

如果结果波动较大，请说明情况，并建议在环境更稳定时重新运行。

何时停止

如果用户只要求基准测试，测量完成后即可停止。如果用户还需要优化建议，则将产物交给相关专家：读取对应的 SKILL.md，并针对同一项目上下文执行其工作流：

• xcode-compilation-analyzer
• xcode-project-analyzer
• spm-build-analysis
• xcode-build-orchestrator（用于完整编排）

其他资源

• 有关基准测试约定，请参阅 references/benchmarking-workflow.md
• 有关共享产物格式，请参阅 references/benchmark-artifacts.md
• 有关 JSON Schema，请参阅 schemas/build-benchmark.schema.json