BuildGraph 脚本元素

本页面的内容：

BuildGraph 脚本以 XML 编写。此文档包含 BuildGraph 脚本中的数据类型以及其整体结构。

元素

元素描述它们包含的数据，使它们成为 BuildGraph 脚本的基础构建块之一。下表包含作为元数据提供的项目，将在构建系统上运行时导出。在本地执行任务时它们不会被 BuildGraph 直接使用，将以 [META] 标记。

图表结构

一个 BuildGraph 脚本通常由以下元素定义：

  • <Node>

  • <Aggregate>

  • <Agent>

  • <Trigger>

节点

<Node> 是 BuildGraph 中执行的最小单位，拥有一套输入和输出。每个 <Node> 由按顺序执行的一个任务序列组成。

属性 类型 是否必需？ 描述
Name 命名 必需 节点名。
Requires 目标列表 可选 由此节点需要执行的其他节点生成的节点列表、聚合，或标记文件集，由分号间隔。
Produces 标记列表 可选 此节点向其他节点提供的标记文件集，由分号间隔。
After 目标列表 可选 在此节点之前运行的节点列表，如他们为当前目标的部分（如非当前目标的部分，则无视）。由分号间隔。
NotifyOnWarnings 布尔 可选 如为 false，此节点将不生成警告通知。只由构建系统使用。默认为 true。[META]
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

聚合

<Aggregate> 声明一个命名聚合，可用作一套其他节点（或生成的标签集）的同义词。

属性 类型 是否必需？ 描述
Name 命名 必需 聚合名。
Requires 目标列表 必需 此聚合的依赖性列表。可能是节点、标记的文件集，或代理群组。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

代理

<Agent> 定义按次序执行的节点上代理的要求（无需清理中间目录）。本地构建时将无视 <Agent> 要求，但必须被指定。

属性 类型 是否必需？ 描述
Name 命名 必需 群组名。
Type 辨识符列表 可选 运行的代理类型。此字符串的含义由 host 构建系统所推断；它不含任何本质含义。[META]
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

触发

<Trigger> 的作用是图表部分（该图表只在显式用户介入后执行）的一个容器。如需在触发后执行节点，将 -Trigger=<Name> 传至命令行。

属性 类型 是否必需？ 描述
Name 命名 必需 触发名。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

属性操作

BuildGraph 属性可通过以下元素进行修改：

  • <Property>

  • <Option>

  • <EnvVar>

属性

<Property> 设置属性的数值。如外部作用域中的属性已使用相同命名声明，<Property> 会将其覆盖。否则将在当前作用域中声明一个新属性。

属性 类型 是否必需？ 描述
Name 命名 必需 设置的属性名。
Value 字符串 必需 属性的新值。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

选项

<Option> 定义可从命令行进行设置的用户选项。<Option> 可能只出现在全局作用域。

属性 类型 是否必需？ 描述
Name 命名 必需 通过选项数值初始化的选项（和属性）名。
Description 字符串 必需 通过 -ListOnly 参数运行 BuildGraph 时选项显示的描述。
Restrict 正则表达式 可选 匹配此选项有效数值的正则表达式（如 [a-zA-Z]+, true | false）。
DefaultValue 字符串 必需 用户不进行显式设置时的选项默认值。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

EnvVar

<EnvVar> 声明属性，以包含环境变量的内容（如未设置则为空白字符串）。 <EnvVar> 可能只出现在全局作用域。

属性 类型 是否必需？ 描述
Name Name Required 作为属性引入的环境变量名。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

流动控制

可通过以下元素控制 BuildGraph 脚本的流动。

  • <Include>

  • <Do>

  • <Switch>

  • <ForEach>

包括

<Include> 处理其他 BuildGraph 脚本的内容，就像它存在出现在此文件中那样。 <Include> 可能只出现在全局作用域。

属性 类型 是否必需？ 描述
Script 字符串 必需 需要包含的脚本的路径（相对于当前脚本）。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

Do

<Do> 将元素的序列分组，仅在条件求值为 true 时对它们进行处理。

属性 类型 是否必需？ 描述
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

切换

<Switch> 与 C 切换语句相似，因其在分支序列上对条件求值，使用求值为 true 的条件处理首个语句。

<Switch> 语句示例： 

