Build for iOS

Complete guide to building SatSigner for iOS devices and simulators, including Xcode setup, CocoaPods, and troubleshooting

Overview

This guide covers building SatSigner for iOS devices and simulators. The build process uses Expo with React Native and requires Xcode, CocoaPods, and proper environment configuration.

iOS development requires macOS. You cannot build iOS apps on Windows or Linux.

Prerequisites

Required Software

• macOS (latest version recommended)
• Node.js version 22.4.0 or higher
• Yarn package manager
• Xcode (latest stable version from Mac App Store)
• CocoaPods (will be installed via Xcode)
• Xcode Command Line Tools

Install Yarn

If you don’t have Yarn installed:

npm install --global yarn

Xcode Setup

Install Xcode

1. Open the Mac App Store
2. Search for “Xcode”
3. Click Install (this may take 30-60 minutes)
4. Open Xcode after installation to accept the license agreement

Install Command Line Tools

After installing Xcode:

xcode-select --install

Verify installation:

xcode-select -p
# Should output: /Applications/Xcode.app/Contents/Developer

Configure Xcode

1. Open Xcode
2. Go to Xcode → Settings → Locations
3. Ensure Command Line Tools is set to your Xcode version
4. Go to Xcode → Settings → Accounts
5. Add your Apple ID (required for device deployment)

CocoaPods Setup

CocoaPods manages iOS dependencies. It should be installed with Xcode, but verify:

pod --version

If not installed:

sudo gem install cocoapods

Expo Environment Setup

Follow the Expo documentation with these settings:

• Select “Development build”
• Disable “Build with Expo Application Services (EAS)”

Do NOT run npx expo start directly. Use the build commands below instead.

Installation

From the repository root:

# Install dependencies
yarn install

# Navigate to mobile app
cd apps/mobile

# Install iOS pods
cd ios
pod install
cd ..

The pod install command:

• Reads the Podfile configuration
• Downloads and links native iOS dependencies
• Generates satsigner.xcworkspace

Podfile Configuration

The iOS build uses several key configurations from apps/mobile/ios/Podfile:

Deployment Target

• Minimum iOS version: 13.4
• Configurable in Podfile.properties.json

React Native Architecture

• Hermes Engine: Enabled by default (can be configured)
• New Architecture: Configurable via newArchEnabled in Podfile.properties.json

Key Dependencies

• Expo modules via use_expo_modules!
• React Native pods via use_react_native!
• Native modules via use_native_modules!

Building and Running

Standard Build

Build and run the app on a simulator:

yarn ios

This command:

1. Installs CocoaPods dependencies (if needed)
2. Compiles the iOS project
3. Installs the development build on default simulator
4. Starts the Metro bundler
5. Launches the app

Alternative: Expo CLI

npx expo run:ios

Run on Specific Simulator

List available simulators:

xcrun simctl list devices

Run on specific device:

yarn ios --simulator="iPhone 15 Pro"

Run on Physical Device

1. Connect your iOS device via USB
2. Trust the computer on your device when prompted
3. In Xcode, open apps/mobile/ios/satsigner.xcworkspace
4. Select your device from the device dropdown
5. Go to Signing & Capabilities tab
6. Select your development team
7. Run: yarn ios --device

Or build directly in Xcode:

1. Open apps/mobile/ios/satsigner.xcworkspace
2. Select your device
3. Click the Play button or press ⌘ + R

Build Configuration

Workspace Structure

• Podfile - CocoaPods dependency configuration
• Podfile.properties.json - Build properties (deployment target, JS engine)
• satsigner.xcworkspace - Main workspace (generated by CocoaPods)
• satsigner.xcodeproj - Xcode project file

Important Build Settings

Configured in Podfile:

platform :ios, '13.4'  # Minimum iOS version

# Hermes JS engine (default)
hermes_enabled: true

# Flipper debugging (disabled by default)
flipper_config: FlipperConfiguration.disabled

Troubleshooting

Pod Install Fails

Clear CocoaPods cache and reinstall:

cd apps/mobile/ios
rm -rf Pods Podfile.lock
pod cache clean --all
pod install

Xcode Build Fails: “Command PhaseScriptExecution failed”

This usually indicates a Metro bundler issue:

1. Stop all Metro instances: pkill -f metro
2. Clear Metro cache: yarn start --reset-cache
3. Clean build folder in Xcode: ⌘ + Shift + K
4. Rebuild: ⌘ + B

Code Signing Error

Ensure you have a valid development team:

1. Open satsigner.xcworkspace in Xcode
2. Select the project in the navigator
3. Go to Signing & Capabilities
4. Select a valid team from the dropdown
5. If no team appears, add your Apple ID in Xcode Settings → Accounts

Simulator Not Found

Install additional simulators:

1. Open Xcode
2. Go to Xcode → Settings → Platforms
3. Click + to download simulator runtimes
4. Install desired iOS versions

Build Error: “use_frameworks! linkage”

This occurs when frameworks configuration conflicts:

1. Open Podfile
2. Check use_frameworks! linkage setting
3. If using frameworks, note that Flipper won’t work
4. Run pod install after changes

Metro Bundler Won’t Start

Manually start Metro in a separate terminal:

cd apps/mobile
yarn start

Then run the build in another terminal:

yarn ios

Clean Build

If experiencing persistent issues, perform a full clean:

# Clean CocoaPods
cd apps/mobile/ios
rm -rf Pods Podfile.lock
pod install

# Clean Xcode build cache
cd ..
rm -rf ~/Library/Developer/Xcode/DerivedData

# Clean Metro cache
yarn start --reset-cache

“Module not found” Errors

Reinstall dependencies and pods:

cd apps/mobile
rm -rf node_modules
yarn install
cd ios
pod install

Hermes Engine Issues

If you need to disable Hermes:

1. Edit apps/mobile/ios/Podfile.properties.json
2. Set "expo.jsEngine": "jsc" (JavaScriptCore instead of Hermes)
3. Run pod install
4. Clean and rebuild

Device Not Trusted

If deploying to physical device:

1. Go to device Settings → General → VPN & Device Management
2. Find your developer certificate
3. Tap Trust

Build Scripts

Available commands from package.json:

{
  "ios": "expo run:ios",           // Build and run iOS
  "sb:ios": "EXPO_PUBLIC_STORYBOOK_ENABLED=true expo run:ios"  // Build with Storybook
}

Advanced Configuration

Change Deployment Target

Edit apps/mobile/ios/Podfile.properties.json:

{
  "ios.deploymentTarget": "14.0"
}

Then run pod install.

Enable New Architecture

Edit apps/mobile/ios/Podfile.properties.json:

{
  "newArchEnabled": "true"
}

Then:

cd ios
rm -rf Pods Podfile.lock
pod install

Custom Build Configurations

1. Open satsigner.xcworkspace in Xcode
2. Select project → Info tab
3. Manage Configurations (Debug, Release, etc.)
4. Duplicate and customize as needed

Performance Optimization

Release Build

For production/testing with optimizations:

yarn ios --configuration Release

Or in Xcode:

1. Product → Scheme → Edit Scheme
2. Change Build Configuration to “Release”
3. Build and run

Reduce Build Time

Add to Podfile before target 'satsigner':

install! 'cocoapods',
  :deterministic_uuids => false,
  :disable_input_output_paths => true

Next Steps

• Build for Android - Build for Android devices
• Storybook - Component development workflow
• Contributing - Contribution guidelines

Additional Resources

• Expo iOS Development
• CocoaPods Documentation
• Xcode Documentation
• React Native iOS Setup