migrating-to-tuist-generated-projects

Tuist 生成プロジェクトへの移行

クイックスタート

1. xcodebuild でアプリをビルドして実行し、ベースラインを確認します。
2. ターゲット、ビルド設定、外部依存関係を一覧にします。
3. Tuist.swift、Project.swift、Tuist/Package.swift を作成します。
4. 設定を .xcconfig ファイルに切り出し、Project.swift で接続します。
5. 生成してビルドします：tuist generate --no-open の後に xcodebuild build を実行します。
6. ビルドの問題を修正して再生成し、シミュレーターで実行時の動作を検証します。

事前チェックリスト

• メインのアプリスキームと、拡張機能／テストの各スキーム
• ターゲットの一覧（アプリ、拡張機能、テスト、ヘルパーツール）
• デプロイメントターゲットとバンドル ID
• Info.plist の場所とエンタイトルメント
• カスタムビルド設定（ターゲットごと、構成ごと）
• 外部依存関係（SPM、XCFramework、ローカルパッケージ）
• ビルドスクリプト（SwiftGen、Sourcery、コード生成）
• 実行時検証の計画（シミュレーターのデスティネーションと起動コマンド）

成果物

• Project.swift と Tuist.swift
• 外部依存関係用の Tuist/Package.swift
• .xcconfig ファイル（任意ですが推奨）
• ビルドおよび実行時検証のメモ
• 決定事項と修正内容を記した簡単な移行ログ

移行ワークフロー

1. プロジェクトのベースラインを確認する

まず、現在のプロジェクトがビルドされ、実行できることを確認します。生成したワークスペースも同じ方法で検証できるよう、使用したコマンドを記録してください。

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

2. ターゲットと設定を整理する

すべてのターゲットとその役割を一覧にします。ビルド設定が多い場合や、複数のターゲットで共有されている場合は、.xcconfig ファイルに切り出します。実行時に予期しない問題が起きないよう、デプロイメントターゲットとバンドル ID は元のプロジェクトと同一に保ってください。

3. Tuist マニフェストを追加する

マニフェストを作成し、最小限にとどめて既存のプロジェクトに近い状態に保ちます。

• Tuist.swift：必要な生成オプションを有効にし、明示的に指定します。
• Project.swift：ターゲット、ソース、リソース、スクリプト、依存関係を定義します。
• Tuist/Package.swift：外部依存関係を列挙し、プロダクトの種類を対応付けます。

依存関係グラフの一貫性を保つには、サードパーティ製の依存関係に .external を使用します。

4. ソースとリソースを慎重に扱う

ここでは正確さが重要です。小さなミスが、後で大きな問題につながることがよくあります。

• .intentdefinition ファイルは resources ではなく sources に含めます。
• .xcstrings を主なローカライズソースとして維持します。重複する glob で .strings や .stringsdict が二重に含まれないようにしてください。
• Settings.bundle などのバンドルには .folderReference を使用します。
• リソースバンドルが見つからない場合は、パッケージターゲットで .process("Resources") が宣言されていることを確認します。

5. 生成してビルドする

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

6. ビルドの問題を反復的に解決する

次のような修正が必要になることがよくあります。

• SDK フレームワークが見つからない：.sdk(name: ..., type: .framework) を追加します。
• SPM リソースバンドル：.process("Resources") と Bundle.module の使用を確認します。
• ファイルシステム同期グループ：ディレクトリを過剰に除外しないでください。型が消えている場合は pbx と比較します。
• 無効なバンドル ID：PackageSettings で上書きするか、ローカルパッケージをベンダリングします。
• 生成ソース：コード生成の出力（SwiftGen／Sourcery）がビルドに含まれていることを確認します。

7. 実行時の動作を検証する

ビルドするだけでは不十分です。シミュレーターでアプリを起動してください。

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

よくある失敗パターン

• 型が見つからない：ソースファイルまたはディレクトリ全体が誤って除外されています。
• Copy Bundle Resources エラー：Swift ファイルがリソースとして扱われています。リソースの glob を修正してください。
• ローカライズの競合：.xcstrings が .strings の glob と競合しています。
• 未定義シンボル：SDK フレームワークまたは依存プロダクトが不足しています。
• 起動時にセレクターが認識されない：静的フレームワーク内の ObjC カテゴリが取り除かれています。OTHER_LDFLAGS に -ObjC を追加するか、そのカテゴリを定義しているライブラリに -force_load を指定します。
• 起動時に実行時クラッシュが発生する：バンドル ID の不一致、エンタイトルメントの不足、またはリソースの接続ミスが原因です。

記録する移行メモ

• Project.swift の変更点とその理由
• 除外やオーバーライド、およびその理由
• 依存関係のパッチまたはローカルへのベンダー同梱
• 検証に使用した正確なビルドおよび実行コマンド

完了チェックリスト

• 生成されたワークスペースが問題なくビルドできる
• アプリがシミュレーター上で起動し、直ちにクラッシュしない
• すべてのターゲットと拡張機能がビルドできる
• 依存関係が .external を通じて設定されている
• 設定が元の Xcode プロジェクトと一致している