Unreal Header Tool

UnrealHeaderTool (UHT) は、UObject システムをサポートするカスタムのパースおよびコード生成のツールです。

Unreal Header Tool の概要

Unreal Header Tool (UHT) は、Unreal Engine のカスタムのパースおよびコード生成のツールです。UHT では、Unreal Engine (UE) の UObject システム用にコードをパースおよび生成します。Unreal Engine のコードのコンパイルは以下の 2 つのフェーズで行われます。

  1. Unreal Build Tool (UBT) で UHT が呼び出されると、Unreal 関連のクラスのメタデータの C++ ヘッダをパースし、さまざまな UObject 関連の機能を実装するためのカスタム コードを生成します。

  2. UBT では、結果をコンパイルするために設定された C++ コンパイラが呼び出されます。

このページでは、次の情報を記載しています。

Unreal Header Tool を実行する

UBT で内部的に対応されているため、通常の開発ワークフローでは Unreal Header Tool (UHT) を実行する必要はありません。ただし、UHT プラグインを作成するか、UHT に変更を加える場合、UHT を個別に実行することが必要になる場合があります。

このセクションでは、UHT を手動で実行する方法について説明します。

UHT コマンドライン

UHT を実行するには、次の 2 種類の方法があります。

内部 UBT コマンド

UBT では、内部的に次のコマンドラインを使用します。UBT はすべてのヘッダ ファイルをスキャンして、UHT キーワードを検索してから、UHT がパースする必要のあるすべてのモジュールとソース ファイルを含むマニフェスト ファイルを生成します。

RunUBT -Mode=UnrealHeaderTool "<PROJECT_FILE>" "<MANIFEST_FILE>" …

UHT 開発コマンド

UHT 開発時または他のエクスポートの実行時に、次のコマンドラインを使用できます。既存のマニフェスト ファイルに依存する代わりに、UHT では UBT が通常実行するスキャンと同じスキャンを実行し、その後、マニフェストを自動的に生成します。UHT では、このモードでの実行時に UBT と同じターゲット指定を使用します。

RunUBT -Mode=UnrealHeaderTool "-Target=<TARGET> <PLATFORM> <CONFIGURATION>" …
RunUBT -Mode=UnrealHeaderTool "-Target=<TARGET> <PLATFORM> <CONFIGURATION> -Project=\"<PROJECT_FILE>\"" …

ログ オプション

UHT では、UBT がサポートしているものと同じログ オプションをサポートしています。

エラー ハンドリング

UHT には、エラー ハンドリングに影響する 2 つのオプションがあります。

  • エラーとして警告

  • 生成したコードが変更された場合に失敗

UHT は、通常、-WarningsAsError で実行されます。名前が示すように、UHT では警告が検出されると、エラー コードを返します。ホット リロード システムでは -FailIfGeneratedCodeChanges を使用して、生成されたコードへの変更を検出し、あればエラーを返します。

デバッグ

デバッグ時に、UHT で C# タスクを多用すると、デバッグが困難になる場合があります。-NoGoWide オプションを使用すると、C# タスクの使用を無効にし、単一スレッドの実行で UHT を実行します。

エクスポータ

エクスポータは、UHT がコードおよびレポートの生成に使用するメカニズムです。デフォルトでは、UHT は標準 Codegen エクスポータおよび有効なスクリプト ジェネレータのエクスポータを実行します。UHT には、デフォルトで有効になっていないサンプル エクスポータが 2 つ含まれています。

  • Json

  • 統計

エクスポータを有効にする

エクスポータを有効にするには、-<EXPORTER_NAME> コマンドライン引数を使用します。通常有効になっているエクスポータを無効にするには、-No<EXPORTER_NAME> コマンドライン引数を使用します。-NoDefaultExporters オプションは、デフォルトで有効になっているすべてのエクスポータを無効にします。このオプションは、デフォルトのエクスポータとは関係なく、統計などのエクスポータを実行する場合に便利です。

エクスポータの出力

