MovieMapper/docs/BUILD-DISTRIBUTION.md

MovieMapper iOS - Build & Distribution (Phase 6)

Overview

This document describes the build system, CI/CD automation, and distribution tools for the MovieMapper iOS app.

Directory Structure

MovieMapper/
├── build.sh              # Build for simulator and device
├── archive.sh            # Create Xcode archive
├── export-ipa.sh         # Export IPA from archive (optional)
├── run-tests.sh          # Run all tests
├── ExportOptions.plist   # Export configuration
├── build-settings.xcconfig  # Build settings
├── .github/
│   └── workflows/
│       ├── build.yml     # Build automation
│       └── test.yml      # Test automation
└── MovieMapper-iOS/      # Xcode project

Build Scripts

1. build.sh - Build for Simulator and Device

Usage:

./build.sh [simulator|device] [Debug|Release]

Examples:

# Build for simulator (Debug)
./build.sh simulator

# Build for device (Release)
./build.sh device Release

# Build for simulator (Debug)
./build.sh simulator Debug

What it does:

• Builds the Xcode project for the specified target
• Uses iPad Pro (12.9-inch) simulator as default
• Sets appropriate SDK and destination
• Validates build configuration

Environment Variables:

• TVDB_API_KEY - TheTVDB API key (from .env file)

---

2. archive.sh - Create Xcode Archive

Usage:

./archive.sh [Debug|Release] [ArchiveName]

Examples:

# Create release archive
./archive.sh Release MovieMapper-iOS

# Create debug archive with custom name
./archive.sh Debug MovieMapper-iOS-Debug

What it does:

• Creates an .xcarchive file
• Stores archives in archives/ directory
• Uses Release configuration for App Store deployment
• Lists available archives after creation

Output:

archives/
└── MovieMapper-iOS.xcarchive/
    ├── Info.plist
    ├── Products/
    ├── dSYMs/
    └── ...

---

3. export-ipa.sh - Export IPA from Archive

Usage:

./export-ipa.sh [ArchivePath] [ExportOptionsPlist] [OutputDirectory]

Examples:

# Export with App Store options
./export-ipa.sh archives/MovieMapper-iOS.xcarchive ExportOptions.plist

# Export with Ad Hoc options
./export-ipa.sh archives/MovieMapper-iOS.xcarchive ExportOptions-AdHoc.plist ./output

What it does:

• Exports IPA from .xcarchive
• Uses ExportOptions.plist for configuration
• Supports App Store, Ad Hoc, and Enterprise distribution

---

4. run-tests.sh - Run All Tests

Usage:

./run-tests.sh [unit|ui|all]

Examples:

# Run only unit tests
./run-tests.sh unit

# Run only UI tests
./run-tests.sh ui

# Run all tests
./run-tests.sh all

What it does:

• Loads environment variables from .env
• Runs Swift unit tests with swift test
• Runs UI tests with xcodebuild
• Generates test summary reports
• Saves logs to test-results/ directory

Test Results:

test-results/
├── unit-test.log         # Unit test output
├── ui-test.log           # UI test output
├── unit-test.xml         # Unit test summary
└── ui-test.xml           # UI test summary

---

Configuration Files

ExportOptions.plist

Purpose: Configure IPA export for different distribution methods.

Key Settings:

• method: Distribution method (app-store, ad-hoc, enterprise, development)
• teamID: Apple Developer Team ID
• bundleIdentifier: App bundle ID
• codeSignIdentity: Code signing identity
• provisioningProfiles: Provisioning profile mapping

Example Methods:

App Store Distribution:

<key>method</key>
<string>app-store</string>

Ad Hoc Distribution:

<key>method</key>
<string>ad-hoc</string>

Enterprise Distribution:

<key>method</key>
<string>enterprise</string>

build-settings.xcconfig

Purpose: Centralize build settings for Debug and Release configurations.

Key Settings:

Debug Configuration:

• CODE_SIGN_IDENTITY = iPhone Developer
• GCC_OPTIMIZATION_LEVEL = 0 (no optimization)
• ENABLE_TESTABILITY = YES
• DEBUG_INFORMATION_FORMAT = dwarf

Release Configuration:

• CODE_SIGN_IDENTITY = iPhone Distribution
• GCC_OPTIMIZATION_LEVEL = s (optimize for size)
• ENABLE_TESTABILITY = NO
• DEVELOPMENT_TEAM = YourTeamID

Common Settings:

• IPHONEOS_DEPLOYMENT_TARGET = 17.0
• SDKROOT = iphoneos
• ARCHS = arm64
• ENABLE_BITCODE = NO

---

