Migrating to Tuist Generated Projects

Quick Start

Baseline build and run the app with xcodebuild.

Inventory targets, build settings, and external dependencies.

Create

Tuist.swift

,

Project.swift

, and

Tuist/Package.swift

.

Extract settings into

.xcconfig

files and wire them in

Project.swift

.

Generate and build:

tuist generate --no-open

then

xcodebuild build

.

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.

Tuist.swift

enable generation options you need and keep them explicit.

Project.swift

define targets, sources, resources, scripts, and dependencies.

Tuist/Package.swift

list external dependencies and map product types.

Use

.external

for third-party dependencies to keep the graph consistent.

4. Handle sources and resources carefully

Be precise here. Small mistakes often cause large failures later.

.intentdefinition

files belong in

sources

, not

resources

.

.xcstrings

should remain the primary localization source. Avoid double-including

.strings

or

.stringsdict

from overlapping globs.

Use

.folderReference

for bundles like

Settings.bundle

.

If a resource bundle is missing, ensure the package target declares

.process("Resources")

.

5. Generate and build

tuist

install

tuist generate --no-open

xcodebuild build

\

-workspace

App.xcworkspace

\

-scheme

App

\

-configuration

Debug

\

-destination

"generic/platform=iOS Simulator"

\

-derivedDataPath

DerivedDataTuist

6. Resolve build issues iteratively

Common fixes you will likely need:

Missing SDK frameworks

add

.sdk(name: ..., type: .framework)

.

SPM resource bundles

verify

.process("Resources")

and

Bundle.module

usage.

File-system-synchronized groups

avoid over-excluding directories; compare with the pbx if a type vanishes.

Invalid bundle identifiers

override with

PackageSettings

or vendor a local package.

Generated sources

ensure codegen outputs (SwiftGen/Sourcery) are part of the build.

7. Validate runtime

A build is not enough; launch the app on a simulator.

xcrun simctl boot

"iPhone 17 Pro"

xcrun simctl

install

booted DerivedDataTuist/Build/Products/Debug-iphonesimulator/App.app

xcrun simctl launch booted com.example.app

Common Failure Patterns

Type not found

a source file or entire directory was excluded accidentally.

Copy Bundle Resources errors

Swift files are being treated as resources; fix the resource globs.

Localization conflicts

:

.xcstrings

colliding with

.strings

globs.

Undefined symbols

missing SDK frameworks or dependency products.

Unrecognized selector at launch

ObjC categories in static frameworks were stripped. Add

-ObjC

to

OTHER_LDFLAGS

or

-force_load

for the library that defines the category.

Runtime crash on launch

mismatched bundle id, missing entitlements, or miswired resources. Migration Notes to Capture What changed in Project.swift and why Any exclusions or overrides (and the reason) Dependency patches or local vendoring The exact build and run commands used for validation Done Checklist Generated workspace builds cleanly App launches on simulator without immediate crash All targets and extensions build Dependencies are wired through .external Settings match the original Xcode project