UHT では、UHT 開発に便利なエクスポータ出力のディレクトリを 1 つ作成します。これらのオプションの出力は、「Engine/Programs/UnrealHeaderTool/Saves」ディレクトリにあります。UHT 開発を実行する前に、-WriteRef オプションを使用して、生成されたすべての出力のコピーを作成します。変更を繰り返す場合、-VerifyRef オプションを使用して、新しく作成した出力を -WriteRef で生成された出力と比較します。これによって、出力に対する予期しない変更がないことが確認されます。

-NoOutput オプションを使用して、UHT で出力を通常書き込む場所に書き込まないようにします。

UHT 実行の一般的な問題

パースされないデリゲートのみを含むソース ファイル

他の文とは異なり、UHT では自動的に任意の DECLARE_DYNAMIC_ デリゲートをパースします。ただし、ヘッダ ファイルにこれらのデリゲートが含まれていて、他の UHT キーワードが含まれていない場合、UBT では、パースする必要があるものとしてヘッダを見なしません。

この問題を回避するには、前述の UDELEGATE キーワードを少なくとも 1 つのデリゲートで使用します。

スクリプト ジェネレータで UHT を拡張する

C# UHT では、プラグインでスクリプト ジェネレータを定義する機能をサポートしています。この例は、「Engine\Plugins\ScriptPlugin\Source\ScriptGeneratorUbtPlugin」にあります。

UBT は、<PLUGIN_NAME>.ubtplugin.csproj C# プロジェクト ファイル名が存在することで、プラグインを認識します。ここで、<PLUGIN_NAME> はプラグインの名前です。C# プロジェクトを設定する場合、プロジェクト参照を使用する代わりに「Engine\Binaries\DotNET\UnrealBuildTool」ディレクトリにある UBT と UHT のアセンブリ参照を使用します。これは、UBT でプラグインを作成する場合、ロックされたファイルの問題を回避します。

指定子、キーワード、プロパティなどを定義するために UHT で同じメカニズムを使用できる場合、エクスポータのみがサポートされます。さらに、エクスポータはプラグインの「Intermediate」ディレクトリへのファイル出力に制限されます。UBT では、標準 Codegen エクスポータ以外で生成されたファイルはコンパイルされません。スクリプト ジェネレータ プラグインの場合、コンパイルは、通常、プラグイン内の他の C++ コードに含まれる単一の生成済み .inl ファイルによって行われます。

IUhtExportFactory インターフェースは、UHT にアクセスを提供しています。

メソッド

説明

IUhtExportFactory.Session

パッケージのコレクションおよびその定義済みのタイプへのアクセスを提供します。C++ UHT とは異なり、3 つのタイプには、UHT によってパースされた各タイプに関するすべての情報が含まれています。

IUhtExportFactory.CreateTask

コンテンツをエクスポートするタスクまたは -NoGoWide が指定された場合に直接実行するタスクを作成します。

IUhtExportFactory.MakePath

CommitOutput に渡すファイル名を生成します。

IUhtExportFactory.CommitOutput

変更された場合にのみ、出力をディスクに書き込みます。-WriteRef または -VerifyRef オプションを使用する場合、ファイルはエクスポータの名前に基づいたサブディレクトリにも書き込まれます。

IUhtExportFactory.AddExternalDependency

UBT で UHT の再実行が必要かどうかを確認するためにチェックするファイルを追加します。たとえば、出力を変更するコンフィギュレーション ファイルを外部依存関係として追加できます。

UHT エクスポータの拡張を有効にする

UHT が拡張を認識するために、次の 2 点が必要です。

  • クラスには、UnrealHeaderTool クラス属性が含まれている必要があります。

  • 関数には、UhtExporter メソッド属性が含まれている必要があります。

エクスポータを追加する場合、属性に次の設定が含まれている必要があります。

  • Name:エクスポータの名前。この名前はある程度固有である必要があります。

  • Options:プラグインが有効になっている場合は常に実行されるように、デフォルトに設定します。

  • ModuleName:エクスポータを含むプラグイン モジュールの名前。

