# Xcode cache {#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 {#setup}

::: warning REQUIREMENTS
<!-- -->
- A <LocalizedLink href="/guides/server/accounts-and-projects">Tuist account and project</LocalizedLink>
- Xcode 26.0 or later
<!-- -->
:::

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

```bash
tuist init
```

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

```bash
tuist setup cache
```

This command creates a
[LaunchAgent](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)
to run a local cache service on startup that the Swift [build
system](https://github.com/swiftlang/swift-build) 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
<LocalizedLink href="/guides/integrations/continuous-integration#authentication">authenticated</LocalizedLink>.

### Configure Xcode Build Settings {#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:

::: info 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
```

::: info 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:
```swift
import ProjectDescription

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

### Continuous integration #{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_TOKEN` environment variable is set.
You can create one by following the documentation
<LocalizedLink href="/guides/server/authentication#as-a-project">here</LocalizedLink>.
The `TUIST_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:
```yaml
name: Build

env:
  TUIST_TOKEN: ${{ secrets.TUIST_TOKEN }}

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