# 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

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

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

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

#### Specialized Commands

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

```bash
# 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:

```bash
# 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`)

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

#### Testing Environment (`--test`)

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

#### Production Environment (`--prod`)

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

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

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

### Git Integration

```bash
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

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

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

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

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

```bash
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

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

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

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Check certificates
security find-identity -v -p codesigning

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

### Debug Mode

Enable verbose logging for iOS builds:

```bash
# 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)
- [x] Create `build-ios.sh` script
- [x] Implement basic build functionality
- [x] Add environment management
- [x] Integrate with package.json

### ✅ Phase 2: Advanced Features (Complete)
- [x] Add Xcode integration
- [x] Implement asset generation
- [x] Add simulator support
- [x] Add device deployment

### ✅ Phase 3: Optimization (Complete)
- [x] Performance optimization
- [x] Error handling improvements
- [x] Documentation completion
- [x] Testing and validation

---

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