migrating-to-tuist-generated-projects

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrating to Tuist Generated Projects

迁移到Tuist生成的项目

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.

使用xcodebuild完成基准构建并运行应用。
清点目标、构建设置和外部依赖。

创建

Tuist.swift

、

Project.swift

和

Tuist/Package.swift

文件。

将设置提取到
```
.xcconfig
```
文件中，并在
```
Project.swift
```
中关联配置。
生成并构建：执行
```
tuist generate --no-open
```
，随后执行
```
xcodebuild build
```
。
修复构建问题，重新生成并在模拟器上验证运行时效果。

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)

主应用scheme及所有扩展/测试scheme
目标列表（应用、扩展、测试、辅助工具）
部署目标和Bundle标识符
Info.plist位置与权限配置
自定义构建设置（按目标和配置划分）
外部依赖（SPM、XCFrameworks、本地包）
构建脚本（SwiftGen、Sourcery、代码生成）
运行时验证计划（模拟器目标和启动命令）

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

```
Project.swift
```
和
```
Tuist.swift
```
用于外部依赖的
```
Tuist/Package.swift
```
```
.xcconfig
```
文件（可选但推荐）
构建与运行时验证说明
包含决策与修复记录的简短迁移日志

Migration Workflow

迁移工作流

1. Baseline the project

1. 基准化项目

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

bash

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

首先确认当前项目能够构建并运行。记录所使用的命令，以便用相同方式验证生成的工作区。

bash

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

2. Map targets and settings

2. 映射目标与设置

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.

列出所有目标及其作用。当构建设置内容较多或跨目标共享时，将其提取到

.xcconfig

文件中。保持部署目标和Bundle标识符与原项目一致，避免运行时异常。

3. Add Tuist manifests

3. 添加Tuist清单文件

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.

创建清单文件，保持内容精简并贴近现有项目。

```
Tuist.swift
```
：启用所需的生成选项并明确配置。
```
Project.swift
```
：定义目标、源码、资源、脚本和依赖。
```
Tuist/Package.swift
```
：列出外部依赖并映射产品类型。

使用

.external

处理第三方依赖，确保依赖图一致。

4. Handle sources and resources carefully

4. 谨慎处理源码与资源

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")
```
.

此步骤需精准操作，小失误可能导致后续出现严重问题。

```
.intentdefinition
```
文件属于
```
sources
```
，而非
```
resources
```
。
```
.xcstrings
```
应作为主要本地化源。避免通过重叠的通配符重复包含
```
.strings
```
或
```
.stringsdict
```
文件。
对于
```
Settings.bundle
```
这类 bundle，使用
```
.folderReference
```
。
如果缺少资源bundle，请确保包目标声明了
```
.process("Resources")
```
。

5. Generate and build

5. 生成并构建

bash

tuist install
tuist generate --no-open
xcodebuild build \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Debug \
  -destination "generic/platform=iOS Simulator" \
  -derivedDataPath DerivedDataTuist

bash

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

6. 迭代解决构建问题

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.

以下是你可能需要的常见修复方案：

缺失SDK框架：添加
```
.sdk(name: ..., type: .framework)
```
。
SPM资源bundle：验证
```
.process("Resources")
```
和
```
Bundle.module
```
的使用。
文件系统同步组：避免过度排除目录；如果某个类型消失，与pbx文件对比检查。
无效Bundle标识符：通过
```
PackageSettings
```
覆盖，或使用本地包托管。
生成的源码：确保代码生成输出（SwiftGen/Sourcery）已纳入构建流程。

7. Validate runtime

7. 验证运行时效果

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

bash

xcrun simctl boot "iPhone 17 Pro"
xcrun simctl install booted DerivedDataTuist/Build/Products/Debug-iphonesimulator/App.app
xcrun simctl launch booted com.example.app

仅构建成功还不够，需在模拟器上启动应用。

bash

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.

类型未找到：意外排除了某个源码文件或整个目录。
复制Bundle资源错误：Swift文件被当作资源处理；修复资源通配符。
本地化冲突：
```
.xcstrings
```
与
```
.strings
```
通配符冲突。
未定义符号：缺失SDK框架或依赖产品。
启动时未识别的选择器：静态框架中的ObjC分类被剥离。向
```
OTHER_LDFLAGS
```
添加
```
-ObjC
```
，或为定义分类的库添加
```
-force_load
```
。
启动时运行时崩溃：Bundle ID不匹配、缺少权限配置或资源关联错误。

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

```
Project.swift
```
中的变更及原因
任何排除或覆盖操作（及其原因）
依赖补丁或本地托管
用于验证的精确构建与运行命令

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

生成的工作区可干净构建
应用在模拟器上启动后无立即崩溃
所有目标和扩展均可构建
依赖通过
```
.external
```
关联
设置与原Xcode项目匹配