> ## 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

> Build a native iOS app for Revyl and run it in the dev loop.

Prompt for your coding agent:

```text
Set up Revyl for this native iOS app.

Read https://docs.revyl.com/frameworks/ios.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.

Build the app's main scheme in the Debug configuration for the simulator (`-sdk iphonesimulator`). Revyl runs the `.app`, not an `.ipa`.

You're done when a Revyl build of the app succeeds and the app runs on a cloud iOS simulator.

Ask me before anything that needs my login or approval.
```

## Build Guidance

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

To capture sanitizer findings, upload a simulator build compiled with the corresponding sanitizer enabled. See [iOS runtime diagnostics](/tests/reports#ios-runtime-diagnostics) for supported diagnostics and how to view findings.

## Build via the Revyl CLI

### Prerequisites

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

### Setup

Initialize the project using the Revyl CLI:

```bash
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](/reference/cli/configuration).

## 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
# 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">
    Revyl's simulators run `arm64`, so your simulator build must include an
    `arm64` slice:

    1. Select your target → **Build Settings**
    2. Find **Architectures** and verify `Standard Architectures - $(ARCHS_STANDARD)`
    3. Find **Excluded Architectures** and make sure `arm64` is not excluded
       for `Any iOS Simulator SDK`, in your target or in your Pods project

    Check the result with `lipo -archs YourApp.app/YourApp`; the output must
    include `arm64`.
  </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>

## Dev loop

### Swift/iOS

Native iOS uses a rebuild-based dev loop. The CLI detects `.xcodeproj` / `.xcworkspace` and configures `xcodebuild`. During `revyl dev`, press `[r]` to rebuild and reinstall. Typical rebuild cycle: ~20-60s.

If an Expo or React Native project is detected as native iOS, run
`revyl init --detect` from the app directory. If detection still cannot resolve
the monorepo layout, edit `build.framework` and the generated profile recipes
in `.revyl/config.yaml`, then run `revyl config validate`.