debug-generated-project

Tuist プロジェクトの問題をデバッグする

クイックスタート

1. 問題の内容とプロジェクトの構成（ターゲット、依存関係、構成、プラットフォーム）をユーザーに尋ねます。
2. 再現用プロジェクトに対して mise exec tuist@latest -- tuist generate を実行し、最新リリースで問題が発生することを確認します。
3. 問題を確認できた場合は、Tuist リポジトリをクローンし、ソースからビルドして main でテストします。
4. トリアージを行います。バグを修正して PR を作成するか、設定ミスについて助言するか、再現手順を添えて問題を報告するようユーザーに案内します。

ステップ 1：状況を確認する

ユーザーに次の情報を尋ねます。

• 実行したコマンド（例：tuist generate）
• エラーメッセージまたは予期しない動作
• 問題が発生するタイミング：生成時、コンパイル時、実行時（アプリの起動時または起動後）
• プロジェクトの構成：ターゲット、プラットフォーム、依存関係（SwiftPM、XCFrameworks、ローカルパッケージ）
• Project.swift と Tuist.swift の内容（または関連する箇所）
• Tuist のバージョン（tuist version）

「いつ」発生するかによって、検証方法が決まります。

• 生成時：Tuist のバグ、またはプロジェクトの設定ミスの可能性があります。tuist generate で再現します。
• コンパイル時：生成されたプロジェクトのビルド設定に誤りがある、ソースが不足している、または依存関係の接続に問題があります。生成後、xcodebuild build で再現します。
• 実行時：アプリはビルドされますが、シミュレーターにインストールして起動するか、使用中にクラッシュまたは誤動作します。

ステップ 2：最新リリースで再現する

ソースコードを調査する前に、最新リリースですでに修正されている問題ではないことを確認します。

一時的な再現用プロジェクトをセットアップする

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

ユーザーの状況を再現する最小限の Tuist.swift、Project.swift、ソースファイルを作成します。問題を再現できる範囲で、できる限り小さく保ちます。

最新の Tuist リリースで生成を実行する

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

問題が依存関係に関係する場合は、先にインストールします。

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

結果を確認する

• 生成が成功し、問題が解消した場合は、最新バージョンに更新するようユーザーに伝えます。
• 問題が続く場合は、ステップ 3 に進みます。

ステップ 3：Tuist をソースからビルドする

リポジトリをクローンし、tuist 実行ファイルと ProjectDescription ライブラリをソースからビルドして、main の最新コードでテストします。

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 にあります。これを使って再現用プロジェクトをテストします。

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

main で問題が修正されている場合

修正はすでに main にありますが、まだリリースされていないことをユーザーに伝えます。次のリリースに含まれることを伝え、該当するコミットを特定できる場合は、そのコミットを案内します。

main でも問題が続く場合

ステップ 4 に進みます。

ステップ 4：問題をトリアージする

Tuist のソースコードを調査し、問題が発生する理由を把握します。

結果 A：バグである

1. ソースコードから根本原因を特定します。
2. 修正を適用します。
3. 再現用プロジェクトに対して再ビルドして実行し、検証します。

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

4. 再現用プロジェクトを ZIP 圧縮し、PR に含めます。

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

5. Tuist リポジトリで PR を作成し、次の内容を含めます。
   • 修正
   • 添付またはフィクスチャとしてコミットした、ZIP 圧縮済みの再現用プロジェクト
   • 根本原因と修正の検証方法を明確に説明した内容

結果 B：設定ミスである

問題点と修正方法をユーザーに伝えます。よくある設定ミスは次のとおりです。

• 外部依存関係を使用しているのに、tuist generate の前に tuist install を実行していない
• ソースまたはリソースの glob が誤っており、ファイルが除外される、または重複して含まれる
• プロジェクトと外部依存関係のビルド構成が一致していない
• 依存関係のプロダクトタイプが誤っている（静的か動的か）
• Objective-C の依存関係に -ObjC リンカーフラグが設定されていない
• buildableFolders と sources および resources の glob を併用している

ユーザーがそのまま適用できるよう、修正済みのマニフェストのスニペットを提示します。

Outcome C: 不明確、またはチームの判断が必要

バグか設定ミスか判断できない場合は、ユーザーに次の対応を勧めてください。

1. 以下を添えて、https://github.com/tuist/tuist/issues に GitHub issue を作成します。
   • 再現用プロジェクト（ZIP 形式）
   • エラー出力
   • Tuist のバージョンと環境の詳細

調査した内容と除外した原因をまとめ、ユーザーがトリアージを繰り返さなくて済むようにしてください。

ビルドの検証

修正をテストする際は、必ず一連の工程全体を検証してください。

# Build the patched 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"

実行時の検証

ユーザーから実行時の問題（起動時のクラッシュ、実行時に見つからないリソース、誤ったバンドル構造、予期しない動作）の報告を受けた場合は、ビルドだけで終わらせず、シミュレーターでアプリを実際に起動してください。

起動してクラッシュを監視する

# 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>

--console-pty フラグは、アプリの標準出力／標準エラー出力をストリーミングするため、ログやクラッシュ出力を直接確認できます。以下を確認してください。

• 起動直後のクラッシュ：通常、フレームワークの欠落、誤ったバンドル ID、エンタイトルメントの欠落、または ObjC カテゴリのストリップ（リンカーフラグ -ObjC の欠落）が原因です。
• 数秒後のクラッシュ：リソース（画像、ストーリーボード、XIB、アセットカタログ）の欠落、またはバンドル構造の不一致が原因であることがよくあります。
• クラッシュを伴わない実行時の不具合：リソースパスの誤り、ローカライズファイルの欠落、または Info.plist の値の誤りが原因です。

クラッシュログを確認する

アプリが有用なコンソール出力を残さずにクラッシュする場合は、クラッシュログを取得してください。

# List recent crash logs for the app
find ~/Library/Logs/DiagnosticReports -name "<AppName>*" -newer "$REPRO_DIR" -print

クラッシュログを読み、クラッシュしたスレッドと障害が発生したシンボルを特定してください。

完了チェックリスト

• 問題を再現するのに十分な状況をユーザーから収集した
• 問題が生成時、コンパイル時、実行時のいずれに発生するかを特定した
• 最新リリースでも問題が発生することを確認した
• ソースからビルドした Tuist（main ブランチ）でテストした
• 実行時の問題の場合：シミュレーターでアプリを起動し、クラッシュまたは不具合を確認した
• 問題をバグ、設定ミス、不明確のいずれかに分類した
• バグの場合：修正を適用して検証し、再現用プロジェクトを添えて PR を作成した
• 設定ミスの場合：修正済みのマニフェストをユーザーに提供した
• 不明確な場合：ユーザーに概要を伝え、次の手順を提案した