Migrate from Xcode Projects

Step-by-step guide to migrate your existing Xcode project to Tuist

Overview

Migrating an existing Xcode project to Tuist allows you to gain better control over your project structure, enable powerful features like binary caching, and simplify dependency management. This guide walks you through the migration process step by step.

Manual migration is an excellent opportunity to clean up accumulated complexity in your Xcode projects. Your team and Xcode will benefit from a simpler, more consistent project structure.

Before You Begin

Prerequisites

• Xcode installed on your Mac
• Tuist CLI installed (curl -Ls https://install.tuist.io | bash)
• Basic familiarity with your current project structure
• Backup of your existing project (commit all changes to git)

Understanding the Benefits

Migrating to Tuist provides:

• Consistency: Projects are defined declaratively and remain simple over time
• Faster builds: Enable binary caching and selective testing
• Better collaboration: Fewer merge conflicts in project files
• Dependency management: Unified approach to external dependencies
• Graph validation: Automatic detection of dependency cycles and issues

Migration Process

Troubleshooting

Compilation Errors Due to Missing Files

If files aren’t contained in directories matching the target structure:

Ensure the list of files after generation matches the original Xcode project. Use this opportunity to align file structure with target structure.

Compare source lists:

# List files in original target
xcodebuild -project MyApp.xcodeproj -target TargetName -showBuildSettings | grep SOURCES

# List files in generated project
tuist generate
xcodebuild -project MyApp-Tuist.xcodeproj -target TargetName -showBuildSettings | grep SOURCES

Build Settings Conflicts

If you encounter conflicts between project and target settings:

1. Review the extracted .xcconfig files
2. Ensure inheritance is correct using $(inherited)
3. Remove duplicate settings between project and target levels

Dependency Graph Cycles

Tuist validates the dependency graph and will error on cycles:

tuist graph

Review the graph visualization to identify and break circular dependencies.

External Dependencies Not Found

If external dependencies aren’t resolving:

# Force reinstall dependencies
rm -rf Tuist/Dependencies
tuist install
tuist generate

Test Target Configuration

If tests fail after migration:

1. Verify the test target has .xctest dependency
2. Check that test host configuration matches the original
3. Ensure test resources are properly included

Migration Checklist

Use this checklist to track your migration progress:

• Create Tuist scaffold files
• Set up CI validation pipeline
• Extract project build settings to xcconfig
• Extract package dependencies
• Determine target migration order
• Migrate each target (create separate PRs)
  • Extract target build settings
  • Define target in Project.swift
  • Validate builds successfully
  • Migrate associated test target
  • Validate tests pass
• Update CI/CD pipelines
• Remove old .xcodeproj file
• Update team documentation

Next Steps

After completing the migration:

Enable Binary Caching

Speed up builds with Tuist’s binary caching feature

Optimize Project Structure

Learn best practices for organizing your Tuist projects

Manage Dependencies

Master dependency management with Tuist

Set Up CI/CD

Configure continuous integration for your Tuist project