# Xcode Build Baseline

> Benchmark Xcode clean, cached-clean, zero-change, and incremental builds with fixed inputs, timing summaries, and `.build-benchmark/` artifacts.

- Skill: `xopoko/xcode-build-baseline` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add xopoko/xcode-build-baseline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xopoko/xcode-build-baseline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Xopoko (https://skillmd.com/u/xopoko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xopoko/xcode-build-baseline

---


# Xcode Build Baseline

Before invoking Apple-only binaries, confirm the execution context is macOS. From Windows or Linux, run those steps in a Mac SSH project or through an already configured remote transport; do not retry missing Apple binaries locally.

Bundled commands use `$PLUGIN_ROOT` for the plugin root. Use the host's plugin-root variable when defined; otherwise set it to the absolute path of this plugin before running a helper from the app repository.

Measure before recommending build-time changes. Do not edit project files while benchmarking.

## Rules

- Keep workspace/project, scheme, configuration, destination, DerivedData path, and warm-up rules consistent.
- Pin the toolchain: verify the active Xcode with `xcode-select -p` and record it in the artifact. When several Xcode versions are installed, switch with `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer` before the first measured run, never mid-series — a toolchain switch invalidates every prior measurement.
- Capture clean and incremental behavior separately.
- Write timestamped JSON artifacts under `.build-benchmark/`.
- Report medians and spread, not only the fastest run.
- For iOS Simulator, resolve an installed iPhone/iOS pair; prefer `OS=latest` only when Xcode accepts it.
- In git worktrees, create missing package `exclude:` directories such as `__Snapshots__` before dependency resolution, or SPM can crash.

## Inputs

Infer or ask for workspace/project, scheme, configuration, destination, simulator/device preference, custom DerivedData needs, and a representative Swift file for incremental touch tests.

## Default Run

1. Normalize the build command and record every cache-affecting flag.
2. Warm up once only if needed to prove the command succeeds.
3. Run 3 clean builds.
4. If `COMPILATION_CACHE_ENABLE_CACHING = YES`, run 3 cached-clean builds; use `--no-cached-clean` only when intentionally skipped.
5. Run 3 zero-change builds with no `--touch-file`; this measures fixed overhead from dependency planning, scripts, codesign, validation, and related phases.
6. Optionally run 3 incremental builds with `--touch-file path/to/SomeFile.swift`.
7. Preserve raw logs, summaries, and JSON artifacts.

Preferred helper:

```bash
python3 "$PLUGIN_ROOT/shared/build-optimization/scripts/benchmark_builds.py" \
  --workspace App.xcworkspace \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=<latest available iPhone simulator>,OS=latest" \
  --output-dir .build-benchmark
```

If the helper is unavailable, run equivalent `xcodebuild` commands with `-showBuildTimingSummary` and keep raw output.

## Output

Return clean, cached-clean when enabled, zero-change, and touched-incremental medians/min/max; biggest timing categories; environment details; artifact path; and noise caveats.

If the user only requested measurement, stop there. For optimization, hand the artifact to the relevant skill: `xcode-compile-profiler`, `xcode-project-auditor`, `swiftpm-build-inspector`, or `xcode-build-strategist`.

## Resources

- `references/benchmarking-workflow.md`
- `../../shared/build-optimization/references/benchmark-artifacts.md`
- `../../shared/build-optimization/schemas/build-benchmark.schema.json`