marathon/docs/ios-deployment.md

iOS Deployment Guide

This guide covers building and deploying Aspen (built on Marathon engine) to iOS devices and simulators.

Prerequisites

Required Tools

1. Xcode Command Line Tools (not full Xcode IDE)

   xcode-select --install
   

2. Rust iOS targets

   # For simulator (M1/M2/M3 Macs)
   rustup target add aarch64-apple-ios-sim
   
   # For device
   rustup target add aarch64-apple-ios
   

3. iOS Simulator Runtime (one-time download, ~8GB)

   xcodebuild -downloadPlatform iOS
   

Verify Installation

# Check Swift compiler
swiftc --version

# Check iOS SDK
xcrun --sdk iphoneos --show-sdk-path

# List available simulators
xcrun simctl list devices

Building for iOS Simulator

Quick Start

Run all steps in one go:

# From project root
./scripts/ios/build-simulator.sh
./scripts/ios/package-app.sh
./scripts/ios/deploy-simulator.sh

Step-by-Step

1. Build the Binary

cargo build \
    --package app \
    --target aarch64-apple-ios-sim \
    --release

Output: target/aarch64-apple-ios-sim/release/app

2. Package as .app Bundle

iOS apps must be in a specific .app bundle structure:

Aspen.app/
├── app           # The executable binary
├── Info.plist    # App metadata
└── PkgInfo       # Legacy file (APPL????)

Run the packaging script:

./scripts/ios/package-app.sh

Output: target/aarch64-apple-ios-sim/release/Aspen.app/

3. Deploy to Simulator

./scripts/ios/deploy-simulator.sh

This will:

1. Find and boot the iPad Pro 13-inch simulator
2. Open Simulator.app
3. Uninstall any previous version
4. Install the new .app bundle
5. Launch the app with console output

To use a different simulator:

./scripts/ios/deploy-simulator.sh "iPad Air 13-inch (M2)"

Building for Physical Device

Prerequisites

1. Apple Developer Account (free account works for local testing)
2. Device connected via USB
3. Code signing setup

Build Steps

# Build for device
cargo build \
    --package app \
    --target aarch64-apple-ios \
    --release

# Package (similar to simulator)
# TODO: Create device packaging script with code signing

Code Signing

iOS requires apps to be signed before running on device:

# Create signing identity (first time only)
security find-identity -v -p codesigning

# Sign the app bundle
codesign --force --sign "Apple Development: your@email.com" \
    target/aarch64-apple-ios/release/Aspen.app

Deploy to Device

# Using devicectl (modern, requires macOS 13+)
xcrun devicectl device install app \
    --device <UUID> \
    target/aarch64-apple-ios/release/Aspen.app

# Launch
xcrun devicectl device process launch \
    --device <UUID> \
    io.r3t.aspen

Project Structure

lonni/
├── crates/
│   ├── app/                    # Aspen application
│   └── libmarathon/            # Marathon engine
│       ├── src/platform/
│       │   ├── ios/
│       │   │   ├── executor.rs         # iOS winit executor
│       │   │   ├── pencil_bridge.rs    # Rust FFI
│       │   │   ├── PencilBridge.h      # C header
│       │   │   └── PencilCapture.swift # Swift capture
│       │   └── ...
│       └── build.rs            # Swift compilation
├── scripts/
│   └── ios/
│       ├── Info.plist          # App metadata template
│       ├── build-simulator.sh  # Build binary
│       ├── package-app.sh      # Create .app bundle
│       └── deploy-simulator.sh # Install & launch
└── docs/
    └── ios-deployment.md       # This file

App Bundle Configuration

Info.plist

Key fields in scripts/ios/Info.plist:

<key>CFBundleIdentifier</key>
<string>io.r3t.aspen</string>

<key>CFBundleName</key>
<string>Aspen</string>

<key>MinimumOSVersion</key>
<string>14.0</string>

To customize, edit scripts/ios/Info.plist before packaging.

Apple Pencil Support

Aspen includes native Apple Pencil support via the Marathon engine:

• Pressure sensitivity (0.0 - 1.0)
• Tilt angles (altitude & azimuth)
• Touch phases (began/moved/ended/cancelled)
• Timestamps for precision input

The Swift → Rust bridge is compiled automatically during cargo build for iOS targets.

Troubleshooting

"runtime profile not found"

The iOS runtime isn't installed:

xcodebuild -downloadPlatform iOS

"No signing identity found"

For simulator, signing is not required. For device:

# Check signing identities
security find-identity -v -p codesigning

# If none exist, create one in Xcode or via command line

"Could not launch app"

Check simulator logs:

xcrun simctl spawn booted log stream --predicate 'processImagePath contains "Aspen"'

Swift compilation fails

Ensure the iOS SDK is installed:

xcrun --sdk iphoneos --show-sdk-path

Should output a path like:

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS26.2.sdk

Performance Notes

Simulator vs Device

• Simulator: Runs on your Mac's CPU (fast for development)
• Device: Runs on iPad's chip (true performance testing)

Build Times

• Simulator build: ~30s (incremental), ~5min (clean)
• Device build: Similar, but includes Swift compilation

App Size

• Debug build: ~200MB (includes debug symbols)
• Release build: ~50MB (optimized, stripped)

Next Steps

• Add device deployment script with code signing
• Create GitHub Actions workflow for CI builds
• Document TestFlight deployment
• Add crash reporting integration

References

• Apple Developer Documentation
• Rust iOS Guide
• Winit iOS Platform