Tauri iOS Setup and Troubleshooting

Mirrored from iblai/os · docs/tauri-ios-setup.md. This page is generated — edit it in the repository, not here.

Quick Start

The Makefile handles most iOS setup automatically:

# First time setup
make tauri-ios-init

# Development build (opens in simulator)
make tauri-ios-dev

# Production build
make tauri-ios-build

Xcode Build Issues

"cargo: command not found" Error

When building through Xcode (clicking Play button), you may encounter a PhaseScriptExecution error because Xcode cannot find the cargo command.

Solution:

The project includes an automatic fix script that runs with make commands. If you're building directly through Xcode, run this first:

cd apps/mentor
./scripts/fix-xcode-cargo-path.sh

This patches the Xcode project to include ~/.cargo/bin in the PATH.

Why this happens:

Xcode uses a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin) that doesn't include ~/.cargo/bin where Rust/Cargo is installed.

Permanent System-Level Fix (Optional)

For a system-wide solution that works with all Xcode projects:

Option 1: Using launchctl (macOS)

# Add cargo to Xcode's environment
launchctl setenv PATH "$HOME/.cargo/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

# Restart Xcode for changes to take effect
killall Xcode

Note: This needs to be run after every system restart. To make it permanent, create a launch agent:

# Create launch agent directory if it doesn't exist
mkdir -p ~/Library/LaunchAgents

# Create the plist file
cat > ~/Library/LaunchAgents/setenv.PATH.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>setenv.PATH</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>-c</string>
    <string>launchctl setenv PATH $HOME/.cargo/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>
EOF

# Load the launch agent
launchctl load ~/Library/LaunchAgents/setenv.PATH.plist

Option 2: Using /etc/paths.d (requires sudo)

# Add cargo to system PATH (requires admin password)
echo "$HOME/.cargo/bin" | sudo tee /etc/paths.d/cargo

# Restart your terminal and Xcode

Deep Link Configuration

The app supports both custom URL schemes and universal links:

Custom URL Schemes (Development)

Scheme: iblai://
Works in: Development builds, simulators, and production
Configuration: Automatic through Tauri deep-link plugin

Universal Links (Production Only)

Domain: https://mentorai.iblai.app/*
Works in: Production builds only (requires App Store submission)
Requires:
- Apple App Site Association (AASA) file hosted at https://mentorai.iblai.app/.well-known/apple-app-site-association
- Domain verification
- Associated Domains entitlement

Android App Links

Domain: https://mentorai.iblai.app/*
Requires:
- Digital Asset Links file at https://mentorai.iblai.app/.well-known/assetlinks.json
- SHA-256 fingerprint in manifest

Building for Physical Devices

iOS

Open in Xcode:

open apps/mentor/src-tauri/gen/apple/ibl-ai-os.xcodeproj

Configure Signing:
- Select the ibl-ai-os_iOS target
- Go to "Signing & Capabilities"
- Select your development team: L4FWRM8W5Z
- Choose automatic or manual signing
Select Device:
- Connect your iPhone via USB
- Select it from the device dropdown in Xcode
Build and Run:
- Click the Play button (⌘R)
- First build may prompt for keychain access

Android

Build APK:

cd apps/mentor/src-tauri
cargo tauri android build

Install on Device:

Via USB (ADB):
```
adb install src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk
```
Via File Transfer:
- Copy APK to device
- Open file and install
- May need to enable "Install from Unknown Sources"

Troubleshooting

Build fails with "invalid configuration"

Make sure you've removed invalid properties from tauri.conf.json
The plugins.deep-link section should be empty or removed
No urlSchemes in bundle configuration

Deep links not working in development

Universal links (https://) only work in production builds
Use custom URL schemes (iblai://) for development testing

"Could not find module" errors

Run pnpm install in the root directory
Make sure all packages are built: pnpm build:packages

Xcode project regeneration

If you run cargo tauri ios init again, it regenerates the Xcode project
The fix script automatically runs with make commands
Or manually run: ./scripts/fix-xcode-cargo-path.sh