たとえば、「Engine\Plugins\ScriptPlugin\Source\ScriptGeneratorUbtPlugin」にある ScriptGenerator.cs の例を参照してください。

[UhtExporter(Name="ScriptPlugin", Description="Generic Script Plugin Generator", Options=UhtExporterOptions.Default, ModuleName="ScriptPlugin")]

その他のオプションは、Epic エクスポータに不要か予約済みのいずれかです。たとえば、前述の例の Description は必須オプションではありません。

その他の UHT 拡張

UnrealHeaderTool クラス属性は、エクスポータ以外の多数のものに使用されます。現在、スクリプト ジェネレータのエクスポータは、サポートされている拡張タイプのみです。

次の属性は、UHT 内の重要な要素を定義します。

属性

説明

UhtKeword

UCLASS などのトークン。

UhtSpecifier

指定子。

UhtSpecifierValidator

メタデータのバリデータ。

UhtPropertyType

新しいプロパティ タイプ。

UhtStructDefaultValue

USTRUCT のデフォルト値。

UhtLocTextDefaultValue

LOCTEXT マクロのデフォルト値。

UhtEngineClass

C# クラスを別のエンジン タイプに関連付けます。

コード生成の変更が不要であるため、新しい指定子、バリデータ、およびデフォルト値を追加できます。新しいエンジン タイプ、プロパティ タイプ、またはキーワードを追加すると、正しく実装するためにエンジンに多数の変更が必要になるので、これらの追加は慎重に行う必要があります。

UHT コマンドライン リファレンス

オプション

コマンドライン引数

説明

-Verbose

ログ出力の詳細を増やします。

-VeryVerbose

ログ出力の詳細を最大化します。

-Log

ログ ファイルの場所を指定します。この引数を指定しない場合、使用されるデフォルトの場所は「Engine/Programs/UnrealHeaderTool/Saved/Logs/UnrealHeaderTool.log」です。

-Timestamps

ログにタイムスタンプを含めます。

-FromMsBuild

Microsoft Build Engine (MSBuild) 用にメッセージをフォーマットします。

-NoLog

デフォルトのログ ファイルなど、ログ ファイルの作成を無効にします。

-Test

テスト スクリプトを実行します。

-WarningsAsErrors

警告をエラーとして扱います。

-NoGoWide

同時のパースとコード生成を無効にします。

-WriteRef

出力をすべて参照ディレクトリに書き込みます。

-VerifyRef

出力をすべて検証ディレクトリに書き込み、参照出力と比較します。

-FailIfGeneratedCodeChanges

出力ファイルへの任意の変更をエラーとして見なします。

-NoOutput

参照出力以外の出力ファイルを保存しません。

-IncludeDebugOutput

デバッグに役立てるために生成済みの出力に追加のコンテンツを含めます。

-NoDefaultExporters

すべてのデフォルトのエクスポータを無効にします。特定のエクスポータを実行する必要がある場合に便利です。

ジェネレータ

コマンドライン引数

説明

-Stats

タイプの統計。

-NoStats

タイプの統計を無効にします。

-Json

パッケージの Json の説明。

-NoJson

パッケージの Json の説明を無効にします。

-CodeGen

標準 Unreal Engine コード ジェネレータ。これはデフォルトのジェネレータです。

-NoCodeGen

デフォルトの Unreal Engine コード ジェネレータを無効にします。

詳細情報

Unreal Engine リフレクション システム

UObjects とその関連メタデータ指定子などの Unreal Engine リフレクション システムの詳細については、「Unreal Engine リフレクション システム」のドキュメントを参照してください。

Unreal Build Tool

Unreal Engine ビルド プロセスおよびビルドのカスタマイズの詳細については、「Unreal Build Tool」のドキュメントを参照してください。

タグ
Unreal Engine のドキュメントを改善するために協力をお願いします!どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
キャンセル