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

# iOS Native Builds

> Create iOS native builds for xcode projects

## Build Guidance

To use the [Dev Loop](../../develop/dev-loop-overview), a build is required **on every code change**. The binary **is** the app — see [Dev Loop: Hot reload and rebuild configuration](../../develop/dev-loop-overview#hot-reload-and-rebuild-configuration) for the full breakdown.

## Build via the Revyl CLI

### Prerequisites

* Revyl CLI installed and authenticated (`revyl auth login`)

### Setup

Initialize the project using the Revyl CLI:

```bash theme={null}
revyl init
```

This creates an app, generates the necessary Revyl configuration files, runs a build, and uploads it to Revyl.

### Run Build

Run a build using:
`revyl build --platform ios`

This command automatically builds and uploads the app to Revyl, where you can use it to start sessions.

## Advanced Configuration

Revyl makes a best effort to determine the build commands to be used. If the build does not complete successfully modify the build commands manually in the [config.yaml file](/cli/command-reference#config-yaml).

## Build via XCode UI

### Select Simulator

In Xcode toolbar:

* Choose your app **scheme**
* Select any **iOS Simulator** (e.g., iPhone 15 Pro)

The specific simulator doesn't matter - builds are universal.

### Build

1. Clean: **Product → Clean Build Folder** (⌘+Shift+K)
2. Build: **Product → Build** (⌘+B)
3. Wait for success

### Locate Build

**Product → Show Build Folder in Finder**

Navigate to:

```
Build/Products/Debug-iphonesimulator/YourAppName.app
```

**Important**: Use `Debug-iphonesimulator`, NOT `Debug-iphoneos`.

### Test Before Upload

1. Open iOS Simulator
2. Drag `YourApp.app` onto simulator window
3. Launch from home screen
4. Verify it works

Always test locally before uploading.

### Upload to Revyl

See Ways to [Add Builds](/builds#ways-to-add-builds) to upload the build to Revyl.

## Auto-Detect Build from DerivedData

If you build in Xcode normally (Cmd+B), `revyl dev` automatically finds the most recent simulator `.app` from DerivedData:

```bash theme={null}
# Build in Xcode as usual (Cmd+B), then:
revyl dev --platform ios
```

The CLI scans `~/Library/Developer/Xcode/DerivedData/` for the most recently modified `.app` matching your project. Test runner bundles (`*Tests.app`) are excluded automatically.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Signing Errors">
    Simulator builds don't need code signing:

    * Set **Code Signing Identity** to "Don't Code Sign"
    * Or enable **Automatically manage signing**
  </Accordion>

  <Accordion title="Architecture Issues">
    Ensure compatibility with Apple Silicon and Intel:

    1. Select your target → **Build Settings**
    2. Find **Architectures**
    3. Verify: `Standard Architectures (arm64) - $(ARCHS_STANDARD)`

    This includes both `arm64` and `x86_64` automatically.
  </Accordion>

  <Accordion title="App Won't Install">
    * Drag the `.app` file directly (not a folder)
    * Restart iOS Simulator
    * Check simulator iOS version matches deployment target
  </Accordion>

  <Accordion title="Build Folder Missing">
    Manual path:

    ```
    ~/Library/Developer/Xcode/DerivedData/[ProjectName]/Build/Products/Debug-iphonesimulator/
    ```
  </Accordion>
</AccordionGroup>