crowd-funder-for-time-pwa/docs/ios-build-scripts.md

iOS Build Scripts Documentation

Author: Matthew Raymer Date: 2025-07-11 Status: ✅ COMPLETE - Full iOS build system integration

Overview

The iOS build system for TimeSafari will provide comprehensive support for iOS mobile application development using Capacitor and Xcode. This system will support development, testing, and production environments with optimized builds for each use case.

Note: The iOS build system is now fully implemented and follows the same patterns as the Android and Electron build systems for consistency and maintainability.

Build Script Integration

Package.json Scripts

The iOS build system is fully integrated into package.json with the following scripts:

Basic Build Commands

# Development builds (defaults to --mode development)
npm run build:ios:dev      # Development build
npm run build:ios:test     # Testing build
npm run build:ios:prod     # Production build

Build Type Commands

# Debug builds
npm run build:ios:debug    # Debug app build

# Release builds
npm run build:ios:release  # Release app build

Specialized Commands

# Xcode integration
npm run build:ios:studio   # Build + open Xcode

# Package builds
npm run build:ios:ipa      # Build IPA file
npm run build:ios:app      # Build app bundle

# Utility commands
npm run build:ios:clean    # Clean build artifacts only
npm run build:ios:sync     # Sync Capacitor only
npm run build:ios:assets   # Generate assets only

Legacy Command

# Original script (maintains backward compatibility)
npm run build:ios          # Full build process

Script Usage

Direct Script Usage

The build-ios.sh script supports comprehensive command-line options:

# Basic usage
./scripts/build-ios.sh [options]

# Environment-specific builds
./scripts/build-ios.sh --dev --studio    # Development + open Xcode
./scripts/build-ios.sh --test --ipa      # Testing IPA build
./scripts/build-ios.sh --prod --app      # Production app build

# Utility operations
./scripts/build-ios.sh --clean           # Clean only
./scripts/build-ios.sh --sync            # Sync only
./scripts/build-ios.sh --assets          # Assets only

Command-Line Options

Option	Description	Default
--dev, --development	Build for development environment	✅
--test	Build for testing environment
--prod, --production	Build for production environment
--debug	Build debug app	✅
--release	Build release app
--studio	Open Xcode after build
--ipa	Build IPA file
--app	Build app bundle
--clean	Clean build artifacts only
--sync	Sync Capacitor only
--assets	Generate assets only
-h, --help	Show help message
-v, --verbose	Enable verbose logging

Build Process

Complete Build Flow

1. Resource Check: Validate iOS resources
2. Cleanup: Clean iOS app and build artifacts
3. Capacitor Build: Build web assets with environment-specific mode
4. Xcode Clean: Clean Xcode build cache
5. Xcode Build: Build debug/release app
6. Capacitor Sync: Sync web assets to iOS platform
7. Asset Generation: Generate iOS-specific assets
8. Package Build: Build IPA if requested
9. Xcode Launch: Open Xcode if requested

Environment-Specific Builds

Development Environment (--dev)

# Uses --mode development
npm run build:capacitor
# Builds with development optimizations and debugging enabled

Testing Environment (--test)

# Uses --mode test
npm run build:capacitor -- --mode test
# Builds with testing configurations and test API endpoints

Production Environment (--prod)

# Uses --mode production
npm run build:capacitor -- --mode production
# Builds with production optimizations and live API endpoints

Build Artifacts

App Files

• Debug App: ios/App/build/Debug-iphonesimulator/App.app
• Release App: ios/App/build/Release-iphoneos/App.app

IPA Files

• Release IPA: ios/App/build/Release-iphoneos/App.ipa

Build Locations

# App files
ios/App/build/Debug-iphonesimulator/
ios/App/build/Release-iphoneos/

# IPA files
ios/App/build/Release-iphoneos/

# Xcode build cache
ios/App/build/
ios/App/DerivedData/

Environment Variables

The build system will automatically set environment variables based on the build type:

Capacitor Environment

VITE_PLATFORM=capacitor
VITE_PWA_ENABLED=false
VITE_DISABLE_PWA=true
DEBUG_MIGRATIONS=0

Git Integration

VITE_GIT_HASH=<git-commit-hash>
# Automatically set from current git commit

Error Handling

Exit Codes

Code	Description
1	iOS cleanup failed
2	Web build failed
3	Capacitor build failed
4	Xcode clean failed
5	Xcode build failed
6	Capacitor sync failed
7	Asset generation failed
8	Xcode open failed

iOS-Specific Features

Simulator Support

# Build for iOS Simulator
npm run build:ios:dev --simulator

# Run on specific simulator
xcrun simctl boot "iPhone 15 Pro"
xcrun simctl install booted ios/App/build/Debug-iphonesimulator/App.app

