Skip to content

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.

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 supplies defaults for unset or empty cache settings. Nonempty project, target, command-line, and -xcconfig build settings take precedence. To disable compilation caching for one invocation, pass COMPILATION_CACHE_ENABLE_CACHING=NO to xcodebuild. To disable only Clang path normalization, pass CLANG_ENABLE_PREFIX_MAPPING=NO.

A custom XCODE_XCCONFIG_FILE replaces Avrea's configuration; unsetting the variable also bypasses it. To disable the integration for new jobs, turn off Xcode Compilation Cache in your repository settings.

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.

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.

  • 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 must preserve the compilation-cache settings.

Usage appears as cache type xcode-build under Settings > Usage > Cache and in avr cache output. Entries are isolated to the Avrea repository, count toward its cache quota, and follow normal cache eviction.

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.

Incremental builds that reuse existing DerivedData and skip compilation can show little or no remote cache traffic.

  • 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 replaces or unsets XCODE_XCCONFIG_FILE, which can bypass Avrea's cache configuration.

Cache keys include compiler inputs and relevant build settings. Source, compiler, SDK, architecture, or configuration changes can produce valid cache misses. Changing checkout or build-directory paths can also cause misses; keeping paths stable helps reuse cached results.

Package download and resolution are separate from compilation caching. See Swift Package Registry for semantic-version package resolution and Git fallback behavior.