差分

このページの2つのバージョン間の差分を表示します。

--- ue4:buildsystem [2020/08/22 12:00] – oga
+++ ue4:buildsystem [2022/03/17 21:58] (現在) – [Unity Build] oga
@@ 行 1: / 行 1: @@
-====== UnrealBuildTool ======
+====== UnrealBuildTool (UBT) ======
 Unreal Engine 4 の BuildSystem は非常に複雑です。
 その中心になるのが C# で記述された UnrealBuildTool になります。
-各 Module の Build file (Makefile 相当) も *.Build.cs と言う名前の C# で書かれています。
+各 Module のビルド定義 (Makefile 相当) も *.Build.cs と言う名前のファイルで C# 言語で書かれています。
+主に２つの機能があります。
+  * IDE 向け Project File の生成
+  * ビルドの実行
+IDE 向けに生成する Project File はデバッグが目的です。
+IDE Native のビルドツールは使われておらず、ビルドそのものは UnrealBuildTool が行っています。
   - フォルダ Tree の検索
   - 依存解析と cache 作成
   - ビルドステップの実行
+    - 依存する必要なツールのビルド (UnrealHeaderTool)
     - UnrealHeaderTool を使ったプリプロセス
     - Executor からコンパイラの呼び出し (もしくは分散 Build System 呼び出し)
-等
+----
@@ 行 23: / 行 36: @@
 デフォルトは ParallelExecutor です。
+^ Executor           ^ 説明    ^
 | LocalExecutor      | Network を使わずに PC の Local CPU だけでビルドします。並列ビルドしますが、HT が有効な場合すべての Thread が使われないという問題があります。設定で変更可能ですが、デフォルトだと本来の速度よりもビルド速度が落ちているので注意。今はほとんど使われていません。  |
-| ParallelExecutor   | Local CPU 用の新しい Executor で、LocalExecutor よりも高速です。設定不要ですべての CPU core とすべての Thread を使います。  |
+| ParallelExecutor   | Local CPU 用の新しい Executor で、LocalExecutor よりも高速です。HyperThreading 対応 CPU の場合、すべてのスレッドを使用するには BuildConfiguration.xml への設定が必要です。  |
 | XGE                | 有料の分散ビルドツール IncrediBuild を install している場合に使用します。CPU/Thread 数に応じたライセンスが必要です。    |
 | HybridExecutor     | XGE と同じですが、分散ビルドと同時に Local の CPU も最大限活用します。IncrediBuild のライセンスよりも CPU core 数が多い場合に有効かもしれません。未確認   |
 | SNDBS              | SONY の分散ビルドツール SN-DBS を install している場合に使用します。     |
 | Distcc             | macOS 上で分散ビルドツールの Distcc を用いる場合にこの Executor を使います。   |
