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:

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 supplies eligible public and private package source from colocated storage. Branch, commit, and other Git dependencies can use GitHub Actions Cache to reuse SwiftPM's download cache. Neither mechanism stores Xcode compiler outputs.

How it works with Tuist

The Xcode and Tuist module caches 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 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 for semantic-version package resolution and Git fallback behavior.