<Switch>
    <Case If=X>
        <Elements go here>
    </Case>
    <Case If=Y>
        <Elements go here>
    </Case>
    <Default>
        <Elements go here>
    </Default>
</Switch>
属性 类型 是否必需？ 描述
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

ForEach

<ForEach> 通过在一个列表中指定到每个项目的给定属性（由分号间隔）来展开元素主体。

<ForEach> 语句示例： 

<ForEach Name="Counter" Values="1;2;3;4;5">
    <Log Message="Counter=$(Counter)"/>
</ForEach>
属性 类型 是否必需？ 描述
Name 命名 必需 指定到列表中每个数值的属性。
Values 字符串列表 必需 数值列表，由分号间隔。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

诊断

可通过以下元素对 BuildGraph 脚本执行诊断。

  • <Warning>

  • <Error>

警告

<Warning> 会在执行图表前输出警告消息。可能包含在节点、代理、触发、或整体作用域中。如` 在被裁剪到被执行的目标后仍为图表的一部分，它将只提供一个输出。

属性 类型 是否必需？ 描述
Message 字符串 必需 被打印到日志的文本。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

错误

<Error> 将输出错误消息。<Error> 可能包含在节点、代理、触发、或整体作用域中。如 <Error> 在被裁剪到被执行的目标后仍为图表的一部分，它将只提供一个输出。

属性 类型 是否必需？ 描述
Message 字符串 必需 被打印到日志的文本。
If 条件 可选 将被求值的条件。元素将被无视，除非条件求值为 true。

任务

通常而言，项目特定的实用脚本被实现为 AutomationTool BuildCommand 类。然而有时您需要为项目自动化自定义任务。这时 BuildGraph 便可提供协助。BuildGraph 可通过任意数量的任务进行延展，便于您用最符合自身需求的方式自定义构建自动化任务。以下部分将说明使用 BuildGraph 创建自定义任务的多种方式，包括预定义任务的列表，为创建自定义任务提供良好的起始点。

自定义任务

如需新建自定义任务，需实现一个派生自 CustomTask 类的类并对其应用 [TaskElement] 属性。TaskElement 构造函数拥有两个参数：其所代表的 XML 元素的命名、和包含其参数的类类型（将在加载时传至构造函数）。

如需从 XML 文件读取参数类域，将 [TaskParameter] 属性附加到任务。附加 TaskParameter 属性将说明形式参数为必须或可选，包括应被应用到实际参数的额外验证。

预定义任务

作为创建任务的起始点，我们提供各种预定义任务供您使用。如果需要上手使用的简单预定义任务，我们推荐将 LogTask 用作一个较好的起始点。如需了解 BuildGraph 的最新改良，请将此页设为书签，以下预定义任务列表将定期更新。

命令

调用一个 AutomationTool 子进程运行给定的命令。

Name 字符串 必需 要执行的命令名
Arguments 字符串 可选 传至命令的参数
MergeTelemetryWithPrefix 字符串 可选 如为非空，将使用给定前缀指示来自命令的遥测合入此 UAT 示例的遥测。可能为一个空（非空）字符串。
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

Commandlet

生成编辑器运行一个 commandlet。

Name 字符串 必需 执行的 commandlet 名
Project 文件规范 可选 和编辑器一同运行的项目
Arguments 字符串 可选 被传至 commandlet 的参数
EditorExe 文件名 可选 使用的编辑器可执行文件。默认为当前平台的开发 UE4Editor 可执行文件。
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

编译

使用 UnrealBuildTool 编译目标。

Target 字符串 必需 编译目标
Configuration Unreal 目标配置 必需 要编译的配置
Platform Unreal 目标平台 必需 编译针对的平台
Arguments 字符串 可选 UnrealBuildTool 的额外参数
Tag 标记列表 可选 应用此标记，构建此任务的产品
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

Cook

为特定平台 cook 一套地图。

Project 字符串 必需 需要 cook 的项目文件
Platform 字符串 必需 目标 cook 平台（如 WindowsNoEditor）
Maps 字符串 可选 被 cook 的地图列表，由“+”字符间隔
Versioned 布尔 可选 传至 cooker 的额外参数
Arguments 字符串 可选 传至 cooker 的额外参数
Tag 标记列表 可选 应用此标记，构建此任务的产品
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

复制

从一个目录复制文件到另一个目录。

Files 文件规范 必需 文件规范列表，由分号间隔（如 .cpp;Engine/.../.bat）；或者标记集的名称。相对路径基于 FromDir。
FromDir 目录名 必需 进行复制的基础目录。
ToDir 目录名 必需 复制的目标目录
Tag 标记列表 可选 应用此标记，构建此任务的产品
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

CsCompile

编译 C# 项目文件及其依赖性。

Project 字符串 必需 需要编译的 C# 项目文件。可指定多个项目文件，由分号间隔。
Configuration 字符串 可选 进行编译的配置
Platform 字符串 可选 进行编译的平台
Arguments 字符串 可选 传至编译器的额外选项
EnumerateOnly 布尔 可选 只列举构建产物，不对项目进行实际编译。
Tag 标记列表 可选 应用此标记，构建此任务的产品
TagReferences 标记列表 可选 应用到项目拥有的非私有引用的标记（即处于外部且未复制进输出 dir）
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

删除

删除一套文件。

Files 文件规范 必需 文件规范列表，由分号间隔（如 .cpp;Engine/.../.bat）；或者标记集的名称
DeleteEmptyDirectories 布尔 可选 删除文件后是否删除空白目录。默认为 true。
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

日志

将消息（和其他可选诊断信息）打印至输出日志

Message 字符串 可选 显示的消息
Files 文件规范 可选 指定后，文件的给定列表将在给定消息后显示。
IncludeContents 布尔 可选 指定后，将显示给定文件的内容。
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

PakFile

从给定的一套文件创建 APK 文件。

Files 文件规范 必需 添加到 pak 文件的文件列表、通配符和标记集，由“;”隔开。
Output 文件名 必需 输出的 PAK 文件
ResponseFile 文件名 可选 响应文件（包含添加到 pak 文件的文件列表）的路径，无需对它们进行单独指定
RebaseDir 目录名 可选 相对重建文件基数的目录。指定后，所列目录下的最短路径将用于每个文件。
Order 文件名 可选 给出文件排序的脚本
Sign 字符串 可选 此 pak 文件的加密键
Compress 布尔 可选 是否压缩文件
Arguments 字符串 可选 传至 UnrealPak 的额外参数
Tag 标记列表 可选 应用此标记，构建此任务的产品
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

重命名

重命名文件或文件群组。

Files 文件规范 必需 需要重命名的单个或多个文件
From 目录名 可选 需要匹配的当前文件名或样式（如 *.txt）。不应包含路径分隔符。
To 路径名 必需 文件的新命名。不应包含路径分隔符。
Tag 标记列表 可选 应用到重命名文件的标记
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

SetVersion

通过给定版本信息更新本地版本文件 (Engine/Source/Runtime/Launch/Resources/Version.h, Engine/Build/Build.version 和 Engine/Source/Programs/DotNETCommon/Metadata.cs)。

Change Int32 必需 在版本文件中设置的变更列表
CompatibleChange Int32 可选 在版本文件中设置的引擎兼容变更列表
Branch 字符串 必需 分支字符串
Build 字符串 可选 构建版本字符串
Licensee 布尔 可选 是否将 IS_LICENSEE_VERSION 标记设为 true
SkipWrite 布尔 可选 设置后，不要对文件进行实际写入 - 返回将被更新的版本文件即可。适用于本地构建。
Tag 标记列表 可选 应用此标记，构建此任务的产品
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

签名

使用安装证书对一套可执行文件进行签名。

Files 文件规范 必需 文件规范列表，由分号间隔（如 .cpp;Engine/.../.bat）；或者标记集的名称
Tag 标记列表 可选 应用此标记，构建此任务的产品
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

生成

生成一个外部可执行文件并等候其完成。

Exe 文件名 必需 要生成的可执行文件
Arguments 字符串 可选 新建处理的参数
ErrorLevel Int32 可选 被认作错误的最小出口代码。
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

暂存

构建中列出的暂存文件接收到输出目录。

Project 文件名 可选 此目标所属的项目
Target 字符串 必需 要暂存的目标名
Platform Unreal 目标平台 必需 要暂存的平台
Configuration Unreal 目标配置 必需 要暂存的配置
Architecture 字符串 可选 要暂存的架构
ToDir 字符串 必需 暂存接收文件的目录
Overwrite 布尔 可选 是否覆盖现有文件
Tag 标记列表 可选 应用此标记，构建此任务的产品
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

剥离

从一套文件中剥离调试信息。

Platform Unreal 目标平台 必需 剥离二进制的平台工具链
BaseDir 目录名 可选 文件存储的目录
Files 文件规范 必需 文件规范列表，由分号间隔（如 .cpp;Engine/.../.bat）；或者标记集的名称
OutputDir 目录名 必需 剥离文件的输出目录。默认为输入路径（覆盖输入文件）。
Tag 标记列表 可选 应用此标记，构建此任务的产品
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

提交

新建一个变更列表并将一套文件提交到 Perforce 流送。

Description 字符串 必需 已提交变更列表的描述
Files 文件规范 必需 要提交的文件
FileType 字符串 可选 提交文件的 Perforce 文件类型（如 binary+FS32）
Workspace 字符串 可选 工作区命名。指定后，将使用给定的流送和根目录提交文件。如否，将使用当前工作区。
Stream 字符串 可选 工作区的流送，默认为当前流送。除非工作区属性也被指定，否则将被无视。
RootDir 目录名 可选 流送的根目录。如未指定，则默认为当前的根目录。
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

标记

为给定的一套文件应用标记。列举“Files”参数给定的标记和文件规格可找到文件列表。与“Filter”参数不匹配的文件将从列表中移除，之后是由“Except”参数匹配的文件。

BaseDir 目录名 可选 设置基础目录解决相对路径和样式之间的冲突。设置后，所有绝对样式（如 /Engine/Build/...）将被当作为与此路径相对的状态。如未设置，它们将被当作完全绝对。
Files 文件规范 必需 使用的文件集，包括通配符和标记名，由分号间隔。设置后，解决相对于 BaseDir；如未设置，则相对于分支根目录。
Filter 文件规范 可选 过滤文件列表的样式，包括标记名或通配符。设置后，可能包含应用至基础目录的样式。如未指定，则默认为所有文件。
Except 文件规范 可选 需要从匹配列表中剔除的样式集。可能包含应用至基础目录的样式的标记名。
With 标记列表 必需 要应用的标记名
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

TagReceipt

从 *.target 文件进行读取，分派哪些标记构建产品和/或运行时依赖性

Files 文件规范 必需 读取的接收文件集（*.target），包括通配符和标记名，由分号间隔。
EngineDir 目录名 可选 引擎文件夹路径，用于在接收文件中展开 $(EngineDir) 属性。当前工作区默认为引擎目录。
ProjectDir 目录名 可选 项目文件夹路径，用于在接收文件中展开 $(ProjectDir) 属性。当前工作区默认为引擎目录。
BuildProducts 布尔 可选 是否标记列于接收中的构建产品
BuildProductType 字符串 可选 标记何种构建产品（查阅 TargetReceipt.cs - UnrealBuildTool.BuildProductType 中的有效值）
RuntimeDependencies 布尔 可选 是否标记列于接收中的运行时依赖性
StagedFileType 字符串 可选 标记的运行时依赖性（查阅 TargetReceipt.cs - UnrealBuildTool.StagedFileType 中的有效值）
PrecompiledBuildDependencies 布尔 可选 是否标记列于接收中的预编译构建依赖性
PrecompiledRuntimeDependencies 布尔 可选 是否标记列于接收中的预编译运行时依赖性
With 标记列表 必需 要应用的标记名
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

解压

从 zip 档案包解压文件。

ZipFile 文件名 必需 解压 zip 文件的路径
ToDir 目录名 必需 解压文件的输出路径
Tag 标记列表 可选 应用到解压文件的标签
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。

压缩

将文件压缩为一个 zip 档案包。

FromDir 目录名 必需 读取压缩文件的目录
Files 文件规范 可选 文件规范列表，由分号间隔（如 .cpp;Engine/.../.bat）；或者标记集的名称。相对路径取自 FromDir。
ZipFile 文件名 必需 要创建的 zip 文件
Tag 标记列表 可选 应用到已创建 zip 文件的标记
If 条件 可选 是否执行此任务。如该条件求值为 false，它将被无视。
Tags
BuildGraph
完整内容索引