Migrating to Tuist Generated Projects

Quick Start

1. Baseline build and run the app with xcodebuild.
2. Inventory targets, build settings, and external dependencies.
3. Create Tuist.swift, Project.swift, and Tuist/Package.swift.
4. Extract settings into .xcconfig files and wire them in Project.swift.
5. Generate and build: tuist generate --no-open then xcodebuild build.
6. Fix build issues, regenerate, and validate runtime on a simulator.

Preflight Checklist

• Primary app scheme and any extension/test schemes
• Targets list (app, extensions, tests, helper tools)
• Deployment targets and bundle identifiers
• Info.plist locations and entitlements
• Custom build settings (per target and per configuration)
• External dependencies (SPM, XCFrameworks, local packages)
• Build scripts (SwiftGen, Sourcery, codegen)
• Runtime validation plan (simulator destination and launch command)

Outputs

• Project.swift and Tuist.swift
• Tuist/Package.swift for external dependencies
• .xcconfig files (optional but recommended)
• Build and runtime validation notes
• A short migration log of decisions and fixes

Migration Workflow

1. Baseline the project

Start by proving the current project builds and runs. Capture the command you use so the generated workspace can be validated the same way.

xcodebuild build \
  -project App.xcodeproj \
  -scheme App \
  -configuration Debug \
  -destination "generic/platform=iOS Simulator" \
  -derivedDataPath DerivedDataBaseline

2. Map targets and settings

List every target and its role. Extract build settings into .xcconfig files when they are large or shared across targets. Keep deployment targets and bundle identifiers identical to the original project to avoid runtime surprises.

3. Add Tuist manifests

Create the manifests and keep them minimal and close to the existing project.