本手册旨在系统地指导如何在UE5.6中添加 OpenHarmony 平台的支持。整个流程遵循Epic Games推荐的平台扩展架构，并特别针对OpenHarmony的Hvigor构建系统和原生ArkNative API进行定制。
阶段一：环境准备与架构搭建
此阶段旨在建立必要的基础开发环境和源代码管理。
1.1 获取UE5.6的源码
从内部引擎源码仓库中获取UE5.6的源码：
P4 Server: <your-perforce-server>:1666
一. UBT 的作用与核心价值
Unreal Build Tool (UBT) 是一个定制化的 C# 命令行工具，负责管理虚幻引擎源代码在不同配置和平台下的 C++ 编译过程。
其核心价值在于将平台差异抽象化。它为上层工具（UAT）提供标准接口，隐藏了底层 SDK、复杂的编译标志以及不同平台工具链（ToolChain）的实现细节。
主要作用包括：
- 管理 C++ 模块依赖：UBT 解析每个模块的
.build.cs文件，确定正确的编译顺序和依赖关系。 - 代码生成：调用 Unreal Header Tool (UHT) ，为虚幻引擎的反射系统生成必要的 C++ 元数据代码。
- 调用原生工具链：抽象化平台差异，调用目标平台的原生编译器（如
MSVC、Clang）和链接器执行实际的编译工作。 - 生成项目文件：根据源代码动态生成 IDE（如 Visual Studio 的
.sln 和.vcxproj文件）所需的项目配置。 - 自动化流程集成：配合 UAT 完成从代码编译到最终打包的自动化流程。
在 UBT 构建平台配置中，通常要实现五个功能模块，UEBuildPlatform是其中的核心。
| 模块类名 | 定位 | 核心职责 |
|---|---|---|
UnrealTargetPlatform |
平台唯一标识符 | 使用 partial struct 模拟类型安全的枚举，提供全局唯一的平台 ID。 |
TargetRules |
编译参数配置 | 存在于项目的 .Target.cs 文件中， 定义构建游戏客户端、服务器或编辑器所需的高级设置。 |
UnrealArchitectureConfig |
平台架构配置 | 确定当前平台构建时支持哪些CPU架构。 |
UEBuildPlatform |
平台构建逻辑 | 负责管理 SDK 检测、工具链路径和架构支持等支持。 |
UEBuildPlatformFactory |
动态加载与注册 | 负责在 UBT 启动时实例化对应的 UEBuildPlatform 类并进行注册。 |
一. PlatformSDK 的定位与用途
当我们需要为某个平台实现它的PlatformSDK时，我们需要先了解UEBuildPlatformSDK。
UEBuildPlatformSDK 在 Unreal Build Tool (UBT) 架构中充当平台开发工具包（SDK）配置管理器的角色。它的核心功能是管理特定平台的 SDK、NDK 和工具链的安装路径、版本信息以及环境配置。它负责定位系统上的开发工具。
该模块的主要用途包括：
- SDK/NDK 检测：
核心职责是定位 SDK/NDK 的根目录，并验证其存在性和有效性。 - 版本检测：
检查并返回 SDK/NDK 的版本号，确保符合构建要求。 - 环境自检：
提供接口来快速判断是否有可用的 SDK 配置，确保构建的前提条件已满足。
一：PlatformToolChain 在 UBT 中的角色与定位
PlatformToolChain 是 UBT 架构的核心组件，负责管理特定目标平台的底层编译器、链接器以及其他构建工具的交互。
它的主要职责是衔接（或对接）通用的 C++ 模块定义（由 .Build.cs 和 .Target.cs 描述）与特定硬件架构和操作系统所需的实际编译器命令之间的逻辑。
简单来说，UBT 决定构建什么，而 PlatformToolChain 决定如何使用正确的工具去构建。
一. UBT PlatformProjectGenerator 的定位与用途
PlatformProjectGenerator 在 Unreal Engine 构建系统中的定位是连接 UBT 内部数据模型与外部集成开发环境（IDE）或构建系统的桥梁。
其核心作用是：在运行 GenerateProjectFiles 命令时，根据不同平台的需求，定制化生成的项目文件（如 .vcxproj、Makefile、.xcfilelist 等），确保开发者能在目标开发环境中正确地配置、编译和调试特定平台的代码。
一. PlatformExports.cs 的定位与用途
在 Unreal Engine 的构建系统中，PlatformExports.cs（如 AndroidExports.cs、IOSExports.cs）文件的核心定位是充当一个通用接口层（Public Interface Layer），连接平台无关的自动化工具（UAT）和平台特定的构建实现逻辑（UBT Modules、SDK Tools）。
它们的主要用途包括：
一、UBT 中的构建架构管理
UnrealArch：
UnrealArch 是一个枚举类型（Enum-like Class）， 代表构建平台的一个特定硬件 CPU 架构（例如 Arm64、x64）。
- 用途： 此标识符直接指导底层的编译器和链接器生成特定 CPU 指令集的机器码。每个平台相关的自动化脚本（如
AndroidPlatform.Automation.cs）会将其内部识别的架构字符串映射到这个标准类型。 - 注意： 当 UBT 需要执行需要明确单一目标架构的特定步骤（例如链接阶段），且配置了多个架构时，可能会要求明确指定一个架构。
一. UBT UEDeployPlatform.cs 的定位与用途
UEDeployPlatform.cs 在 Unreal Engine 构建系统（Unreal Build Tool，UBT）中至关重要，它扮演了连接 UBT 核心构建逻辑与目标平台原生打包工具之间的关键桥梁角色。
主要功能：
- 生成标准平台安装包：负责生成特定格式的交付物，包括
APK/AAB (Android)、IPA (iOS)、HAP/APP(HarmonyOS/Apple) 或标准的桌面安装程序。 - 快速部署与调试支持：通过实现
PrepTargetForDeployment等方法，为开发者提供快速迭代的能力，支持编辑器直接启动和调试所需的临时包准备工作。 - 提供统一的自动化接口：作为标准化的入口点，供
Unreal Automation Tool（UAT） 和虚幻编辑器调用，例如PrepForUATPackageOrDeploy方法，以自动化触发完整的构建、打包和部署流程。
一. UAT 简介：核心价值与定位
Unreal Automation Tool (UAT) 是虚幻引擎中基于 C# 开发的核心自动化脚本框架。它作为引擎工作流的统一调度中心，将原本零散的流程整合为标准化的流水线，涵盖了从代码编译到最终交付的全生命周期管理。
核心功能与作用：
- 端到端流水线管理：
UAT 负责管理项目的构建（Build）、资产平台化转换（Cook） 、打包（Package）、部署（Deploy）及自动化测试（Test）。它将复杂的命令行操作封装为一致的任务流。 - 资产跨平台转换 (Cooking) ：
将引擎内的通用资源（如材质、模型、贴图）转换与优化为目标平台（如 PS5、Android、Windows）能够直接读取的二进制格式，确保运行时的读取效率和兼容性。 - 跨平台构建标准化：
屏蔽了不同操作系统和硬件平台（PC、移动端、主机）之间的环境差异，提供统一的执行接口，极大降低了多平台发布的维护成本。 - 高层级流程调度：
UAT 位于构建链的最顶层。在执行代码编译时，它会按需调用 UBT (Unreal Build Tool) 进行底层编译，并随后触发后续的资源打包与分发逻辑，实现“一键式”全流程自动化。 - CI/CD 与无人值守发布：
支持完整的命令行驱动，可无缝集成至 Jenkins、GitHub Actions 或 GitLab CI 等持续集成系统，实现自动化的每日构建（Daily Build）与版本发布。 - 可扩展性与定制化：
开发者可以通过编写自定义的BuildCommand类，灵活扩展特定项目的自动化逻辑（如自动上传 CDN、同步符号表等）。