Jarian Cottingham
2ce7ab14c9
- Move phase/plan docs into docs/ - Move legacy node:test files into tests/legacy/ with README - Remove .backup file, test audit artifacts, and unused AI prompt/skill files - Remove broken iOS GitHub workflows (reference missing MovieMapper-iOS/)
426 lines
9.0 KiB
Markdown
426 lines
9.0 KiB
Markdown
# 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:**
|
|
```bash
|
|
./build.sh [simulator|device] [Debug|Release]
|
|
```
|
|
|
|
**Examples:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
./archive.sh [Debug|Release] [ArchiveName]
|
|
```
|
|
|
|
**Examples:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
./export-ipa.sh [ArchivePath] [ExportOptionsPlist] [OutputDirectory]
|
|
```
|
|
|
|
**Examples:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
./run-tests.sh [unit|ui|all]
|
|
```
|
|
|
|
**Examples:**
|
|
```bash
|
|
# 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:**
|
|
```xml
|
|
<key>method</key>
|
|
<string>app-store</string>
|
|
```
|
|
|
|
**Ad Hoc Distribution:**
|
|
```xml
|
|
<key>method</key>
|
|
<string>ad-hoc</string>
|
|
```
|
|
|
|
**Enterprise Distribution:**
|
|
```xml
|
|
<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:**
|
|
```bash
|
|
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:
|
|
```yaml
|
|
- 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:**
|
|
```bash
|
|
./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:**
|
|
```bash
|
|
./run-tests.sh ui
|
|
xcodebuild test -project MovieMapper-iOS.xcodeproj ...
|
|
```
|
|
|
|
---
|
|
|
|
## Distribution
|
|
|
|
### App Store Distribution
|
|
|
|
1. **Build Release Archive:**
|
|
```bash
|
|
./archive.sh Release MovieMapper-iOS
|
|
```
|
|
|
|
2. **Export IPA:**
|
|
```bash
|
|
./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:**
|
|
```xml
|
|
<key>method</key>
|
|
<string>ad-hoc</string>
|
|
```
|
|
|
|
2. **Archive and Export:**
|
|
```bash
|
|
./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"**
|
|
```bash
|
|
# Clean build directory
|
|
./build.sh simulator Debug clean
|
|
```
|
|
|
|
**2. Archive fails**
|
|
```bash
|
|
# Check Xcode version
|
|
xcodebuild -version
|
|
|
|
# Verify team ID in ExportOptions.plist
|
|
```
|
|
|
|
**3. Tests fail with API errors**
|
|
```bash
|
|
# Verify TVDB_API_KEY is set
|
|
echo $TVDB_API_KEY
|
|
|
|
# Check .env file exists
|
|
cat .env
|
|
```
|
|
|
|
**4. Code signing errors**
|
|
```bash
|
|
# 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](./MovieMapper-iOS/README.md) - Project Setup
|
|
- [Phase 3](./MovieMapper-iOS/QUICK_REFERENCE.md) - UI Implementation
|
|
- [Phase 4](./MovieMapper-iOS/TESTING.md) - Testing Strategy
|
|
- [iOS_PLAN.md](./iOS_PLAN.md) - Complete Implementation Plan |