> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apsio.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Xcode build phase

> Upload a build's dSYMs from a Run Script build phase, every time Xcode builds the app.

The script `xcode-upload-dsyms.sh` in the
[`apsio-cli` repository](https://github.com/Apsio/apsio-cli/blob/main/scripts/xcode-upload-dsyms.sh)
uploads a build's dSYMs from an Xcode Run Script phase, for the Release configuration by
default. It calls the [`apsio` CLI](/cli), which must be installed on the machine that builds.

## Set it up

1. Copy `xcode-upload-dsyms.sh` into your repository, for example to `scripts/`, and make it
   executable (`chmod +x scripts/xcode-upload-dsyms.sh`).

2. In the app target's Build Settings, set Debug Information Format to "DWARF with dSYM
   File" for Release.

3. In Build Phases, add a New Run Script Phase as the last phase, with this script:

   ```sh theme={null}
   "${SRCROOT}/scripts/xcode-upload-dsyms.sh"
   ```

4. Add this Input File to the phase, so Xcode runs it after the dSYM is written:

   ```text theme={null}
   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${EXECUTABLE_NAME}
   ```

   With User Script Sandboxing on, also add `${DWARF_DSYM_FOLDER_PATH}` as an Input File.

5. Give the build your [upload token](/symbols/upload#upload-tokens): run
   `apsio login --with-token` once on a developer machine, or set
   `APSIO_TOKEN` in the build environment on CI. Never commit the token.

The phase uploads every dSYM of the build: the app, its extensions and the frameworks built
with it.

## Settings

Set these as environment variables, or as user-defined build settings, which Xcode passes to
the script:

| Setting | Default | What it does |
| - | - | - |
| `APSIO_UPLOAD_CONFIGURATIONS` | `Release` | The configurations that upload, separated by spaces |
| `APSIO_CLI` | `apsio` on the `PATH`, then Homebrew's paths | The path to the `apsio` binary |
| `APSIO_STRICT` | `0` | `1` fails the build when the upload fails |
| `APSIO_DRY_RUN` | `0` | `1` finds and validates the dSYMs and uploads nothing |
| `APSIO_TOKEN`, `APSIO_SYMBOLS_URL` | | Passed to the CLI (the symbol upload URL defaults to `https://symbols.apsio.io`) |

## When an upload fails

By default a failed upload is a build warning, never a failed build: you can ship, and the
crashes from that build stay unsymbolicated until `apsio upload dsyms` succeeds for it. The
warning says why, for example a missing token or a missing CLI. With `APSIO_STRICT=1` the
same problems are build errors.

## Debug builds

Debug builds use Debug Information Format "DWARF" by default, which writes no dSYM, so
their crashes cannot be symbolicated. To symbolicate crashes from Debug builds, for example
while you test, set Debug Information Format to "DWARF with dSYM File" for Debug too, and set
`APSIO_UPLOAD_CONFIGURATIONS` to `Debug Release`. This makes Debug builds slower.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.