CI/CD Automation

GitHub Actions Workflows

build.yml - Build Workflow

Triggers:

• Push to main, develop, feature/* branches
• Pull requests to main, develop

Jobs:

1. Checkout code - Clone repository
2. Set up Xcode - Install Xcode 15.2
3. Load environment variables - Read .env file
4. Build for Simulator - Debug build
5. Build for Device - Release build
6. Archive App - Create .xcarchive
7. Upload Build Artifacts - Save build outputs
8. Upload Test Results - Save test logs
9. Upload Debug Logs - Save debug logs on failure

Artifacts:

• iOS-App-Build - Archives and IPA files (7 days retention)
• test-results - Test reports (7 days retention)
• debug-logs - Debug logs on failure (7 days retention)

---

test.yml - Test Workflow

Triggers:

• Push to main, develop, feature/* branches
• Pull requests to main, develop

Jobs:

1. Checkout code - Clone repository
2. Set up Xcode - Install Xcode 15.2
3. Load environment variables - Read .env file
4. Run Unit Tests - Execute Swift tests
5. Run UI Tests - Execute UI automation tests
6. Upload Test Results - Save test reports

Test Coverage:

• Unit tests: All service classes
• UI tests: Main views and navigation
• TVDB API tests: Authentication and search

---

Environment Variables

Required Variables

TVDB_API_KEY

• Location: .env file at project root
• Format: TVDB_API_KEY=your-api-key-here
• Usage: Authentication for TheTVDB API

Example .env:

TVDB_API_KEY=aa3699a9-01ac-49a9-836e-3b6123e00140
APP_NAME=MovieMapper
APP_VERSION=1.0.0

CI/CD Environment Variables

GitHub Actions automatically loads .env file:

- name: Load environment variables
  run: |
    if [[ -f .env ]]; then
      export $(grep -v '^#' .env | xargs)
    fi

---

Testing Strategy

Unit Tests

Location: MovieMapper-iOS/Tests/

Test Files:

• FileScannerTests.swift - Directory scanning
• MetadataExtractorTests.swift - FFmpeg metadata extraction
• TVDBClientTests.swift - API integration
• FileMapperTests.swift - File mapping logic
• AuditLoggerTests.swift - Audit logging

Run Unit Tests:

./run-tests.sh unit
swift test -v

UI Tests

Location: MovieMapper-iOS/

Test Features:

• Directory picker
• File list navigation
• Tagging system
• Search functionality
• Episode management

Run UI Tests:

./run-tests.sh ui
xcodebuild test -project MovieMapper-iOS.xcodeproj ...

---

Distribution

App Store Distribution

1. Build Release Archive:

   ./archive.sh Release MovieMapper-iOS
   

2. Export IPA:

   ./export-ipa.sh archives/MovieMapper-iOS.xcarchive ExportOptions.plist
   

3. Upload to App Store:

   • Use Xcode Organizer
   • Or use xcrun altool command

Ad Hoc Distribution

1. Update ExportOptions.plist:

   <key>method</key>
   <string>ad-hoc</string>
   

2. Archive and Export:

   ./archive.sh Release MovieMapper-iOS-AdHoc
   ./export-ipa.sh archives/MovieMapper-iOS-AdHoc.xcarchive ExportOptions-AdHoc.plist
   

3. Distribute to Testers:

   • Upload to TestFlight
   • Or share IPA directly

---

Troubleshooting

Common Issues

1. Build fails with "No such module"

# Clean build directory
./build.sh simulator Debug clean

2. Archive fails

# Check Xcode version
xcodebuild -version

# Verify team ID in ExportOptions.plist

3. Tests fail with API errors

# Verify TVDB_API_KEY is set
echo $TVDB_API_KEY

# Check .env file exists
cat .env

4. Code signing errors

# Check provisioning profiles in Xcode
# Update CODE_SIGN_IDENTITY in build-settings.xcconfig

---

Quick Reference

Task	Command
Build for simulator	./build.sh simulator
Build for device	./build.sh device Release
Create archive	./archive.sh Release
Run all tests	./run-tests.sh all
Run unit tests only	./run-tests.sh unit
Run UI tests only	./run-tests.sh ui

---

Next Steps

1. Update ExportOptions.plist with your Team ID
2. Configure Xcode signing in project settings
3. Set up App Store Connect metadata
4. Configure TestFlight for beta testing
5. Set up GitHub Secrets for CI/CD (if needed)

---

Documentation References

• Phase 1 - Project Setup
• Phase 3 - UI Implementation
• Phase 4 - Testing Strategy
• iOS_PLAN.md - Complete Implementation Plan