+| FASTBuild          | オープンソースの分散ビルドツール FASTbuild を使用する場合に用いられます。   |
+自分で独自の分散ビルドツールを開発する場合は、専用の Executor を実装することになります。
+Executor の選択は System/ActionGraph.cs の内部にあります。
+==== Build.cs の読み込み ====
+Build.cs は必要に応じて動的にコンパイルが行われ、dll として読み込まれます。[[https://wlog.flatlib.jp/archive/1/2019-3-24|(参照)]]
+  * *.Build.cs や *.Target.cs がまとめて dll に変換される
+  * Intermediate/Build/BuildRules/*.dll に保存
+例えば UE4 Engine の場合、Engine/Intermediate/Buld/BuildRules/UE4Rules.dll になります。
+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/Build/Windows/cl-filter/cl-filter.exe を使用しています。
+標準出力から依存解析部分のみ抽出して、別のファイルに保存する機能を持っています。
+==== UnrealBuildTool の Makefile ====
+UnrealBuildTool 内部では、異なる意味の Makefile という用語がいくつか存在します。
+ひとつは Linux 向けの Projectfile である Makefile で、他に全 Platform で共通で用いられる Makefile (TargetMakefile) があります。
+TargetMakefile は *.cpp / *.h の依存解析結果を保存しておくための cache ファイルです。
+保存される場所は下記の通り。
+  * Intermediate/Build/＜Platform＞/＜Target＞/＜Configuration＞/Makefile.bin
+例えば Windows 上で Game Project である MyProject の場合
+  * MyProject/Intermediate/Build/Win64/MyProjectEditor/Development/Makefile.bin
+==== 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='1.0' encoding='utf-8'?>
+<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
+    <BuildConfiguration>
+        <bUseUnityBuild>true</bUseUnityBuild>
+        <NumIncludedBytesPerUnityCPP>393216</NumIncludedBytesPerUnityCPP>
+    </BuildConfiguration>
+</Configuration>
+</code>
+==== ビルド速度の調整 ====
+=== ParallelExecutor のビルドスレッド数 ===
+ParallelExecutor はすべてのスレッドを使用するとは限りません。
+最大速度でビルドを行いたい場合は BuildConfiguration.xml への設定が必要です。
+例えば物理コアが 6個である場合はデフォルトで 6スレッドでビルドが行われます。
+HyperThreading の 12スレッド分すべて使ってビルドを行いたい場合は、下記のように倍率として 2.0 を設定します。
+<code xml>
+<?xml version='1.0' encoding='utf-8'?>
+<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
+	<ParallelExecutor>
+		<ProcessorCountMultiplier>2.0</ProcessorCountMultiplier>
+	</ParallelExecutor>
+</Configuration>
+</code>
+ただし RAM 容量が少ない場合は指定した数だけビルドを走らせることができません。
+ParallelExecutor は RAM の空き容量によって最大スレッド数を制限しています。
+UnityBuild は非常にメモリを消費するので、RAM が少ない場合はむやみにビルドスレッド数を増やさないようにしてください。
+SN-DBS や FASTBuild では RAM 容量に関係なくビルドスレッド数を増やすことができますが、増やしすぎるとスラッシングが発生しビルド速度が著しく低下します。
+RAM が 32GB の場合は、最大でも 8～12 スレッド程度にとどめておくことをおすすめします。
+----
+===== UnrealHeaderTool (UHT) とは =====
+<nowiki>C++</nowiki> で UE4 の開発を行っている方には説明するまでもないですが *.generated.h を生成するためのプリプロセッサです。
+<nowiki>C/C++</nowiki> 言語のプリプロセッサの前に走ります。
+  - UnrealHeaderTool が *.h の UCLASS(), UFUNCTION(), UPROPERTY() などを解析。*.generated.h を生成する。
+  - <nowiki>C++</nowiki> 言語のプリプロセッサが # で始まる行(#define, #include など)やコメント行の処理、マクロ展開を行う。ソースコードを生成する。
+  - 生成された <nowiki>C++</nowiki> ソースコードのコンパイル
+上記のように <nowiki>C++</nowiki> のプリプロセッサの前に走るので、UHT が解析するコマンドにはブロックコメントや #if ～、define マクロが意味を持ちません。
+例えば下記の UFUNCTION() はどちらも <nowiki>C/C++</nowiki> 言語的にはコメントアウトされていますが UHT では有効になります。#if ～ #endif block でも同じです。
+<code cpp>
+/*
+UFUNCTION( ～ )
+int32  GetParameterA();
+*/
+#if 0
+UFUNCTION( ～ )
+int32  GetParameterB();
+#endif
+</code>
+また下記のように UHT が解析する行に define したマクロを使用しても展開されません。"CATEGORY_NAME" という Category になってしまいます。
+<code cpp>
+#define CATEGORY_NAME "Camera"
+～
+UFUNCTION(BlueprintCallable, Category=CATEOGRY_NAME)
+void  SetCameraType( int32 type );
+UFUNCTION(BlueprintCallable, Category=CATEOGRY_NAME)
+int32  GetCameraType() const;
+</code>
+----
+===== UnrealAutomationTool (UAT) とは =====
+UE4 のパッケージの作成には、cpp のコンパイル以外にも必要な手順がいくつか存在します。
+また、それぞれ専用のツールが存在しています。
+  - UnrealBuildTool, ShaderCompileWorker, UnrealPak, Lightmass などツールのビルド : UnrealAutomationTool が行う。
+  - ソースコード cpp のビルド : UnrealBuildTool が行う。内部で UnrealHeaderTool のビルドや呼び出しも行う。
+  - Contents の cook : UE4Editor 本体が行う
+  - パッケージの生成 : pak 生成に UnrealPak を使う
+  - Deploy や起動
+これらの手順をまとめて実行するためのツールが UnrealAutomationTool (UAT) です。
+本来のビルドツールだと、ソースコードのビルドとリソースの変換やパッケージ化などの生成手段に区別がありません。
+たとえば make なら、Makefile 内部でソースコードのコンパイルだけでなくリソースの変換やパッケージ化など一連の処理をまとめて実行できます。
+つまり汎用的なビルドツールだと UBT と UAT 相当のツールは兼用されます。
+UE4 では、それぞれの手順ごとに専用のツールが用いられているので複雑です。
+ちなみに UAT 自体のビルドは Engine/Build/BatchFiles/RunUAT.bat 内部で行われています。
+空の Engine/Build/InstalledBuild.txt ファイルを作っておくと InstalledBuild mode になります。
+UAT が外部ツールをビルドするのを回避することができます。
+----
 ===== 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/Engine/Saved/UnrealBuildTool/BuildConfiguration.xml
+  - $USER_DIR/AppData/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml
+  - $USER_DIR/Documents/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml
-VisualStudio の選択。以前は UBT のコマンドオプションで -2017 のように指定していた。[[https://wlog.flatlib.jp/archive/1/2019-4-9|詳細]]
+  * USER_DIR = C:/Users/＜USER＞/
+Linux と macOS の場合は次の場所になります。
+  - $ENGINE_DIR/Engine/Saved/UnrealBuildTool/BuildConfiguration.xml
+  - $HOME/.config/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml
+  - $HOME/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml
+**BuildConfiguration.xml に定義可能なパラメータの詳細は $ENGINE_DIR/Engine/Saved/UnrealBuildTool/BuildConfiguration.Schema.xsd ファイルを見るとわかります。**
+==== Compiler の指定 ====
+Windows で使用する VisualStudio の Version を選択できます。
+.25 からは BuildConfiguration.xml で設定するように変更されています。4.24 以前はコマンドラインオプション -2017, -2019 が有効でした。[[https://wlog.flatlib.jp/archive/1/2019-4-9|(参照)]]
+Project File 生成時の VisualStudio 指定の例
 <code xml>
 <?xml version="1.0" encoding="utf-8"?>
 <Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
-	<BuildConfiguration>
-	</BuildConfiguration>
    <ProjectFileGenerator>
      <Format>VisualStudio2017</Format>
@@ 行 59: / 行 312: @@
 </Configuration>
 </code>
+実際にコンパイルに使用する VisualStudio 選択の例
+<code xml>
+<?xml version="1.0" encoding="utf-8"?>
+<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
+   <WindowsPlatform>
+     <Compiler>VisualStudio2017</Compiler>
+   </WindowsPlatform>
+</Configuration>
+</code>
+Compiler の指定は通常は不要です。ProjectFileGenerator の選択だけで良く、Compiler は自動的に決まります。
+唯一の例外が Windows 上で Clang を使用する場合です。
+Windows 上で LLVM (clang) を install している場合は、下記の設定により Compiler として clang (clang-cl) を使用することができます。
+<code xml>
+<?xml version="1.0" encoding="utf-8"?>
+<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
+   <WindowsPlatform>
+     <Compiler>Clang</Compiler>
+   </WindowsPlatform>
+</Configuration>
+</code>
+もちろん対応していない Compiler を使うと Engine のビルドではエラーが出ます。
+特定の Module で clang が必要になった場合に、build.cs 内部で指定するのが本来の使い方だと思われます。
+==== Windows SDK の選択 ====
+<code xml>
+<?xml version='1.0' encoding='utf-8'?>
+<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
+	<WindowsPlatform>
+		<WindowsSdkVersion>10.0.18362.0</WindowsSdkVersion>
+	</WindowsPlatform>
+</Configuration>
+</code>
+==== 有効な分散ビルドの指定 ====
+<code xml>
+<?xml version='1.0' encoding='utf-8'?>
+<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
+	<BuildConfiguration>
+		<bAllowXGE>false</bAllowXGE>
+		<bAllowSNDBS>false</bAllowSNDBS>
+		<bAllowFASTBuild>true</bAllowFASTBuild>
+	</BuildConfiguration>
+</Configuration>
+</code>
+| bAllowXGE     | IncrediBuild   |
+| bAllowSNDBS   | SN-DBS         |
+| bAllowFASTBuild  | FASTBuild   |
+----
+====== UnrealHeaderTool Build の回避方法 ======
+Source Code 版 Engine を使用していると、UnrealBuildTool は本来不要なはずの UnrealHeaderTool を何度もビルドしてしまう場合があります。
+  * Makefile.bin が存在しない
+  * Makefile.bin のバージョンが古い
+  * *.uproject file の更新
+  * BuildConfigration.xml の更新
+  * UnrealBuldTool.exe の更新
+などの条件において、Makefile.bin だけでなく UHT 自体をビルドしようとします。
+UHT は <nowiki>C++</nowiki> で書かれているため VisualStudio が install されていないとエラーになります。
+Windows 向けにビルドを行う場合は VisualStudio が必要なのですが、他の Platform 向けに出力する場合はその限りではありません。
+例えば Android の場合、Android SDK (Android NDK) 自体に toolchain 一式が含まれているので単独でビルドを行うことができます。
+実際に Binary 配布版 UE4 (おそらく InstalledBuild 版も同じ) では VisualStudio がなくてもビルドすることができます。
+Source Code 版 UE4 でも、UBT 実行時のコマンドラインオプション -NoBuildUHT または下記の設定によって UHT のリビルドを回避することができます。
+<code cpp>
+<?xml version="1.0" encoding="utf-8"?>
+<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
+   <UEBuildConfiguration>
+      <bDoNotBuildUHT>true</bDoNotBuildUHT>
+   </UEBuildConfiguration>
+</Configuration>
+</code>
+例えばチームで開発作業を行っていると、プログラマのみ VisualStudio を所有しておりプランナーやグラフィックデザイナーは VisualStudio を持っていない場合があります。
+生成した Windows 向けの *.exe はもちろん共有が必要ですが、上記の方法を使えば各種実機(Android,他コンソール)向けに出力する場合、各自でビルドを行うことができます。
+使用方法の例
+  - Target 向けのバイナリを直接作っておきます。
+    * UnrealBuildTool.exe  MyProject  Android  Development  -Project="＜フルパス＞/MyProject/MyProject.uproject"  -WaitMutex  -NoBuildUHT
+  - ビルドします。
+  * UE4Editor 上から実機で起動する場合
+    - プレイボタンのサブメニューから、リストに並んでいる Android Device を選びます。
+    * エラーが出る場合は次の ProjectLauncher を使う方法を試してください。
+  * UE4Editor 上で ProjectLauncher を使う場合
+    - カスタム起動プロファイルに [+] ボタンで新規追加
+    - 「ビルド」の項目を "ビルドしない" に変更
+    - 「クック」を "バイザブック" に変更
+      - クックしたプラットフォームを "Android_ASTC" に変更 (または適切なもの)
+    - 「パッケージ」を "ローカル環境にパッケージ化および格納"
+      * パッケージ化が不要なら "パッケージ化しないでください"
+    - 「デプロイ」を "デプロイしないでください"
+      * パッケージ化ではなく起動したい場合は "デバイスにコピー" に変更します。
+    - 右上の矢印で戻る
+    - 今追加したカスタム起動プロファイルの右端にある起動 ("このプロファイルを起動する") ボタンを押してビルド開始