xcode-build-benchmark

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xcode Build Benchmark

Xcode 构建基准测试

Use this skill to produce a repeatable Xcode build baseline before anyone tries to optimize build times.

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

Core Rules

核心规则

Measure before recommending changes.
Capture clean and incremental builds separately.
Keep the command, destination, configuration, scheme, and warm-up rules consistent across runs.
Write a timestamped JSON artifact to
```
.build-benchmark/
```
.
Do not change project files as part of benchmarking.

在推荐变更前先进行测量。
分别记录清理构建和增量构建的数据。
在多次运行中保持命令、目标设备、配置、scheme和预热规则的一致性。
将带时间戳的JSON产物写入
```
.build-benchmark/
```
目录。
基准测试过程中请勿修改项目文件。

Inputs To Collect

需要收集的输入信息

Confirm or infer:

workspace or project path
scheme
configuration
destination
whether the user wants simulator or device numbers
whether a custom
```
DerivedData
```
path is needed

If the project has both clean-build and incremental-build pain, benchmark both. That is the default.

确认或推断以下信息：

工作区或项目路径
scheme
配置
目标设备
用户是否需要模拟器或真机的数据
是否需要自定义
```
DerivedData
```
路径

如果项目同时存在清理构建和增量构建的性能问题，默认对两者都进行基准测试。

Worktree Considerations

Git工作区注意事项

When benchmarking inside a git worktree, SPM packages with

exclude:

paths that reference gitignored directories (e.g.,

__Snapshots__

) will cause

xcodebuild -resolvePackageDependencies

to crash. Create those missing directories before running any builds.

在git工作区内进行基准测试时，如果SPM包的

exclude:

路径引用了被git忽略的目录（例如

__Snapshots__

），会导致

xcodebuild -resolvePackageDependencies

命令崩溃。请在运行任何构建前创建这些缺失的目录。

Default Workflow

默认工作流

Normalize the build command and note every flag that affects caching or module reuse.
Run one warm-up build if needed to validate that the command succeeds.
Run 3 clean builds.
If
```
COMPILATION_CACHING = YES
```
is detected, run 3 cached clean builds. These measure clean build time with a warm compilation cache -- the realistic scenario for branch switching, pulling changes, or Clean Build Folder. The script handles this automatically by building once to warm the cache, then deleting DerivedData (but not the compilation cache) before each measured run. Pass
```
--no-cached-clean
```
to skip.
Run 3 zero-change builds (build immediately after a successful build with no edits). This measures the fixed overhead floor: dependency computation, project description transfer, build description creation, script phases, codesigning, and validation. A zero-change build that takes more than a few seconds indicates avoidable per-build overhead. Use the default
```
benchmark_builds.py
```
invocation (no
```
--touch-file
```
flag).
Optionally run 3 incremental builds with a file touch to measure a real edit-rebuild loop. Use
```
--touch-file path/to/SomeFile.swift
```
to touch a representative source file before each build.
Save the raw results and summary into
```
.build-benchmark/
```
.
Report medians and spread, not just the single fastest run.

标准化构建命令，并记录所有影响缓存或模块复用的标志。
如有需要，运行一次预热构建以验证命令可成功执行。
运行3次清理构建。
如果检测到
```
COMPILATION_CACHING = YES
```
，则运行3次带缓存的清理构建。这用于测量编译缓存预热后的清理构建时间——这是分支切换、拉取变更或执行「清理构建文件夹」时的真实场景。脚本会自动处理此流程：先构建一次预热缓存，然后在每次测量运行前删除DerivedData（但保留编译缓存）。可传入
```
--no-cached-clean
```
参数跳过此步骤。
运行3次无变更构建（在一次成功构建后立即再次构建，不做任何编辑）。这用于测量固定的开销下限：依赖计算、项目描述传输、构建描述创建、脚本阶段、代码签名和验证。如果无变更构建耗时超过几秒，说明存在可避免的每次构建开销。使用默认的
```
benchmark_builds.py
```
调用方式（不添加
```
--touch-file
```
标志）。
（可选）运行3次带文件修改的增量构建，以测量真实的编辑-重建循环。在每次构建前，使用
```
--touch-file path/to/SomeFile.swift
```
命令修改一个具有代表性的源文件。
将原始结果和摘要保存到
```
.build-benchmark/
```
目录。
报告中位数和离散程度，而不仅仅是最快的单次运行结果。

Preferred Command Path

Required Output

必需的输出内容

Return:

clean build median, min, max
cached clean build median, min, max (when COMPILATION_CACHING is enabled)
zero-change build median, min, max (fixed overhead floor)
incremental build median, min, max (if
```
--touch-file
```
was used)
biggest timing-summary categories
environment details that could affect comparisons
path to the saved artifact

If results are noisy, say so and recommend rerunning under calmer conditions.

需返回以下内容：

清理构建的中位数、最小值、最大值
带缓存的清理构建的中位数、最小值、最大值（当COMPILATION_CACHING启用时）
无变更构建的中位数、最小值、最大值（固定开销下限）
增量构建的中位数、最小值、最大值（如果使用了
```
--touch-file
```
参数）
时间摘要中占比最大的类别
可能影响对比结果的环境细节
保存产物的路径

如果结果波动较大，请告知用户并建议在更稳定的环境下重新运行。

When To Stop

停止时机

Stop after measurement if the user only asked for benchmarking. If they want optimization guidance, hand off the artifact to the relevant specialist by reading its SKILL.md and applying its workflow to the same project context:

```
xcode-compilation-analyzer
```
```
xcode-project-analyzer
```
```
spm-build-analysis
```
```
xcode-build-orchestrator
```
for full orchestration

如果用户仅要求进行基准测试，测量完成后即可停止。如果用户需要优化指导，请读取相关SKILL.md并将产物移交至对应专家，在相同项目环境下应用其工作流：

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

Additional Resources

额外资源

For the benchmark contract, see references/benchmarking-workflow.md
For the shared artifact format, see references/benchmark-artifacts.md
For the JSON schema, see schemas/build-benchmark.schema.json

关于基准测试协议，请查看references/benchmarking-workflow.md
关于共享产物格式，请查看references/benchmark-artifacts.md
关于JSON schema，请查看schemas/build-benchmark.schema.json