Include What You Use

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

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

IWYU についての説明

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

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

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

1. すべてのヘッダ ファイルには、必要な依存関係が含まれます。
2. *.cpp ファイルには、対応する *.h ファイルが最初にインクルードされます。
3. Precompiled Header (PCH) ファイルは、明示的にインクルードされません。
4. モノリシック ヘッダ ファイルは明示的にインクルードされません。

IWYU 規則

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

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

   • CoreMinimal ヘッダ ファイル (CoreMinimal.h) には、UE のコア プログラミング環境でよく使われている型 (FString、FName、TArray など) が含まれます。
   • (UE4 root directory at \Engine\Source\Runtime\Core\Public\CoreMinimal.h の UE ルート ディレクトリに格納されている) CoreMinimal.h ヘッダ ファイルは、だいたいのエンジンのヘッダ ファイルの中で最初にインクルードされます。
   • Core モジュールでは、ほとんどのヘッダ ファイルは先頭で CoreTypes.h ヘッダ ファイルをインクルードします。これにはプリミティブ C++ 型の typedefs、UE ビルド マクロ、コンパイル環境を設定するディレクティブのみをインクルードします。

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

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

   • すべてのソース ファイルに必要な依存がすべてインクルードされているかを検証するには、PCH ファイルを無効にして通常モードでゲーム プロジェクトをコンパイルします。

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

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

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

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

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

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

IWYU 規則が制定される以前は、UE コードは IWYU 準拠コードにインクルードしたいデベロッパー達に反して、各 C++ ファイルのトップに 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 モードで実行する

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

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

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

一般的なヒント

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

1. 各ヘッダ ファイルの最初に CoreMinimal.h をインクルードします。
2. すべてのソース ファイルに必要な依存がすべてインクルードされているかを検証するには、PCH ファイルを無効にして通常モードでゲーム プロジェクトをコンパイルします。
3. Runtime\Engine\Classes\Engine\Engine.h で定義される UEngine または GEngine にアクセスする必要がある場合は、#include Engine/Engine.h を使います (Runtime\Engine\Public\Engine.h にあるモノリシック ヘッダ ファイルとは異なります)。
4. コンパイラが認識しないクラスを使用し、何を含める必要があるのかわからない場合、ヘッダ ファイルが不足している可能性があります。特に、正しくコンパイルされた IWYU 以外のコードから変換している場合はそうなります。API Documentation でそのクラスを調べ、必要なモジュールとヘッダ ファイルはページの下の方にあります。