Device Deployment

# Build for physical device
npm run build:ios:dev --device

# Install on connected device
xcrun devicectl device install app --device <device-id> ios/App/build/Debug-iphoneos/App.app

Code Signing

# Development signing
npm run build:ios:dev --development-team <team-id>

# Distribution signing
npm run build:ios:prod --distribution-certificate <cert-id>

Asset Generation

iOS-Specific Assets

# Generate iOS assets
npx capacitor-assets generate --ios

# Assets generated
ios/App/App/Assets.xcassets/
├── AppIcon.appiconset/
├── Splash.imageset/
└── SplashDark.imageset/

Asset Requirements

• App Icon: 1024x1024 PNG (App Store requirement)
• Splash Screens: Multiple sizes for different devices
• Launch Images: Optimized for fast app startup

Xcode Integration

Xcode Project Structure

ios/App/
├── App.xcodeproj/          # Xcode project file
├── App.xcworkspace/        # Xcode workspace
├── App/                    # iOS app source
│   ├── AppDelegate.swift   # App delegate
│   ├── Info.plist         # App configuration
│   └── Assets.xcassets/   # App assets
└── Podfile                # CocoaPods dependencies

Xcode Build Configurations

• Debug: Development with debugging enabled
• Release: Production with optimizations
• Ad Hoc: Testing distribution
• App Store: App Store distribution

Development Workflow

Daily Development

# Development build
npm run build:ios:dev

# Open in Xcode
npm run build:ios:studio

# Run on simulator
xcrun simctl launch booted app.timesafari.app

Testing Workflow

# Test build
npm run build:ios:test

# Run tests
cd ios/App && xcodebuild test -workspace App.xcworkspace -scheme App -destination 'platform=iOS Simulator,name=iPhone 15 Pro'

Production Workflow

# Production build
npm run build:ios:prod

# Create IPA for distribution
npm run build:ios:ipa:prod

# Upload to App Store Connect
xcrun altool --upload-app -f ios/App/build/Release-iphoneos/App.ipa -t ios -u <apple-id> -p <app-specific-password>

Troubleshooting

Common Issues

Build Failures

# Clean Xcode build
cd ios/App && xcodebuild clean -workspace App.xcworkspace -scheme App

# Clean Capacitor
npx cap clean ios

# Rebuild
npm run build:ios:dev

Simulator Issues

# Reset simulator
xcrun simctl erase all

# List available simulators
xcrun simctl list devices

# Boot specific simulator
xcrun simctl boot "iPhone 15 Pro"

Code Signing Issues

# Check certificates
security find-identity -v -p codesigning

# Check provisioning profiles
ls ~/Library/MobileDevice/Provisioning\ Profiles/

Debug Mode

Enable verbose logging for iOS builds:

# Verbose mode
./scripts/build-ios.sh --verbose

# Xcode verbose build
cd ios/App && xcodebuild -workspace App.xcworkspace -scheme App -configuration Debug -verbose

Performance Considerations

Build Performance

• Incremental Builds: Only rebuild changed files
• Parallel Processing: Multi-core build optimization
• Caching: Xcode build cache utilization
• Asset Optimization: Image compression and optimization

Runtime Performance

• App Launch Time: Optimized splash screens and assets
• Memory Usage: Efficient image loading and caching
• Battery Life: Background task optimization
• Network Performance: Efficient API communication

Security Considerations

iOS Security Features

• App Sandboxing: Isolated app environment
• Code Signing: Digital signature verification
• Entitlements: Controlled access to system resources
• App Transport Security: Secure network communication

Build Security

• Environment Isolation: Separate dev/test/prod environments
• Secret Management: Secure handling of API keys
• Dependency Scanning: Regular security audits
• Code Signing: Secure certificate management

Future Enhancements

Planned Features

• CI/CD Integration: Automated build pipelines
• Test Automation: Automated testing framework
• Performance Monitoring: Build and runtime performance tracking
• Asset Optimization: Advanced image and code optimization

Platform Expansion

• App Store: App Store distribution optimization
• TestFlight: Beta testing integration
• Enterprise Distribution: Enterprise app distribution
• Universal Links: Deep linking support

Current Status

✅ Phase 1: Foundation (Complete)

• Create build-ios.sh script
• Implement basic build functionality
• Add environment management
• Integrate with package.json

✅ Phase 2: Advanced Features (Complete)

• Add Xcode integration
• Implement asset generation
• Add simulator support
• Add device deployment

✅ Phase 3: Optimization (Complete)

• Performance optimization
• Error handling improvements
• Documentation completion
• Testing and validation

---

Last Updated: 2025-07-11 Version: 1.0.3-beta Status: Production Ready