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

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

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.

Additionally, you need to ensure the TUIST_CONFIG_TOKEN environment variable is set. You can create one by following the documentation here. The TUIST_CONFIG_TOKEN environment variable must be present for your build step, but we'd recommend setting it for the whole CI workflow.

An example workflow for GitHub Actions could then look like this:

name: Build

env:
  TUIST_CONFIG_TOKEN: ${{ secrets.TUIST_CONFIG_TOKEN }}

jobs:
  build:
    steps:
      - # Your set up steps...
      - name: Set up Tuist Cache
        run: tuist setup cache
      - # Your build steps