UnrealBuildTool生成ProjectFiles

发表于

GenerateProjectFiles

UE中构建项目之前，都需要先执行GenerateProjectFiles，这样UE会通过mono执行UnrealBuildTool（UBT）收集所有模块的Build.cs，然后生成各种编译所需要的文件。比如*.generated.h等等。

在不同平台、不同IDE下还需要生成不同结构的配置，因为Xcode、VS、Rider的工程配置文件是各不相同的，UBT源码中需要分类去处理。

以VS为例，UBT会为VS生成.sln以及各种模块的.vcxproj文件，里面包含了各个模块的宏定义以及include path，都是由Build.cs生成出来的。这样IDE在打开工程时才知道模块的宏是什么，引用的路径有哪些，也就是常说的IntelliSense功能。当然，更重要的是能让编译器在编译时找到。

支持的IDE

除了VS，UBT还支持为其他的一些IDE或者编译工具生成对应的配置文件。IDE主要是Xcode和Rider/CLion，还有一些小众一点的比如CodeLite、Eddie、KDevelop。编译工具支持CMake、Make、QMake等。

大部分情况我们都是用VS/Xcode/Rider。我在Windows和Mac上都用Rider，因为基于UE定制了一些功能，可以自动生成Generate，而且IntelliSense和查找功能也比较强大。

UBT参数

Project Files for IDEs | Unreal Engine 4.27 Documentation

UE官方给的UBT参数文档很粗糙，只是把一部分参数列出来了，没有说清楚什么时候使用哪些参数，各有什么作用。这里简单介绍一些有用的参数。

  1. 指定IDE配置
    1. 可选参数”-ProjectFiles” “-Rider” “-XCodeProjectFiles”等
    2. 一般默认是”-ProjectFiles”，会生成VS的配置文件和平台必须的文件
    3. 可以自己调用换成”-Rider”或”-XCodeProjectFiles”生成Rider和Xcode的配置
    4. 可以多个组合，但需要运行的平台支持（Win没法生成Xcode的），所以没什么卵用
  2. -Platforms
    1. 生成平台，生成ProjectFiles时仅可选Editor支持的平台，包括Win64/Win32/Mac/Linux
    2. 决定了PLATFORM_XXX等宏的生成
  3. -TargetTypes
    1. 运行模式，Editor或者Game
    2. 决定了WITH_EDITOR等相关宏的生成
  4. -TargetConfigurations
    1. UE编译选项，UnrealTargetConfiguration
    2. 可选Debug/DebugGame/Development/Shipping/Test
    3. 决定了UE_BUILD_XXX宏的生成
  5. -project
    1. .uproject绝对路径
    2. 控制为哪个项目生成配置

参数示例(便于展示参数换行了)：

Windows

1
2
3
4
5
6
./UnrealBuildTool.exe
-Rider
-Platforms=Win64
-TargetTypes=Game
-TargetConfigurations=Shipping
-project="C:\xxx\Game.uproject"

Mac或Linux下需要使用mono调用UBT

1
2
3
4
5
6
mono "xxx/UnrealBuildTool.exe"
-Rider
-Platforms=Mac
-TargetTypes=Game
-TargetConfigurations=Shipping
-project="C:\xxx\Game.uproject"

这样就可以为Rider生成Game项目的Game模式的Shipping编译配置。

一般可以修改TargetTypes更换成Editor模式，或者修改TargetConfigurations来切换编译选项。
Platforms只能选当前所使用的的桌面平台，不支持生成移动平台的，因为生成中的一些操作依赖操作系统的环境，并且UBT代码中做了限制。

不过我们可以修改UBT代码来跳过这个限制，注释以下代码然后重新编译UBT即可在Windows生成Android的配置，在Mac生成Android和IOS的配置。Windows不能生成IOS和Mac的配置，因为生成过程依赖Xcode环境。

Rider生成之后会产生json配置文件，文件路径：
{GameRoot}/Intermediate/ProjectFiles/.Rider/{Platform}/{Configuration}/{TargetType}/{ProjectName}.json

同目录下除了{ProjectName}.json还有一个UE4.json ，里面包含了所需要的全部编译参数和include path。

IDE配置文件

各个IDE的配置各不相同，Xcode是.xcodeproj文件，VS是.vcxproj文件，而Rider是.json文件。

很显然，Rider的文件最方便我们读取使用，而且Win和Mac都支持生成。

这个配置文件对我们有什么作用？

这些配置文件是给IDE或编译工具使用的，正常开发游戏确实用不到这个。但是如果你需要导出指定平台的特点条件下的宏的时候，就需要使用UBT去导出，而如果想不修改UBT就做到这一点，只能像我说的这样调用UBT生成Rider配置文件，然后读取。

其中有用的信息之一是EnvironmentDefinitions，包含了引擎和Game全局的宏定义，其他的宏定义也都来自这些宏。

其次是各个模块的参数，PublicIncludePaths和PrivateIncludePaths包含了这个模块的全部include path。最重要的是ThirdParty下的各个模块，因为这些第三方库的文件路径并不遵循UE的Public/Private文件夹的模式，想收集这些include path会很困难，所以UE通过Build.cs来为这些模块添加include path，并且通过UBT收集然后导出给IDE和编译工具。

调试UBT

UBT是个命令行程序，执行速度很快，想要调试的话是不方便通过attach的方式调试的，最好的办法是通过debug模式启动。

首先在IDE中切换项目为UBT：

然后修改UBT的启动参数，添加自己需要的参数

最后在需要的地方断点，然后debug启动即可。