> ## 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 detects the Xcode build and writes a named profile with its iOS recipe.
Review or fill in the app ID, commands, and output path before the first build.

### Run Build

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

This runs the selected recipe in the cloud. If your profile has a different
name, pass it explicitly; no profile is active/default. See
[Configuration](/remote-builds/configuration).

## 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 require an Apple distribution certificate or
    provisioning profile. Let Xcode apply its default local signature so the
    app retains entitlements used by services such as Keychain. Don't set
    **Code Signing Identity** to "Don't Code Sign" or pass
    `CODE_SIGNING_ALLOWED=NO`.
  </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>


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