IWYU

Include-What-You-Use (IWYU) は、その名前が示すように、エンジンのソース コードにはコンパイルに必要な依存関係のみが含まれることを意味します。IWYU の目的は、「Engine.h」や「UnrealEd.h」のようなモノリシック ヘッダ ファイルを含まないようにすることで、不要な依存関係を削除することです。以下のリファレンス ガイドでは、IWYU との関係について説明しています。IWYU を有効にして、IWYU の規則にプロジェクトが確実に準拠するようにする方法についてのハイレベルな説明も含まれています。さらに、ゲームプロジェクトで IWYU モードを使用することを選択した場合、IWYU モードでの作業を最大限に活用するための一般的なヒントを提供します。

ゲームおよびゲーム プラグインでは、IWYU モードはデフォルトで無効になっています。ただし、エンジンおよびエンジン プラグインでは、デフォルトで IWYU モードが有効になっています。

IWYU について

Unreal Engine 4 (UE4) の以前のバージョンでは、エンジン機能の大部分は「Engine.h」や「UnrealEd.h」のような大きなモジュール中心のヘッダ ファイルを経由してインクルードされ、コンパイル時間はこれらのファイルがプリコンパイル済みヘッダ (PCH) ファイルにコンパイルされる速さによって異なります。エンジン機能が拡大するにつれて、これがボトルネックとなりました。

IWYU を使用すると、各ファイルには必要なものと使用することを選択した PCH ファイルだけがインクルードされ、基本となるソース ファイルの上位にある最適化レイヤーとして機能します。ソース ファイル自体を変更することなく、コードのコンパイルが成功するかどうかに影響を与えることなく、そしてビルド時間を最小限に抑えるように変更できます。

IWYU コードの書き出しには、以下の 4 つの規則を適用しています。

1. すべてのヘッダ ファイルには、必要な依存関係が含まれます。

2. .cpp ファイルには、対応する .h ファイルが最初にインクルードされます。

3. PCH ファイルは、明示的にインクルードされません。

4. モノリシック ヘッダ ファイルは明示的にインクルードされません。

IWYU 規則

IWYU の意味については、以下の IWYU 規則に説明があります。

1. すべてのヘッダ ファイルには、必要な依存関係が含まれます。

   • CoreMinimal ヘッダ ファイルには、UE4 のコア プログラミング環境でよく使われている型 (FString、FName、TArray など) が含まれます。

   • (「CoreMinimal」の UE4 ルート ディレクトリに格納されている) \Engine\Source\Runtime\Core\Public\CoreMinimal.h ヘッダ ファイルは、ほとんどのエンジンのヘッダ ファイルの中で最初にインクルードされます。

     

   • Core モジュールでは、ほとんどのヘッダ ファイルは最初に CoreTypes.h ヘッダ ファイルをインクルードします。これにはプリミティブ C++ 型の typedefs、UE4 ビルド マクロ、コンパイル環境を設定するディレクティブのみをインクルードします。

   ここで重要なことは、すべてのヘッダ ファイルにコンパイルに必要なものがすべて含まれているということです。

2. .cpp ファイルには、対応する .h ファイルが最初にインクルードされます。

   
   • すべてのソース ファイルが、要求されるすべての依存関係をインクルードしているか検証するためには、PCH ファイルを無効にして non-unity モードでゲーム プロジェクトをコンパイルします。

3. PCH ファイルは、明示的にインクルードされません。

   • PCH ファイルは引き続き使用され、UnrealBuildTool (UBT) によりコンパイラ コマンドライン上で強制的にインクルードされます。

4. モノリシック ヘッダ ファイルは明示的にインクルードされません。

   • エンジン コードがモノリシック ヘッダ ファイル (「Engine.h」または「UnrealEd.h」) をインクルードすると、コンパイラから警告が出ます。

   モノリシック ヘッダ ファイルはゲーム プロジェクトとの互換性のために UE4 に存在しており、ゲーム プロジェクトがそれらをインクルードしても (デフォルトで) 警告は出ません。

IWYU が有効であることを確認する

バージョン 4.15 のリリース時で IWYU 規則が制定される以前は、UE4 コードは IWYU 準拠コードにインクルードしたいデベロッパー達に反して、各 CPP ファイルのトップに PCH ファイルをインクルードするのが常でした。IWYU 規則では、PCH ファイルは、コードが最初にオーサリングされた方法とは別に適用されるコンパイル時間の最適化のレイヤーと考えることができます。したがって、PCH ファイルを作成してインクルードするのではなく、PCH を UBT に任せて、使用する PCH ファイル (ある場合) を決定します。

IWYU が有効であることを確認するには、モジュールを IWYU 規則でコンパイルし、モジュールの *.build.cs ファイルを開いて、PCHUsageMode.UseExplicitOrSharedPCHs が PCHUsage に設定されていることを確認します。

PCHUsage を PCHUsageMode.UseExplicitOrSharedPCHs 設定すると、モジュールの build.cs ファイルに PrivatePCHHeaderFile 設定がある場合にのみ、明示的な PCH ファイルがモジュールに対して作成されます。設定されていない場合は、モジュールは PCH を別のモジュールと共有し、ツールが必要以上の PCH ファイルを生成しないようにします。また、UseExplicitOrSharedPCHs モードを有効にする場合、ソース ファイルに対応するヘッダ ファイルがインクルードされている必要があります。別の選択肢として、モジュールが IWYU 規則に準拠することを拒否する場合は、PCHUsage を PCHUsageMode.UseSharedPCHs に設定します。

このエンジンのコード ベースを IWYU モデルに変換すると、UE4 のコンパイル時間が大幅に改善されることがわかりました。

IWYU モードで実行する

ゲームを IWYU モードで実行している場合は、.cpp ファイルに対応する .h ファイルを最初にインクルードしなければなりません。これは、コンパイラが *.hファイルに必要な依存関係をすべて確実にインクルードするようにするには便利な方法です (PCH ファイルとユニティ ビルドが無効な場合)。Unreal Build Tool (UBT) では、一致するヘッダ ファイルを最初にインクルードしないと警告が表示されます (対応する CPP ファイル)。

コンパイラによる警告を無効にするには、モジュールの bEnforceIWYU.build.cs ファイルの false を * に設定します。

ターゲット全体に対して警告がでないようにするには、*.target.cs ファイルの bEnforceIWYU を false に設定します。

一般的なヒント

ゲームで IWYU を許容するする場合は、以下の点に留意してください。

1. 各ヘッダ ファイルの最初に「CoreMinimal.h」をインクルードします。

2. すべてのソース ファイルに必要な依存関係がすべてインクルードされていることを検証するには、PCH ファイルを無効にして、ゲーム プロジェクトを non-unity モードでコンパイルします。

3. 「Runtime\Engine\Classes\Engine\Engine.h」で定義される UEngine または GEngine にアクセスする必要がある場合は、「#include Engine/Engine.h」を使います (「Runtime\Engine\Public\Engine.h」にあるモノリシック ヘッダ ファイルとは異なります)。

4. コンパイラが認識しないクラスを使用していて、必要なものがわからない場合は、ヘッダ ファイルが存在しない可能性があります。これは、正しくコンパイルされた IWYU 以外のコードから変換する場合に特に当てはまります。API ドキュメントでクラスを参照すると、ページの下部に必要なモジュールとヘッダ ファイルを見つけることができます。

追加リソース

ユーザーが既存の C++ プロジェクトを IWYU 形式に変換するのを支援するために IncludeTool をリリースしました (「[UE4Root]\Engine\Source\Programs\IncludeTool」で確認できます)。