Unless you bootstrap a new project using Tuist, in which case you get everything configured automatically, you'll have to define your Xcode projects using Tuist's primitives (e.g. Project.swift and Workspace.swift files). How tedious this process is, depends on how complex your projects are.
As you probably know, Xcode projects can become messy and complex over time: groups that don't match the directory structure, files that are shared across targets, or file references that point to nonexisting files (to mention some). All that accumulated complexity makes it hard for us to provide a command that reliably ports migrates project.
Moreover, manual migration is an excellent exercise to clean up and simplify your projects. Not only the developers in your project will be thankful for that, but Xcode, who will be faster processing and indexing them. Once you have fully adopted Tuist, it will make sure that projects are consistently defined and that they remain simple.
In the aim of easing that work, we are giving you some guidelines based on the feedback that we have received from the users.
Extract your build settings into
The leaner the projects, the easier they are to migrate. To make them thinner, you can extract information like build settings that can be defined outside Xcode projects. You must prevent developers from defining settings using build settings.
You can use this snippet for that:
# Extract target build settingstuist migration settings-to-xcconfig -p Project.xcodeproj -t MyApp -x MyApp.xcconfig # Extract project build settingstuist migration settings-to-xcconfig -p Project.xcodeproj -x MyAppProject.xcconfig
After extracting the build settings into
.xcconfig files, we recommend adding a check in continuous integration to ensure that build settings are not set to the project:
tuist migration check-empty-settings -p Project.xcodeproj -t MyApp
Those are usually simpler since they contain fewer dependencies than the rest. That makes them good candidates from which we can start the migration. Use this command to list the targets of a project, sorted by number of dependencies. We recommend starting from the top, with the target that has the lowest number of dependencies
tuist migration list-targets -p Project.xcodeproj
Go through your target sources and resources build phases, and delete references to files that are missing. Although Xcode's build system ignores them, they might complicate the migration.
There might be files that were once part of the project,
but that they are no longer needed.
Find and remove them.
you might run into compilation issues because your glob patterns (e.g.
**/*.swift) ended up matching them,
and adding them as sources of your targets.
After the migration of each project, add a script that fails CI if someone modifies the Xcode project directly, and lets developers know that they should change the manifest files instead.
You can use a tool like xcdiff for that.
They allow defining your own abstractions for defining your projects,
and most importantly,
they allow reusing content across all your manifest files.
One of the most common use cases is defining functions that act as factories of templated projects.
After migrating all your projects,
go through the
Project.swift files to identify common patterns and extract them into helpers.
Here's a list of community-developed tools that can aid you on the migration process: