UBT · UEBuildPlatform（平台构建核心）
UBT · UEBuildPlatform（平台构建核心）
在 UBT 构建平台配置中，通常要实现五个功能模块，UEBuildPlatform是其中的核心。
| 模块类名 | 定位 | 核心职责 |
|---|---|---|
UnrealTargetPlatform | 平台唯一标识符 | 使用 partial struct 模拟类型安全的枚举，提供全局唯一的平台 ID。 |
TargetRules | 编译参数配置 | 存在于项目的 .Target.cs 文件中， 定义构建游戏客户端、服务器或编辑器所需的高级设置。 |
UnrealArchitectureConfig | 平台架构配置 | 确定当前平台构建时支持哪些CPU架构。 |
UEBuildPlatform | 平台构建逻辑 | 负责管理 SDK 检测、工具链路径和架构支持等支持。 |
UEBuildPlatformFactory | 动态加载与注册 | 负责在 UBT 启动时实例化对应的 UEBuildPlatform 类并进行注册。 |
我们将围绕这五个功能模块以 "OpenHarmony"平台为例介绍如何在UBT中添加对应的支持。
步骤 1：定义一个新的 UnrealTargetPlatform 标识符
这是最基础的一步：告诉 UBT "OpenHarmony" 是一个合法的、可构建的平台。
作用说明
UnrealTargetPlatform 是一个全局唯一的标识符，用于在整个引擎代码库中进行平台相关的判断（例如在 .Build.cs 文件中使用：
if (Target.Platform == UnrealTargetPlatform.OpenHarmony)
)。UBT 使用 partial struct 机制允许在不修改核心文件的前提下扩展此列表。
指导操作
在您的平台扩展模块中定义一个 partial struct：
namespace UnrealBuildTool
{
// 注意：UnrealTargetPlatform 在核心 UBT 程序集中被定义为 partial
public partial struct UnrealTargetPlatform
{
/// <summary>
/// OpenHarmony 平台标识符
/// </summary>
public static readonly UnrealTargetPlatform OpenHarmony = FindOrAddByName("OpenHarmony");
}
}
步骤 2：定义平台特定的 TargetRules 配置子对象
这一步旨在为 OpenHarmony 平台提供一套可配置的规则集，并将其集成到全局的 TargetRules 中。这样用户可以在他们的游戏项目中针对 OpenHarmony 进行配置。
作用说明
我们定义独立的平台规则类 (OpenHarmonyTargetRules)，并通过 partial class 扩展核心 TargetRules，使用 [ConfigureSubObject] 属性将其挂载。这使得用户可以在项目的 .Target.cs 或 INI 配置文件中配置 OpenHarmony 特有的设置。
指导操作
分为三个子步骤实现读写分离和集成：
2A. 定义可读写的 OpenHarmonyTargetRules
定义平台独有的配置属性：
namespace UnrealBuildTool
{
// 代码片段
public partial class OpenHarmonyTargetRules
{
[ConfigFile(ConfigHierarchyType.Engine, "OpenHarmonyRuntimeSettings")]
public bool bEnableCustomCrashHandling = false;
[CommandLine("-EnableUBSan")]
public bool bEnableUndefinedBehaviorSanitizer = false;
}
}
2B. 实现只读的 ReadOnlyOpenHarmonyTargetRules 包装器
提供一个只读接口供构建逻辑安全访问：
namespace UnrealBuildTool
{
// 代码片段
public partial class ReadOnlyOpenHarmonyTargetRules
{
private OpenHarmonyTargetRules Inner;
public ReadOnlyOpenHarmonyTargetRules(OpenHarmonyTargetRules Inner) => this.Inner = Inner;
public bool bEnableCustomCrashHandling => Inner.bEnableCustomCrashHandling;
// ... 其他只读属性 ...
}
}
2C. 使用分部类扩展核心 TargetRules 和 ReadOnlyTargetRules
关键点： 在您的平台模块内，使用 partial class 扩展核心 UBT 类，不要修改引擎核心文件。
namespace UnrealBuildTool
{
// 扩展核心 TargetRules，添加可读写配置子对象
partial class TargetRules
{
[ConfigureSubObject]
public OpenHarmonyTargetRules OpenHarmonyPlatform = new OpenHarmonyTargetRules();
}
// 扩展核心 ReadOnlyTargetRules，添加只读访问器
partial class ReadOnlyTargetRules
{
private ReadOnlyOpenHarmonyTargetRules? _OpenHarmonyPlatform = null;
public ReadOnlyOpenHarmonyTargetRules OpenHarmonyPlatform
{
get
{
if (_OpenHarmonyPlatform == null)
_OpenHarmonyPlatform = new ReadOnlyOpenHarmonyTargetRules(Inner.OpenHarmonyPlatform);
return _OpenHarmonyPlatform;
}
}
}
}
步骤 3：实现 UBT - UnrealArchitectureConfig 配置类
这是构建系统用来管理目标平台的硬件 CPU 架构（例如 Arm64 或 x64）。
作用说明
UnrealArchitectureConfig 确保编译器能够生成正确的机器码，并根据项目需求（例如支持哪些架构）进行灵活配置。
指导操作
实现OpenHarmonyArchitectureConfig 定义平台支持的架构并实现配置读取逻辑。
namespace UnrealBuildTool
{
class OpenHarmonyArchitectureConfig : UnrealArchitectureConfig
{
public OpenHarmonyArchitectureConfig()
// 使用 SingleTargetLinkSeparately 模式，并设置默认支持 Arm64 和 X64
: base(UnrealArchitectureMode.SingleTargetLinkSeparately, new[] { UnrealArch.Arm64, UnrealArch.X64 })
{
}
// 返回当前项目需要构建的活动架构列表
public override UnrealArchitectures ActiveArchitectures(FileReference? ProjectFile, string? TargetName) => GetProjectArchitectures(ProjectFile, false);
// 为特定的架构返回特定的文件夹后缀（例如在 Android 中是 'arm64-v8a'）
public override string GetFolderNameForArchitecture(UnrealArch Architecture)
{
// OpenHarmony 示例映射
return Architecture == UnrealArch.Arm64 ? "arm64-v8a" : "x64";
}
// 缓存机制和私有方法 GetProjectArchitectures 略...
// ... (此处省略读取配置INI并填充 ActiveArches 列表的私有实现) ...
}
}
步骤 4：实现 UEBuildPlatform 抽象类
这是构建系统集成的核心，实现所有特定于 OpenHarmony 平台的构建逻辑。
作用说明
UEBuildPlatform 负责管理目标平台的编译器、链接器、SDK 配置和构建环境。您需要实现关键方法来指导 UBT 如何编译和打包二进制文件。
指导操作
实现 OpenHarmonyPlatform 类，覆盖关键方法：
namespace UnrealBuildTool
{
class OpenHarmonyPlatform : UEBuildPlatform
{
// 构造函数略...
// public OpenHarmonyPlatform(OpenHarmonyPlatformSDK InSDK, ILogger InLogger) : base(...) { }
public override bool PlatformAvailable
{
get { return OpenHarmonySDK.IsSDKAvailable(); } // 实现 SDK 检测逻辑
}
public override UEToolChain CreateToolChain(ReadOnlyTargetRules TargetRules)
{
// 返回一个负责实际编译/链接命令的 ToolChain 实例 (需要单独实现 OpenHarmonyToolChain 类)
// return new OpenHarmonyToolChain(TargetRules);
return base.CreateToolChain(TargetRules);
}
public override void GetBuildArchitectureNames(List<string> OutArchitectureNames)
{
OutArchitectureNames.Add("arm64-v8a"); // 添加支持的 ABI
}
public override UEBuildPlatformType PlatformType => UEBuildPlatformType.Mobile;
// ... 还需要实现其他抽象方法和属性，例如打包逻辑 ...
}
}
步骤 5：创建 UEBuildPlatformFactory
这是将上述平台实现动态加载到 UBT 运行时的最后一步。
作用说明
UBT 在启动时扫描所有程序集，查找实现了 UEBuildPlatformFactory 的类，并使用它们来实例化可用的构建平台，将其注册到 UBT 平台管理器中。
指导操作
实现工厂类，负责实例化和注册您的平台实现：
namespace UnrealBuildTool
{
class OpenHarmonyPlatformFactory : UEBuildPlatformFactory
{
public override UnrealTargetPlatform TargetPlatform => UnrealTargetPlatform.OpenHarmony;
public override void RegisterBuildPlatforms(ILogger Logger)
{
// 实例化 SDK 管理器 (OpenHarmonyPlatformSDK 需要单独实现)
OpenHarmonyPlatformSDK SDK = new(Logger);
// 注册平台实例
UEBuildPlatform.RegisterBuildPlatform(new OpenHarmonyPlatform(SDK, Logger), Logger);
// 注册到特定平台组
UEBuildPlatform.RegisterPlatformWithGroup(UnrealTargetPlatform.OpenHarmony, UnrealPlatformGroup.HuaWei);
}
}
}