Skip to content
Documentation

Docs / Adapter commands / Xcode

Xcode adapter

Use Xcode's native compilation cache across compatible macOS machines. Stable physical source and DerivedData paths define which builds can share results.

Command
boringcache xcode
Protocol
Xcode compilation cache over Apple's content-addressable store
Action
mode: xcode

How the adapter works

Apple-native cache path

BoringCache uses Xcode's own compilation caching and CAS model instead of archiving derived data after the fact.

Compatible builds share compilation results

Use the same Xcode build and SDK on each runner. Different compiler versions do not share compilation results. CLI 1.42.0 (not yet released) also fixes Swift compilation reuse between cache sessions and read-only restores.

Checkout and build paths

By default, keep real checkout and DerivedData paths consistent across runners. Xcode 26 requires this. Changing the Xcode build or SDK also prevents reuse, even when source files match. CLI 1.42.0 also refuses cache setup if XCODE_XCCONFIG_FILE is already set, so existing build settings are preserved.

Set up Xcode

Keep the cache tag and the xcodebuild command in .boringcache.toml, then run boringcache xcode. The adapter manages Xcode's native compilation cache and points the build at the derived-data path it provides.

[adapters.xcode]
tag = "xcode-cache"
command = ["xcodebuild", "-workspace", "App.xcworkspace", "-scheme", "App", "build"]

# Run: boringcache xcode

Before the first run

  • Run on macOS with Xcode 26.
  • Keep physical checkout and DerivedData paths stable across the runners expected to share compilation results.
  • Inspect boringcache xcode --dry-run --json before comparing different path cohorts.

Configuration and cache behavior

Optional Xcode 27 path mapping

CLI 1.42.0 (not yet released) adds prefix-mapping = true under [adapters.xcode.options]. It enables compiler mapping for project and build paths without moving the checkout. Enable it only if your build does not use #filePath or __FILE__ to find files at runtime: those values become virtual paths. Debugging outside Xcode may require a source map. Use a direct xcodebuild command so BoringCache can determine the build directory; Action builds must use the exported BORINGCACHE_XCODE_DERIVED_DATA_PATH.

Wrapper commands and build paths containing an equals sign are not supported with this option. External absolute inputs and build settings must still match. Leave the option unset or false to retain existing behavior.

Use the same adapter in GitHub Actions

The Action prepares the native Xcode compilation-cache bridge and exports a stable DerivedData path for the later xcodebuild step.

.github/workflows/ci.yml
- uses: boringcache/one@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  with:
    trust-policy: auto
    mode: xcode

- run: xcodebuild -workspace App.xcworkspace -scheme App -derivedDataPath "$BORINGCACHE_XCODE_DERIVED_DATA_PATH" build

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

GitHub Actions reference

Benchmarks

OBS Studio builds the same upstream commits with BoringCache, Bitrise Build Cache and GHA Cache on the same runner classes.

OBS Studio

Xcode

Benchmark →

Video recording and live streaming application in C and C++.

Average restore, build and save · lower is better

GitHub macOS runner

3 vCPU · 7 GB · macOS 26 Apple M1

BoringCache
5 min 22 s 28 builds
GHA Cache
4 min 53 s 28 builds

Apple M1 (Virtual)

Cold and warm builds

Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.

One cold and warm build per cache
Cache Cold Warm CPU
BoringCache Compilation cache 11 min 17 s 5 min 7 s Apple M1 (Virtual)
GHA Cache Local cache directory restored and saved by actions/cache 10 min 53 s 4 min 21 s Apple M1 (Virtual)

Cache hits

BoringCache · GitHub macOS runner · 3 vCPU

100.0% of 217,417 lookups over 28 builds

Served from the runner
Under 1 ms per read
Read from cache
30.8 GB

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

Compare every supported command, protocol, and Action mode in one place.

Adapter command index →

Need help or found something unclear? Open an issue or browse the CLI repo.