ue4:buildsystem
差分
このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン前のリビジョン次のリビジョン | 前のリビジョン | ||
ue4:buildsystem [2020/06/23 20:50] – [UE4 4.25] oga | ue4:buildsystem [2022/03/17 21:58] (現在) – [Unity Build] oga | ||
---|---|---|---|
行 1: | 行 1: | ||
- | ====== UnrealBuildTool ====== | + | ====== UnrealBuildTool |
Unreal Engine 4 の BuildSystem は非常に複雑です。 | Unreal Engine 4 の BuildSystem は非常に複雑です。 | ||
その中心になるのが C# で記述された UnrealBuildTool になります。 | その中心になるのが C# で記述された UnrealBuildTool になります。 | ||
- | 各 Module の Build file (Makefile 相当) も *.Build.cs と言う名前の C# で書かれています。 | + | 各 Module のビルド定義 |
+ | |||
+ | 主に2つの機能があります。 | ||
+ | |||
+ | * IDE 向け Project File の生成 | ||
+ | * ビルドの実行 | ||
+ | |||
+ | IDE 向けに生成する Project File はデバッグが目的です。 | ||
+ | IDE Native のビルドツールは使われておらず、ビルドそのものは UnrealBuildTool が行っています。 | ||
- フォルダ Tree の検索 | - フォルダ Tree の検索 | ||
- 依存解析と cache 作成 | - 依存解析と cache 作成 | ||
- ビルドステップの実行 | - ビルドステップの実行 | ||
+ | - 依存する必要なツールのビルド (UnrealHeaderTool) | ||
- UnrealHeaderTool を使ったプリプロセス | - UnrealHeaderTool を使ったプリプロセス | ||
- Executor からコンパイラの呼び出し (もしくは分散 Build System 呼び出し) | - Executor からコンパイラの呼び出し (もしくは分散 Build System 呼び出し) | ||
- | 等 | + | |
+ | |||
+ | |||
+ | ---- | ||
+ | |||
+ | |||
+ | ===== 内部構造 ===== | ||
+ | |||
+ | ==== Executor ==== | ||
+ | |||
+ | コンパイラを呼び出すためのフロントエンドです。 | ||
+ | 分散ビルドを行う場合、それぞれ対応した Executor が選択されます。 | ||
+ | デフォルトは ParallelExecutor です。 | ||
+ | |||
+ | ^ Executor | ||
+ | | LocalExecutor | ||
+ | | ParallelExecutor | ||
+ | | XGE | 有料の分散ビルドツール IncrediBuild を install している場合に使用します。CPU/ | ||
+ | | HybridExecutor | ||
+ | | SNDBS | SONY の分散ビルドツール SN-DBS を install している場合に使用します。 | ||
+ | | Distcc | ||
+ | | FASTBuild | ||
+ | |||
+ | |||
+ | 自分で独自の分散ビルドツールを開発する場合は、専用の Executor を実装することになります。 | ||
+ | Executor の選択は System/ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ==== Build.cs の読み込み ==== | ||
+ | |||
+ | Build.cs は必要に応じて動的にコンパイルが行われ、dll として読み込まれます。[[https:// | ||
+ | |||
+ | * *.Build.cs や *.Target.cs がまとめて dll に変換される | ||
+ | * Intermediate/ | ||
+ | |||
+ | 例えば UE4 Engine の場合、Engine/ | ||
+ | dll は必要なときにしか作られないため cache としても機能します。 | ||
+ | |||
+ | |||
+ | ==== cl-filter.exe とは何か ==== | ||
+ | |||
+ | 古い UnrealBuildTool では *.cpp や *.h の依存解析を自前で行っていました。 | ||
+ | 最新版ではコンパイラの機能を利用して #include の解析を行っています。 | ||
+ | |||
+ | - 依存解析ファイルがない場合、cl.exe や clang を使って #include の抽出 | ||
+ | - 依存解析結果を元に build が必要なソースコードを絞り込む | ||
+ | - 必要なソースコードのコンパイルを実行し、同時に #include 解析結果を取得 | ||
+ | - 以降は 3のみ繰り返す | ||
+ | |||
+ | clang/gcc は -MD や -MF などのオプションで、依存解析結果のみ指定したファイルに保存することができます。 | ||
+ | コンパイラのエラーメッセージと混同してしまうことがありません。 | ||
+ | |||
+ | VisualStudio (cl.exe) には依存解析のみ別ファイルに出力する機能がありません。 | ||
+ | コンパイラのエラーメッセージと区別なく、同じ標準出力に出力します。 | ||
+ | |||
+ | UE4 では cl.exe の依存解析結果を分離するためのツールとして Engine/ | ||
+ | 標準出力から依存解析部分のみ抽出して、別のファイルに保存する機能を持っています。 | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ==== UnrealBuildTool の Makefile ==== | ||
+ | |||
+ | UnrealBuildTool 内部では、異なる意味の Makefile という用語がいくつか存在します。 | ||
+ | ひとつは Linux 向けの Projectfile である Makefile で、他に全 Platform で共通で用いられる Makefile (TargetMakefile) があります。 | ||
+ | |||
+ | TargetMakefile は *.cpp / *.h の依存解析結果を保存しておくための cache ファイルです。 | ||
+ | 保存される場所は下記の通り。 | ||
+ | |||
+ | * Intermediate/ | ||
+ | |||
+ | |||
+ | 例えば Windows 上で Game Project である MyProject の場合 | ||
+ | |||
+ | * MyProject/ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ==== Unity Build ==== | ||
+ | |||
+ | UnrealBuildTool はデフォルトで UnityBuild を行います。BuildConfiguration.xml の設定で無効化することができます。 | ||
+ | |||
+ | UnityBuild を有効にすると複数のソースコードを単一のファイルにまとめてコンパイルを行います。ビルド時間を大幅に短縮することができます。 | ||
+ | |||
+ | * ソースファイルの数が減ることによってコンパイラ起動のオーバーヘッドを減らすことが可能です。 | ||
+ | * 複数のソースコードをまとめることによって、共通で参照しているヘッダファイルの読み込みや解析が一度で済むようになります。 | ||
+ | * LTCG を off にしてもある程度複数ファイルにまたがった最適化が行われます。 | ||
+ | |||
+ | 欠点もいくつかあります。 | ||
+ | |||
+ | === コンパイル粒度が大きくなる === | ||
+ | |||
+ | 本来単一ファイルのコンパイルだけで済む小さい修正でも、周辺のファイルも含めて再コンパイルが行われることになります。 | ||
+ | なおデフォルトで AdaptiveUnityBuild が有効になっているためリビルド範囲は動的に調整が入ります。 | ||
+ | |||
+ | |||
+ | === エラーが報告されない場合がある === | ||
+ | |||
+ | #include し忘れによるシンボル参照エラーがあっても、コンパイルが通ってしまう場合があります。 | ||
+ | 他のファイルで #include されているかもしれないからです。 | ||
+ | Unity Build が行われる単位は変化するので、以前はビルドが通っていても再ビルドしたらエラーが出ていて戸惑うこともあります。 | ||
+ | |||
+ | Unity Build を無効化してビルドが通るかテストしたい場合は、ビルド時のコマンドラインオプションに -DisableUnity を指定します。 | ||
+ | (VisualStudio から呼ばれている Build.bat のコマンドラインオプションに指定できます。) | ||
+ | |||
+ | または BuildConfiguration.xml でも設定可能です。 | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | === File Scope の Local シンボルが衝突する可能性がある === | ||
+ | |||
+ | File Scope が完全な Local になりません。 | ||
+ | File Scope に記述した static 変数や無名の namespace block が他のファイルからも見えるので、衝突する場合があります。 | ||
+ | |||
+ | |||
+ | === UnityBuild の各種設定 === | ||
+ | |||
+ | UnityBuild はビルド時間を短縮しますが、ビルドするソースコードが肥大しメモリ消費が増えます。 | ||
+ | 特にマルチコア・マルチスレッド CPU で並列ビルドを行う場合はメモリがあふれる可能性があります。 | ||
+ | |||
+ | コマンドラインオプションではなく、BuildConfigration.xml で無効化したい場合は bUseUnityBuild を使います。 | ||
+ | |||
+ | また、Unity 化する場合のソースコードのサイズ制限の目安を NumIncludedBytesPerUnityCPP (byte数) で指定できます。デフォルトは 384KB (393216) です。 | ||
+ | RAM 容量が少なくメモリ不足が発生する場合はサイズを減らしてみてください。 | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version=' | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ==== ビルド速度の調整 ==== | ||
+ | |||
+ | |||
+ | === ParallelExecutor のビルドスレッド数 === | ||
+ | |||
+ | ParallelExecutor はすべてのスレッドを使用するとは限りません。 | ||
+ | 最大速度でビルドを行いたい場合は BuildConfiguration.xml への設定が必要です。 | ||
+ | |||
+ | 例えば物理コアが 6個である場合はデフォルトで 6スレッドでビルドが行われます。 | ||
+ | HyperThreading の 12スレッド分すべて使ってビルドを行いたい場合は、下記のように倍率として 2.0 を設定します。 | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version=' | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | ただし RAM 容量が少ない場合は指定した数だけビルドを走らせることができません。 | ||
+ | ParallelExecutor は RAM の空き容量によって最大スレッド数を制限しています。 | ||
+ | |||
+ | UnityBuild は非常にメモリを消費するので、RAM が少ない場合はむやみにビルドスレッド数を増やさないようにしてください。 | ||
+ | SN-DBS や FASTBuild では RAM 容量に関係なくビルドスレッド数を増やすことができますが、増やしすぎるとスラッシングが発生しビルド速度が著しく低下します。 | ||
+ | |||
+ | RAM が 32GB の場合は、最大でも 8~12 スレッド程度にとどめておくことをおすすめします。 | ||
+ | |||
+ | |||
+ | ---- | ||
+ | |||
+ | ===== UnrealHeaderTool (UHT) とは ===== | ||
+ | |||
+ | < | ||
+ | < | ||
+ | |||
+ | - UnrealHeaderTool が *.h の UCLASS(), UFUNCTION(), | ||
+ | - < | ||
+ | - 生成された < | ||
+ | |||
+ | |||
+ | 上記のように < | ||
+ | 例えば下記の UFUNCTION() はどちらも < | ||
+ | |||
+ | <code cpp> | ||
+ | /* | ||
+ | UFUNCTION( ~ ) | ||
+ | int32 GetParameterA(); | ||
+ | */ | ||
+ | |||
+ | #if 0 | ||
+ | UFUNCTION( ~ ) | ||
+ | int32 GetParameterB(); | ||
+ | #endif | ||
+ | </ | ||
+ | |||
+ | また下記のように UHT が解析する行に define したマクロを使用しても展開されません。" | ||
+ | |||
+ | <code cpp> | ||
+ | #define CATEGORY_NAME " | ||
+ | |||
+ | ~ | ||
+ | |||
+ | UFUNCTION(BlueprintCallable, | ||
+ | void SetCameraType( int32 type ); | ||
+ | |||
+ | UFUNCTION(BlueprintCallable, | ||
+ | int32 GetCameraType() const; | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | ---- | ||
+ | |||
+ | ===== UnrealAutomationTool (UAT) とは ===== | ||
+ | |||
+ | UE4 のパッケージの作成には、cpp のコンパイル以外にも必要な手順がいくつか存在します。 | ||
+ | また、それぞれ専用のツールが存在しています。 | ||
+ | |||
+ | - UnrealBuildTool, | ||
+ | - ソースコード cpp のビルド : UnrealBuildTool が行う。内部で UnrealHeaderTool のビルドや呼び出しも行う。 | ||
+ | - Contents の cook : UE4Editor 本体が行う | ||
+ | - パッケージの生成 : pak 生成に UnrealPak を使う | ||
+ | - Deploy や起動 | ||
+ | |||
+ | これらの手順をまとめて実行するためのツールが UnrealAutomationTool (UAT) です。 | ||
+ | |||
+ | 本来のビルドツールだと、ソースコードのビルドとリソースの変換やパッケージ化などの生成手段に区別がありません。 | ||
+ | たとえば make なら、Makefile 内部でソースコードのコンパイルだけでなくリソースの変換やパッケージ化など一連の処理をまとめて実行できます。 | ||
+ | |||
+ | つまり汎用的なビルドツールだと UBT と UAT 相当のツールは兼用されます。 | ||
+ | UE4 では、それぞれの手順ごとに専用のツールが用いられているので複雑です。 | ||
+ | |||
+ | ちなみに UAT 自体のビルドは Engine/ | ||
+ | |||
+ | |||
+ | |||
+ | 空の Engine/ | ||
+ | UAT が外部ツールをビルドするのを回避することができます。 | ||
+ | |||
+ | |||
+ | ---- | ||
===== UnrealBuildTool の設定 ===== | ===== UnrealBuildTool の設定 ===== | ||
- | BuildConfiguration.xml | + | ==== BuildConfiguration.xml |
- | Project / Module 単位の設定は *.Build.cs や *.Target.cs で設定することが可能です。 | + | UnrealBuildTool の共通の設定は BuildConfiguration.xml ファイルに記述しておくことができます。 |
+ | Project / Module 単位の個別の設定は *.Build.cs や *.Target.cs で設定することもできます。 | ||
- | + | BuildConfiguration.xml の置き場所は下記のとおりです。 | |
- | ===== UE4 4.25 ===== | + | - $ENGINE_DIR/ |
+ | - $USER_DIR/ | ||
+ | - $USER_DIR/ | ||
- | VisualStudio の選択。以前は | + | * USER_DIR = C:/ |
+ | |||
+ | Linux と macOS の場合は次の場所になります。 | ||
+ | |||
+ | - $ENGINE_DIR/ | ||
+ | - $HOME/ | ||
+ | - $HOME/ | ||
+ | |||
+ | **BuildConfiguration.xml に定義可能なパラメータの詳細は $ENGINE_DIR/ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ==== Compiler の指定 ==== | ||
+ | |||
+ | Windows で使用する | ||
+ | 4.25 からは BuildConfiguration.xml で設定するように変更されています。4.24 | ||
+ | |||
+ | |||
+ | Project File 生成時の VisualStudio 指定の例 | ||
<code xml> | <code xml> | ||
<?xml version=" | <?xml version=" | ||
< | < | ||
- | < | ||
- | </ | ||
- | |||
< | < | ||
< | < | ||
行 38: | 行 312: | ||
</ | </ | ||
</ | </ | ||
+ | |||
+ | 実際にコンパイルに使用する VisualStudio 選択の例 | ||
+ | |||
+ | |||
+ | <code xml> | ||
+ | <?xml version=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | Compiler の指定は通常は不要です。ProjectFileGenerator の選択だけで良く、Compiler は自動的に決まります。 | ||
+ | 唯一の例外が Windows 上で Clang を使用する場合です。 | ||
+ | Windows 上で LLVM (clang) を install している場合は、下記の設定により Compiler として clang (clang-cl) を使用することができます。 | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | もちろん対応していない Compiler を使うと Engine のビルドではエラーが出ます。 | ||
+ | 特定の Module で clang が必要になった場合に、build.cs 内部で指定するのが本来の使い方だと思われます。 | ||
+ | |||
+ | |||
+ | ==== Windows SDK の選択 ==== | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version=' | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ==== 有効な分散ビルドの指定 ==== | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version=' | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | | bAllowXGE | ||
+ | | bAllowSNDBS | ||
+ | | bAllowFASTBuild | ||
+ | |||
+ | |||
+ | |||
+ | ---- | ||
+ | |||
+ | ====== UnrealHeaderTool Build の回避方法 ====== | ||
+ | |||
+ | Source Code 版 Engine を使用していると、UnrealBuildTool は本来不要なはずの UnrealHeaderTool を何度もビルドしてしまう場合があります。 | ||
+ | |||
+ | * Makefile.bin が存在しない | ||
+ | * Makefile.bin のバージョンが古い | ||
+ | * *.uproject file の更新 | ||
+ | * BuildConfigration.xml の更新 | ||
+ | * UnrealBuldTool.exe の更新 | ||
+ | |||
+ | などの条件において、Makefile.bin だけでなく UHT 自体をビルドしようとします。 | ||
+ | UHT は < | ||
+ | |||
+ | Windows 向けにビルドを行う場合は VisualStudio が必要なのですが、他の Platform 向けに出力する場合はその限りではありません。 | ||
+ | 例えば Android の場合、Android SDK (Android NDK) 自体に toolchain 一式が含まれているので単独でビルドを行うことができます。 | ||
+ | 実際に Binary 配布版 UE4 (おそらく InstalledBuild 版も同じ) では VisualStudio がなくてもビルドすることができます。 | ||
+ | |||
+ | |||
+ | Source Code 版 UE4 でも、UBT 実行時のコマンドラインオプション -NoBuildUHT または下記の設定によって UHT のリビルドを回避することができます。 | ||
+ | |||
+ | <code cpp> | ||
+ | <?xml version=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | 例えばチームで開発作業を行っていると、プログラマのみ VisualStudio を所有しておりプランナーやグラフィックデザイナーは VisualStudio を持っていない場合があります。 | ||
+ | 生成した Windows 向けの *.exe はもちろん共有が必要ですが、上記の方法を使えば各種実機(Android, | ||
+ | |||
+ | 使用方法の例 | ||
+ | |||
+ | - Target 向けのバイナリを直接作っておきます。 | ||
+ | * UnrealBuildTool.exe | ||
+ | - ビルドします。 | ||
+ | |||
+ | * UE4Editor 上から実機で起動する場合 | ||
+ | - プレイボタンのサブメニューから、リストに並んでいる Android Device を選びます。 | ||
+ | * エラーが出る場合は次の ProjectLauncher を使う方法を試してください。 | ||
+ | |||
+ | * UE4Editor 上で ProjectLauncher を使う場合 | ||
+ | - カスタム起動プロファイルに [+] ボタンで新規追加 | ||
+ | - 「ビルド」の項目を " | ||
+ | - 「クック」を " | ||
+ | - クックしたプラットフォームを " | ||
+ | - 「パッケージ」を " | ||
+ | * パッケージ化が不要なら " | ||
+ | - 「デプロイ」を " | ||
+ | * パッケージ化ではなく起動したい場合は " | ||
+ | - 右上の矢印で戻る | ||
+ | - 今追加したカスタム起動プロファイルの右端にある起動 (" | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
ue4/buildsystem.1592913011.txt.gz · 最終更新: 2020/06/23 20:50 by oga