IWYU リファレンス ガイド

UE4 向けに更新された Include-What-You-Use (IWYU) 依存モデルを使用するコードベースの概要です。

Windows
MacOS
Linux
前提トピック

このページは以下のトピックへの知識があることを前提にしています。まず以下のトピックの内容についてご確認をお願いします。

IWYU.png

Include-What-You-Use (IWYU) は名前が意味する通り、エンジンのソースコードにはコンパイルする必要がある依存のみ含まれます。IWYU の目的は、 Engine.h や UnrealEd.h などのモノリシック ヘッダ ファイルを含まないようにして、 余分な依存を削減することです。以下のリファレンス ガイドでは、プロジェクトが IWYU の規則を絶対に固守するように、 IWYU を有効にする方法の概要説明を交えて、IWYU とはどういうものかを説明します。さらに、ゲーム プロジェクトに IWYU モードを使用することに決めた場合、 IWYU モードでの作業を最大限に活用できるようにする一般的なヒントも提供します。

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

IWYU について

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

IWYU を使うと、各ファイルは必要なものと使用することにした PCH ファイルのみをインクルードし、純粋に基本となるソース ファイルに加えて最適化のレイヤーとなります。ソール ファイルそのものの変更をせず、また、コードのコンパイル化に影響も与えずに、 ビルド時間を最小に変更することができます。

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

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

  2. *.cpp files include their matching *.h ファイルが最初にきます。

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

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

IWYU 規則

以下の IWYU の概要を読むと、IWYU とは何か分かりやすくなります。

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

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

    *(UE4 root directory at \Engine\Source\Runtime\Core\Public\CoreMinimal.h の UE4 ルート ディレクトリに格納されている) CoreMinimal ヘッダ ファイルは、だいたいのエンジンのヘッダ ファイルの中で最初にインクルードされます。

    CoreMinimalHeader.png

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

    各ヘッダ ファイルはコンパイルが必要なものをすべてインクルードしていることをまず覚えておいてください。

  2. *.cpp files include their matching *.h ファイルが最初にきます。

    CPPFileIncludingHeader.png

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

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

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

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

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

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

IWYU を有効にする

バージョン 4.15 のリリース時に IWYU が制定されるまで UE4 コードは、IWYU 準拠コードをインクルードしたかったエンジン デベロッパー達に反して、 各 CPP ファイルのトップに PCH ファイルをインクルードするのが常でした。IWYU 規則を新しく制定してからは、PCH ファイルはコードをもともとオーサリングした方法とは別に適用される コンパイル時間の最適化の積み重ねと考えています。従って、PCH ファイルを合成しインクルードするよりも、むしろ UBT のままにして使用する PCH ファイル (もしあれば) を決定しています。

IWYU モードを有効にするには、モジュールを必ず IWYU 規則でコンパイルし、モジュールの *.build.cs ファイルで開き、PCHUsagePCHUsageMode.UseExplicitOrSharedPCHs に設定します。

ExamplePlugin_PCHUsage.png

PCHUsagePCHUsageMode.UseExplicitOrSharedPCHs に設定すると、モジュールの *.build.cs ファイルが PrivatePCHHeaderFile 設定にされている場合のみ、明示的な PCH ファイルがモジュールに対して作成されます。 設定されていない場合は、モジュールは必要以上の PCH ファイルをツールが生成しなくて済むように PCH を他のモジュールと共有します。また、UseExplicitOrSharedPCHs モードが有効になっていると、 ソース ファイルは一致するヘッダ ファイルをインクルードしなければならないことも覚えておいてください。別の選択肢として、IWYU 規則に遵守するオプトアウトをモジュールに適用したい場合は、PCHUsagePCHUsageMode.UseSharedPCHs に設定することもできます。

ExamplePlugin_UseSharedPCHs.png

エンジンのコードベースを IWYU モデルに変換した後、UE4 のコンパイル時間に劇的な改善が見られました。

IWYU モードで実行する

ゲームを IWYU モードで実行する場合、 *.cpp ファイルが対応する *.h ファイルを先頭にインクルードしなければなりません。*.h ファイルが必要な依存のすべてがインクルードされているかどうかを コンパイラが確認してくれるという点で便利な方法です (PDC ファイルとユニティ ビルドが無効の時)。一致するヘッダ ファイル (対応する CPP ファイル) が先頭にインクルードされていないと、 コンパイラから警告が出されます。

コンパイラから警告が出ないようにするには、モジュールの *.build.cs ファイルの bEnforceIWYUfalse に設定します。

ModuleBuildCS_bEnforceIWYUfalse.png

ターゲット全体に対して警告が出ないようにするには、モジュールの *.build.cs ファイルの bEnforceIWYUfalse に設定します。

一般的なヒント

ゲームに 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 でクラスを参照すると、ページの下に必要なモジュールとヘッダ ファイルがあります。

Select Skin
Light
Dark

新しい Unreal Engine 4 ドキュメントサイトへようこそ!

あなたの声を私たちに伝えるフィードバックシステムを含め、様々な新機能について開発をおこなっています。まだ広く使える状態にはなっていないので、準備ができるまでは、ドキュメントフィードバックフォーラムで、このページについて、もしくは遭遇した問題について教えていただけると助かります。

新しいシステムが稼働した際にお知らせします。

フィードバックを送信