# iOS Builds

## Build Flavor/Schemes

| Flavor  | Profile Type | Scheme            | Bundle ID           | Distribution Channel | Release Cadence                        | Purpose                   |
| ------- | ------------ | ----------------- | ------------------- | -------------------- | -------------------------------------- | ------------------------- |
| `staff` | `ad-hoc`     | `suno-staff`      | `ai.suno.ios-staff` | Firebase             | Hourly from `develop` branch           | Internal dogfooding       |
| `prod`  | `app-store`  | `suno-production` | `ai.suno.ios`       | TestFlight           | Continuously from `release/*` branches | Release candidate testing |

## Build Versioning

### Version Name (`CFBundleShortVersionString`)

Version names for each build are automatically generated based on the branch type and context, following [Semantic Versioning 2.0.0](https://semver.org/) standards:

| Branch Type                         | Pattern                | Example                    | Components                                                                               |
| ----------------------------------- | ---------------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| **Release branches** (`release/v*`) | `x.y.z`                | `1.2.3`                    | Version extracted from branch name                                                       |
| **Pull request branches**           | `x.y.z+sha.prNUMBER`   | `1.27.0+f73d6d0.pr1266`    | Base version (from Xcode) + 7-char SHA + PR number                                       |
| **Feature/custom branches**         | `x.y.z+sha.branchname` | `1.27.0+f73d6d0.featnewui` | Base version (from Xcode) + 7-char SHA + sanitized branch name (lowercase, alphanumeric) |
| **Default branch** (`develop`)      | `x.y.z+sha`            | `1.27.0+f73d6d0`           | Base version (from Xcode) + 7-char SHA                                                   |

**Build Metadata Format:**

- The `+` symbol denotes build metadata per SemVer standards
- Metadata is ordered by debugging priority: Git SHA first (for code traceability), then context (PR/branch)
- Metadata uses dot (`.`) separators for readability

### Version Code (`CFBundleVersion`)

Version codes (ie build numbers) are automatically incremented and uniquely assigned to each build:

- **Source**: Highest build number from Firebase App Distribution and TestFlight
- **Increment**: Automatically incremented by 1 for each new build
- **Format**: Integer (e.g., `123`)
- **Implementation**: `fastlane/actions/max_version_code.rb`

This ensures builds are always uniquely identified and properly ordered in distribution channels.

## CI/CD Pipeline Overview

### Workflow Overview

| Workflow                                                       | Trigger                                    | Purpose                                                                         |
| -------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| [ci.yml](.github/workflows/ci.yml)                             | PRs, push to `develop`/`release/*`         | Lint, build for testing, run unit/UI tests in parallel shards                   |
| [ci-high-risk.yml](.github/workflows/ci-high-risk.yml)         | PRs labeled `high-risk-change`             | Build both prod and staff release variants for validation before merge          |
| [build-staff.yml](.github/workflows/build-staff.yml)           | Push to `main`, manual, workflow call      | Build staff release artifacts, upload to GitHub Actions, track binary size      |
| [build-prod.yml](.github/workflows/build-prod.yml)             | Push to `release/*`, manual, workflow call | Build production release artifacts, upload to GitHub Actions, track binary size |
| [distribute-staff.yml](.github/workflows/distribute-staff.yml) | Hourly schedule, manual                    | Download latest staff builds and distribute to Firebase App Distribution        |
| [build-command.yml](.github/workflows/build-command.yml)       | Workflow call, manual                      | Reusable workflow for building iOS artifacts with optional distribution         |

### Slash Commands

Use these commands in PR comments to trigger manual operations:

| Command              | Purpose                                                                   |
| -------------------- | ------------------------------------------------------------------------- |
| `/build`             | Build adhoc Staff release and distribute it to Firebase (`dev` group)     |
| `/build flavor:prod` | Build adhoc Prod release and distribute it to Firebase (`dev` group)      |
| `/benchmark`         | Run performance benchmarks (5 iterations) via `suno-ai/ci` infrastructure |

## Xcode Configuration

### Xcode Preferences

The project automatically configures Xcode preferences via [`scripts/configure_xcode.sh`](../scripts/configure_xcode.sh) to ensure consistent development environments:

**Key Settings:**

- **DerivedData Location**: Repo-local at `./DerivedData` (gitignored)
- **SourcePackages Location**: Repo-local at `./SourcePackages` (gitignored)
- **Plugin/Macro Validation**: Disabled for faster package plugin and macro builds
- **Build System Integration**: Swift build system enabled
- **Parallel Builds**: Optimized for available CPU cores

**Running Configuration:**

```bash
./scripts/configure_xcode.sh
```

This script:

1. Creates a backup of current Xcode preferences
2. Sets repo-local DerivedData and SourcePackages paths
3. Disables fingerprint validation for plugins/macros
4. Enables parallel build optimizations

**Note:** Changes require restarting Xcode to take effect.

## Build Settings

The project uses optimized build settings to maximize local development performance while maintaining proper release builds for distribution.

### SWIFT_COMPILATION_MODE

| Mode          | Incremental Speed | Cross-file Optimization | Configuration |
| ------------- | ----------------- | ----------------------- | ------------- |
| `incremental` | ✅ Fast           | ✅ Partial              | Debug         |
| `wholemodule` | ⚠️ Slow           | ✅ Full                 | Release       |

### DEBUG_INFORMATION_FORMAT

| Format            | Build Speed | File Size         | Crash Symbolication        | Xcode Debugging | Configuration   |
| ----------------- | ----------- | ----------------- | -------------------------- | --------------- | --------------- |
| `dwarf`           | ✅ Fastest  | ✅ Smaller        | ❌ Local only              | ✅ Full support | Debug           |
| `dwarf-with-dsym` | ⚠️ Slower   | ❌ Larger (+dSYM) | ✅ Can symbolicate crashes | ✅ Full support | Release/Release |