Xcode Build Benchmark

Xcode Build Benchmark

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

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.

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.

Worktree Considerations

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.

Default Workflow

1. Normalize the build command and note every flag that affects caching or module reuse.
2. Run one warm-up build if needed to validate that the command succeeds.
3. Run 3 clean builds.
4. If COMPILATION_CACHE_ENABLE_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.
5. 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).
6. 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.
7. Save the raw results and summary into .build-benchmark/.
8. Report medians and spread, not just the single fastest run.