debug-generated-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debug Tuist Project Issue

调试Tuist项目问题

Quick Start

快速开始

Ask the user to describe the issue and the project setup (targets, dependencies, configurations, platform).
Confirm the issue exists with the latest release by running
```
mise exec tuist@latest -- tuist generate
```
against a reproduction project.
If confirmed, clone the Tuist repository and build from source to test against main.
Triage: fix the bug and open a PR, advise on misconfiguration, or recommend the user files an issue with a reproduction.

请用户描述问题以及项目设置（目标、依赖项、配置、平台）。
通过针对复现项目运行
```
mise exec tuist@latest -- tuist generate
```
，确认问题在最新版本中是否存在。
如果问题确认存在，克隆Tuist仓库并从源码构建，以针对main分支进行测试。
分类处理：修复Bug并提交PR，指导用户修正配置错误，或建议用户提交包含复现场景的Issue。

Step 1: Gather Context

步骤1：收集上下文信息

Ask the user for:

What command they ran (e.g.
```
tuist generate
```
)
The error message or unexpected behavior
When the issue happens: generation time, compile time, or runtime (app launch or later)
Their project structure: targets, platforms, dependencies (SwiftPM, XCFrameworks, local packages)
Their
```
Project.swift
```
and
```
Tuist.swift
```
content (or relevant excerpts)
Their Tuist version (
```
tuist version
```
)

The answer to "when" determines the verification strategy:

Generation time: the issue might be a Tuist bug or a project misconfiguration. Reproduce with
```
tuist generate
```
.
Compile time: the generated project has incorrect build settings, missing sources, or wrong dependency wiring. Reproduce with
```
xcodebuild build
```
after generation.
Runtime: the app builds but crashes or misbehaves on launch or during use. Reproduce by installing and launching on a simulator.

向用户询问：

他们运行的命令（例如
```
tuist generate
```
）
错误信息或异常行为
问题发生的时机：生成阶段、编译阶段还是运行阶段（应用启动时或之后）
项目结构：目标、平台、依赖项（SwiftPM、XCFrameworks、本地包）
他们的
```
Project.swift
```
和
```
Tuist.swift
```
内容（或相关片段）
他们使用的Tuist版本（
```
tuist version
```
）

“时机”的答案会决定验证策略：

生成阶段：问题可能是Tuist的Bug或项目配置错误。使用
```
tuist generate
```
复现。
编译阶段：生成的项目存在不正确的构建设置、缺失的源码或错误的依赖关联。生成后使用
```
xcodebuild build
```
复现。
运行阶段：应用可以构建，但在启动或使用过程中崩溃或行为异常。通过在模拟器上安装并启动应用来复现。

Step 2: Reproduce with the latest release

步骤2：使用最新版本复现问题

Before investigating the source code, confirm the issue is not already fixed in the latest release.

在研究源码之前，确认问题是否已在最新版本中修复。

Set up a temporary reproduction project

设置临时复现项目

bash

REPRO_DIR=$(mktemp -d)
cd "$REPRO_DIR"

Create minimal

Tuist.swift

Project.swift

, and source files that reproduce the user's scenario. Keep it as small as possible while still triggering the issue.

bash

REPRO_DIR=$(mktemp -d)
cd "$REPRO_DIR"

创建最小化的

Tuist.swift

、

Project.swift

和源码文件，以复现用户的场景。在仍能触发问题的前提下，尽可能保持项目简洁。

Run generation with the latest Tuist release

使用最新Tuist版本运行生成命令

bash

mise exec tuist@latest -- tuist generate --no-open --path "$REPRO_DIR"

If the issue involves dependencies, install them first:

bash

mise exec tuist@latest -- tuist install --path "$REPRO_DIR"

bash

mise exec tuist@latest -- tuist generate --no-open --path "$REPRO_DIR"

如果问题涉及依赖项，请先安装它们：

bash

mise exec tuist@latest -- tuist install --path "$REPRO_DIR"

Check the result

检查结果

If generation succeeds and the issue is gone, tell the user to update to the latest version.
If the issue persists, continue to Step 3.

如果生成成功且问题消失，告知用户更新到最新版本。
如果问题仍然存在，继续步骤3。

Step 3: Build Tuist from Source

步骤3：从源码构建Tuist

Clone the repository and build the

tuist

executable and

ProjectDescription

library from source to test against the latest code on

main

bash

TUIST_SRC=$(mktemp -d)
git clone --depth 1 https://github.com/tuist/tuist.git "$TUIST_SRC"
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry

The built binary will be at

