# Xcode Compilation Cache

Avrea stores Xcode compiler outputs in colocated cache. When Xcode encounters
the same compilation inputs again, it can reuse the previous results instead
of compiling those sources from scratch. This is especially useful after clean
builds and when switching between branches.

Available on macOS runners only. The integration is on by default.

## On Avrea runners

The cache is pre-configured before your workflow steps run, so a stock
`xcodebuild` invocation uses it without workflow changes:

```yaml title="workflow.yml"
jobs:
  build:
    runs-on: avrea-macos-latest
    steps:
      - uses: actions/checkout@v7
      - run: |
          xcodebuild \
            -scheme MyApp \
            -destination 'platform=macOS' \
            build
```

The **Xcode Compilation Cache** setting controls the integration at the
organization and repository levels. It is on by default. A repository-level
override takes precedence over the organization setting, and setting changes
apply to new jobs.

Avrea activates the cache through `XCODE_XCCONFIG_FILE`. A workflow-provided
value or command-line `-xcconfig` takes precedence and can bypass Avrea's
injected cache settings. Avoid overriding them unless the project deliberately
manages the compilation-cache configuration itself.

## What it caches

The cache stores reusable Swift and Clang compilation results for a particular
set of source and build-setting inputs. It can accelerate:

- Application, framework, library, and test source compiled by an Xcode
  project.
- A standalone Swift package built directly with its own `xcodebuild` scheme.
- Swift package dependencies of an Xcode project on Xcode 26.5 or later.
- Repeated compilation after a clean build or branch switch.

On Xcode 26.5 or later, Swift package dependencies can use compilation caching
both when built directly and as part of an application-target build.
Compilation caching is separate from downloading package sources.

The [Swift Package Registry](/cache/packages/swift/) supplies eligible public
and private package source from colocated storage. Branch, commit, and other
Git dependencies can use [GitHub Actions Cache](/cache/github-actions/) to
reuse SwiftPM's download cache. Neither mechanism stores Xcode compiler
outputs.

## How it works with Tuist

The Xcode and [Tuist module caches](/cache/build-cache/tuist/) operate at
different levels:

- A Tuist hit substitutes a complete prebuilt target before compilation.
- On a Tuist miss, Xcode compiles eligible project source and can reuse
  lower-level compiler outputs from the Xcode compilation cache.
- Targets that Tuist cannot store, including the application target, can still
  benefit from Xcode compilation caching.

When `tuist cache warm` builds a missing module through Xcode, the Xcode
compilation cache can accelerate that build.

## Requirements

- **Xcode 26 or later**: compilation caching relies on Xcode 26's caching
  support. Older versions continue to build without the remote cache.
- **macOS runner**: the integration has no effect on non-macOS runners.
- **Compatible Xcode configuration**: a custom `XCODE_XCCONFIG_FILE` or
  command-line `-xcconfig` must preserve the compilation-cache settings.

## Storage and isolation

Entries appear with type `xcode-build` on the **Caches** page and in
`avr cache` output. They are isolated to the Avrea repository, count toward its
cache quota, and follow normal cache eviction.

## Cache stats

Run and job cache stats show Xcode cache traffic and, for
supported jobs, a build-client summary split into local and remote operations.
The summary does not include source file or compilation-unit names. See
[Cache Stats](/cache/stats/) for field definitions and coverage states.

## Troubleshooting

### No Xcode cache entries appear

- Confirm that **Xcode Compilation Cache** is enabled, then start a new job.
- Confirm that the job uses Xcode 26 or later on a macOS runner.
- Check whether the workflow sets `XCODE_XCCONFIG_FILE` or passes `-xcconfig`.
  Either can override Avrea's injected configuration.

### A warm build still compiles source

Cache keys include compiler inputs and relevant build settings. Source,
compiler, SDK, architecture, or configuration changes can produce valid cache
misses.

### Swift package downloads are slow

Package download and resolution are separate from compilation caching. See
[Swift Package Registry](/cache/packages/swift/) for semantic-version package
resolution and Git fallback behavior.