UBT 全貌：OpenHarmony 平台构建

一. 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 代码架构与目录职责

UBT 的代码设计遵循高度解耦的​分层架构，通过不同的物理目录划分核心框架与平台特定的实现。

• 核心框架层 (​​Configuration/​ ​ , ​System/​ ​ , ​Modes/​ ​ ) ：
  负责解析 .build.cs​ 规则、XML 配置、构建任务依赖图及管理任务模式（如 BuildMode）。
• ​平台抽象层 (​​Platform/​ ​ , ​ToolChain/​ ​ ) ​：
  定义了跨平台接口的基类（如 UEBuildPlatform​、UEToolChain​）。它规定了“一个平台应该具备哪些构建属性”，是适配新平台时必须遵循的​底层契约。
• ​执行引擎层 (​​Executors/​ ​ ) ​：
  负责将生成的任务分发给物理编译器。支持本地多线程并行或分布式加速（如 ​UBA​、​FASTBuild）。
• 平台实现层 (​​Platform/​ ​ ) ：
  这是适配新平台的核心区域。该目录承载了特定平台的差异化逻辑，负责和该平台的原生工具对接，实现SDK 环境检测、编译指令翻译、项目工程生成以及构建安装包等逻辑。

---

三. UBT 打包流程示例

整个构建流程由 UAT 驱动 UBT 内部的平台逻辑。以下展示了从用户命令到最终产出的核心调用顺序：

UBT 核心模块调用流程

graph TD
    %% 样式定义
    classDef uat_style fill:#2b79c2,stroke:#1a4a75,color:#fff,stroke-width:2px;
    classDef ubt_style fill:#7ed321,stroke:#4a7a13,color:#000,stroke-width:2px;
    classDef tool_style fill:#f5f5f5,stroke:#333,color:#333,stroke-dasharray: 5 5;
    classDef output_style fill:#ff8a9a,stroke:#c0392b,color:#000,stroke-width:2px;

    %% 1. UAT 调度层 (控制中心)
    subgraph UAT_Layer [UAT 自动化调度层]
        A[UAT: BuildCookRun 启动]
    end

    %% 2. UBT 构建层 (编译核心)
    subgraph UBT_Build [UBT 构建执行层]
        direction TB
        B[驱动 UBT 编译任务] --> C{Mode 选择}
               
        %% 模式分支
        C -- "GenerateProjectFiles" --> P2_Mode[<b>GenerateProjectFilesMode</b>]
        P2_Mode --> P2[<b>PlatformProjectGenerator.cs</b>]
        
        C -- "Build" --> H[<b>BuildMode 调度逻辑</b>]
        
    %% 平台注册
        B -. "实例化" .-> P1[<b>UEBuildPlatform.cs</b><br/>平台实例注册]
        
        %% 编译链路
        H -- "获取单例" --> P1
        P1 -- "验证环境" --> P3[<b>PlatformSDK.cs</b>]
        P1 -- "生成指令" --> P4[<b>PlatformToolChain.cs</b>]
        
        %% 编译执行
        P4 --> G(调用目标平台编译/链接工具)
        H --> I[<b>ActionExecutor 执行编译</b>]
        P4 -. "封装 Action" .-> I
    I --> J[<b>编译产物</b>]
    end

    %% 3. UBT 交付接口 (属于UBT, 由UAT回传驱动)
    subgraph UBT_Delivery [UBT 打包枢纽接口]
        direction TB
        P5[<b>PlatformExports.cs</b><br/>接口枢纽]
        P5 -- "映射接口" --> P6[<b>UEDeployPlatform.cs</b>]
        P6 --> L[调用原生打包工具]
        L --> M[最终产物 .hap / .apk]
    end

    %% 全局控制流
    A -- "1. 启动编译 (Invoke UBT)" --> B
    I -- "2. Build 结束" --> A
    A -- "3. 驱动打包 (Cook/Stage/Package)" --> P5

    %% 样式应用
    class A uat_style;
    class B,C,H,I,P1,P2,P3,P4,P5,P2_Mode ubt_style;
    class G,L,P6 tool_style;
    class M,J output_style;

打包流程描述

1. ​起点与命令发起：

• UAT 加载自动化脚本并执行 BuildCookRun​ 命令，匹配具体 BuildCommand 实现。

2. 任务分发（生成项目文件 vs. 构建/打包） ：

• UAT 启动 UBT 进程。​UEBuildPlatform.cs​​通过工厂模式实例化对应平台，UBT根据参数选择具体的编译 (BuildMode​) 或 生成项目文件(GenerateProjectFilesMode) 模式。

3. 环境准备：

• ​​UEBuildPlatform.cs​​调用 ​PlatformSDK.cs​ 验证所需 SDK 和工具链环境。

4. ​生成项目文件（可选） ：

• 若用户执行了项目文件生成命令，则调用 ​PlatformProjectGenerator.cs​ 生成平台和IDE特定的项目文件结构。

5. ​执行 C++ 编译：

• ​BuildMode​ 创建 UEBuildTarget​ 编译任务，PlatformToolChain.cs​生成编译器命令行和封装Action​，通过执行器（如ParallelExecutor）并发调用本地编译器完成编译。

6. 最终交付（打包与部署） ：

• 编译完成后，UAT 继续执行 Cook、Stage、Package 阶段，UAT 通过 ​PlatformExports.cs​​ 调度 ​UEDeployPlatform.cs​ 完成打包产物整合和调用平台原生工具生成可安装包。

---

四. 适配新平台所需完成的工作

根据上面的构建示例流程可知，为虚幻引擎添加一个新的目标平台需要扩展 UBT 中平台实现的6个C# 类文件，它们通常位于 Engine/Source/Programs/UnrealBuildTool/Platform/ 路径下。

这些模块协同工作，定义了新平台的所有构建细节：

模块文件	职责概述	适配关注点
UBT - PlatformSDK.cs	SDK/NDK 检测与管理	实现自动查找、验证新平台开发工具链的安装路径和版本。
UBT - PlatformToolChain.cs	编译器/链接器管理核心	封装实际的编译命令、参数、ABI 和 CPU 指令集差异。
UBT - UEBuildPlatform.cs	平台构建逻辑核心	注册新平台、定义支持的架构、统筹调用 SDK 和工具链。
UBT - PlatformProjectGenerator.cs	生成 IDE 项目文件	确保主流 IDE 能正确识别和配置新平台。
UBT - UEDeployPlatform.cs	安装包生成与部署支持	实现生成特定格式安装包（如 .apk, .ipa）的逻辑。
UBT - PlatformExports.cs	UAT 与 UBT 平台层的桥梁	封装供 UAT 调用的公共方法。

‍