.build/debug/tuist

. Use it to test the reproduction project:

bash

"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"

克隆仓库并从源码构建

tuist

可执行文件和

ProjectDescription

库，以针对main分支的最新代码进行测试。

bash

TUIST_SRC=$(mktemp -d)
git clone --depth 1 https://github.com/tuist/tuist.git "$TUIST_SRC"
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry

构建后的二进制文件位于

.build/debug/tuist

。使用它来测试复现项目：

bash

"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"

If the issue is fixed on main

如果问题在main分支上已修复

Tell the user the fix is already on

main

, and it hasn't been released, tell them it'll be in the nest release and point them to the relevant commit if you can identify it.

告知用户修复已合并到main分支，尚未发布的话，说明会包含在下一个版本中，如果能找到相关提交，可指向该提交。

If the issue persists on main

如果问题在main分支上仍然存在

Continue to Step 4.

继续步骤4。

Step 4: Triage the Issue

步骤4：分类排查问题

Investigate the Tuist source code to understand why the issue occurs.

研究Tuist源码以理解问题发生的原因。

Outcome A: It is a bug

结果A：是Bug

Identify the root cause in the source code.
Apply the fix.

Verify by rebuilding and running against the reproduction project:

bash

cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry
"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"

Zip the reproduction project and include it in the PR:

bash

cd "$REPRO_DIR" && cd ..
zip -r reproduction.zip "$(basename "$REPRO_DIR")" -x '*.xcodeproj/*' -x '*.xcworkspace/*' -x 'Derived/*' -x '.build/*'

Open a PR on the Tuist repository with:
- The fix
- The zipped reproduction project attached or committed as a fixture
- A clear description of the root cause and how to verify the fix

在源码中确定根本原因。
应用修复。

重新构建并针对复现项目运行以验证：

bash

cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry
"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"

将复现项目压缩并包含在PR中：

bash

cd "$REPRO_DIR" && cd ..
zip -r reproduction.zip "$(basename "$REPRO_DIR")" -x '*.xcodeproj/*' -x '*.xcworkspace/*' -x 'Derived/*' -x '.build/*'

在Tuist仓库上提交PR，包含：
- 修复代码
- 附加的压缩复现项目，或作为测试用例提交
- 清晰描述根本原因以及如何验证修复

Outcome B: It is a misconfiguration

结果B：是配置错误

Tell the user what is wrong and how to fix it. Common misconfigurations:

Missing
```
tuist install
```
before
```
tuist generate
```
when using external dependencies
Incorrect source or resource globs that exclude or double-include files
Mismatched build configurations between the project and external dependencies
Wrong product types for dependencies (static vs dynamic)
Missing
```
-ObjC
```
linker flag for Objective-C dependencies
Using
```
sources
```
and
```
resources
```
globs together with
```
buildableFolders
```

Provide the corrected manifest snippet so the user can apply the fix directly.

告知用户问题所在以及修复方法。常见的配置错误包括：

使用外部依赖时，在
```
tuist generate
```
之前未运行
```
tuist install
```
不正确的源码或资源通配符，导致文件被排除或重复包含
项目与外部依赖之间的构建配置不匹配
依赖项的产品类型错误（静态 vs 动态）
Objective-C依赖项缺少
```
-ObjC
```
链接器标志
同时使用
```
sources
```
和
```
resources
```
通配符与
```
buildableFolders
```

提供修正后的清单代码片段，以便用户直接应用修复。

Outcome C: Unclear or needs team input

结果C：问题不明确或需要团队介入

If you cannot determine whether it is a bug or misconfiguration, recommend the user:

Open a GitHub issue at https://github.com/tuist/tuist/issues with:
- The reproduction project (zipped)
- The error output
- Their Tuist version and environment details

Provide a summary of what you investigated and what you ruled out, so the user does not have to repeat the triage.

如果无法确定是Bug还是配置错误，建议用户：

在GitHub上提交Issue：https://github.com/tuist/tuist/issues，包含：
- 压缩后的复现项目
- 错误输出
- 他们的Tuist版本和环境详情

提供你已调查的内容以及排除的可能性的总结，这样用户就无需重复分类排查的步骤。

Build Verification

构建验证

When testing a fix, always verify the full cycle:

bash

undefined

测试修复时，始终验证完整流程：

bash

undefined

Build the patched tuist

构建修复后的tuist

cd "$TUIST_SRC" swift build --product tuist --product ProjectDescription --replace-scm-with-registry

Install dependencies if needed

如果需要，安装依赖项

