Xcode cache

Tuist provides support for the Xcode compilation cache, which allows teams to share compilation artifacts by leveraging the build system's caching capabilities.

Setup

REQUIREMENTS

• A Tuist account and project
• Xcode 26.0 or later

If you don't already have a Tuist account and project, you can create one by running:

tuist init

Once you have a Tuist.swift file referencing your fullHandle, you can set up the caching for your project by running:

tuist setup cache

This command creates a LaunchAgent to run a local cache service on startup that the Swift build system uses to share compilation artifacts. This command needs to be run once in both your local and CI environments.

To set up the cache on the CI, make sure you are authenticated.

Configure Xcode Build Settings

Add the following build settings to your Xcode project:

COMPILATION_CACHE_ENABLE_CACHING = YES
COMPILATION_CACHE_REMOTE_SERVICE_PATH = $HOME/.local/state/tuist/your_org_your_project.sock
COMPILATION_CACHE_ENABLE_PLUGIN = YES
COMPILATION_CACHE_ENABLE_DIAGNOSTIC_REMARKS = YES

Note that COMPILATION_CACHE_REMOTE_SERVICE_PATH and COMPILATION_CACHE_ENABLE_PLUGIN need to be added as user-defined build settings since they're not directly exposed in Xcode's build settings UI:

SOCKET PATH

The socket path will be displayed when you run tuist setup cache. It's based on your project's full handle with slashes replaced by underscores.

You can also specify these settings when running xcodebuild by adding the following flags, such as:

xcodebuild build -project YourProject.xcodeproj -scheme YourScheme \
    COMPILATION_CACHE_ENABLE_CACHING=YES \
    COMPILATION_CACHE_REMOTE_SERVICE_PATH=$HOME/.local/state/tuist/your_org_your_project.sock \
    COMPILATION_CACHE_ENABLE_PLUGIN=YES \
    COMPILATION_CACHE_ENABLE_DIAGNOSTIC_REMARKS=YES

GENERATED PROJECTS

Setting the settings manually is not needed if your project is generated by Tuist.

In that case, all you need is to add enableCaching: true to your Tuist.swift file:

import ProjectDescription

let tuist = Tuist(
    fullHandle: "your-org/your-project",
    project: .tuist(
        generationOptions: .options(
            enableCaching: true
        )
    )
)

Continuous integration #

To enable caching in your CI environment, you need to run the same command as in local environments: tuist setup cache.

For authentication, you can use either OIDC authentication (recommended for supported CI providers) or an account token via the TUIST_TOKEN environment variable.

An example workflow for GitHub Actions using OIDC authentication:

name: Build

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v2
      - run: tuist auth login
      - run: tuist setup cache
      - # Your build steps

See the Continuous Integration guide for more examples, including token-based authentication and other CI platforms like Xcode Cloud, CircleCI, Bitrise, and Codemagic.