"$TUIST_SRC/.build/debug/tuist" install --path "$REPRO_DIR"

Generate the project

生成项目

"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"

Build the generated project

构建生成的项目

xcodebuild build
-workspace "$REPRO_DIR"/*.xcworkspace
-scheme <scheme>
-destination "platform=iOS Simulator,name=iPhone 16 Pro"

undefined

xcodebuild build
-workspace "$REPRO_DIR"/*.xcworkspace
-scheme <scheme>
-destination "platform=iOS Simulator,name=iPhone 16 Pro"

undefined

Runtime Verification

运行时验证

When the user reports a runtime issue (crash on launch, missing resources at runtime, wrong bundle structure, or unexpected behavior), you must go beyond building and actually launch the app on a simulator.

当用户报告运行时问题（启动崩溃、运行时缺少资源、错误的Bundle结构或异常行为）时，你必须超越构建步骤，在模拟器上实际启动应用。

Launch and monitor for crashes

启动并监控崩溃情况

bash

undefined

bash

undefined

Boot a simulator

启动模拟器

xcrun simctl boot "iPhone 16 Pro" 2>/dev/null || true

Build for the simulator

为模拟器构建应用

xcodebuild build
-workspace "$REPRO_DIR"/*.xcworkspace
-scheme <scheme>
-destination "platform=iOS Simulator,name=iPhone 16 Pro"
-derivedDataPath "$REPRO_DIR/DerivedData"

Install the app

安装应用

xcrun simctl install booted "$REPRO_DIR/DerivedData/Build/Products/Debug-iphonesimulator/<AppName>.app"

Launch and monitor — this will print crash info if the app terminates abnormally

启动并监控——如果应用异常终止，会打印崩溃信息

xcrun simctl launch --console-pty booted <bundle-identifier>


The `--console-pty` flag streams the app's stdout/stderr so you can observe logs and crash output directly. Watch for:

- **Immediate crash on launch**: usually a missing framework, wrong bundle ID, missing entitlements, or stripped ObjC categories (`-ObjC` linker flag missing)
- **Crash after a few seconds**: often missing resources (images, storyboards, XIBs, asset catalogs) or a bundle structure mismatch
- **Runtime misbehavior without crash**: wrong resource paths, missing localization files, or incorrect Info.plist values

xcrun simctl launch --console-pty booted <bundle-identifier>


`--console-pty`标志会流式传输应用的stdout/stderr，因此你可以直接观察日志和崩溃输出。注意以下情况：

- **启动时立即崩溃**：通常是缺少框架、错误的Bundle ID、缺少权限或Objective-C分类被剥离（缺少`-ObjC`链接器标志）
- **几秒后崩溃**：通常是缺少资源（图片、故事板、XIB、资源目录）或Bundle结构不匹配
- **无崩溃但运行时行为异常**：错误的资源路径、缺少本地化文件或不正确的Info.plist值

Check crash logs

检查崩溃日志

If the app crashes without useful console output, pull the crash log:

bash

undefined

如果应用崩溃但没有有用的控制台输出，提取崩溃日志：

bash

undefined

List recent crash logs for the app

列出应用的近期崩溃日志

find ~/Library/Logs/DiagnosticReports -name "<AppName>*" -newer "$REPRO_DIR" -print


Read the crash log to identify the crashing thread and the faulting symbol.

find ~/Library/Logs/DiagnosticReports -name "<AppName>*" -newer "$REPRO_DIR" -print


读取崩溃日志以确定崩溃线程和故障符号。

Done Checklist

完成检查清单

Gathered enough context from the user to reproduce the issue
Determined whether the issue is at generation time, compile time, or runtime
Confirmed whether the issue exists in the latest release
Tested against Tuist built from source (main branch)
If runtime issue: launched the app on a simulator and verified the crash or misbehavior
Triaged the issue as a bug, misconfiguration, or unclear
If bug: applied fix, verified it, and opened a PR with reproduction project
If misconfiguration: provided corrected manifest to the user
If unclear: gave the user a summary and recommended next steps

从用户处收集了足够的上下文信息以复现问题
确定问题发生在生成阶段、编译阶段还是运行阶段
确认问题在最新版本中是否存在
针对从源码构建的Tuist（main分支）进行了测试
如果是运行时问题：在模拟器上启动应用并验证崩溃或异常行为
将问题分类为Bug、配置错误或不明确
如果是Bug：应用了修复，验证了修复，并提交了包含复现项目的PR
如果是配置错误：向用户提供了修正后的清单
如果不明确：向用户提供了总结并推荐了后续步骤