Language:
Page Info
Tags:
Engine Version:
Share
此中文页面内容对应的英文页面有后续更新,如需浏览最新文档可切换至英文页面浏览。

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 的最新改良,请将此页设为书签,以下预定义任务列表将定期更新。

AgeStore

从文件集中剥离符号的任务。此任务以Microsoft调试器工具SDK附带的AGESTORE工具命名,实际上是一个单独的实现。主要的区别在于其使用的是最后修改时间来决定要删除的文件,而非最后访问时间。

平台

UnrealTargetPlatform

必需

设置符号年龄的目标平台。

StoreDir

字符串

必需

符号服务器目录。

天数

Int32

必需

保存符号需要的天数。

过滤器

字符串

可选

删除符号前子字符串应与目录文件命名匹配。多版本共享相同符号服务器时,“衰老储存”任务可避免删除其他版本中的符号。平台工具链定义的符号服务器结构将决定过滤器使用的特定数值。

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

命令

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

命名

字符串

必需

要执行的命令名

参数

字符串

可选

传至命令的参数

MergeTelemetryWithPrefix

字符串

可选

如为非空,将使用给定前缀指示来自命令的遥测合入此UAT示例的遥测。可能出现空白(非空)字符串。

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

命令行

生成编辑器运行命令行。

命名

字符串

必需

要执行的命令行命名

项目

文件规范

可选

和编辑器一同运行的项目

参数

字符串

可选

传至命令行的参数

EditorExe

文件名

可选

要使用的编辑器可执行文件。当前平台默认为开发UE4Editor可执行文件。

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

编译

使用UnrealBuildTool编译目标。

Target

字符串

必需

要编译的目标

配置

UnrealTargetConfiguration

必需

要编译的配置

平台

UnrealTargetPlatform

必需

编译针对的平台

参数

字符串

可选

UnrealBuildTool 的额外参数

AllowXGE

布尔

可选

是否可使用XGE进行编译

AllowParallelExecutor

布尔

可选

是否可使用此编译的并列执行程序

标签

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

烘焙

为特定平台烘焙一套地图

项目

字符串

必需

需要烘焙的项目文件

平台

字符串

必需

目标烘焙平台(如 WindowsNoEditor)

地图

字符串

可选

被烘焙的地图列表,由“+”字符间隔

版本

布尔

可选

传至烘焙器的额外参数

参数

字符串

可选

传至烘焙器的额外参数

标签

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

复制

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

文件

文件规范

可选

应用至输入文件列表的过滤器。可选。

文件规范

必需

复制源头的样式(如Engine/*.txt)

文件规范

必需

需要复制到的目录

覆盖

布尔

可选

是否覆盖现有文件

标签

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

CsCompile

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

项目

字符串

必需

要编译的C#项目文件。可用分号进行间隔,指定多个项目文件。

配置

字符串

可选

要编译的配置

平台

字符串

可选

要编译的平台

参数

字符串

可选

传至编译器的额外选项

EnumerateOnly

布尔

可选

只列举编译产物,不对项目进行实际编译。

标签

标签列表

可选

编译此任务产物所应用的标签

TagReferences

标签列表

可选

应用到项目中非私有引用的标签(即处于外部且未复制进输出dir)

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

删除

删除文件集。

文件

文件规范

必需

文件规范列表,由分号间隔(如 .cpp;Engine/.../.bat);或者标签集的命名

DeleteEmptyDirectories

布尔

可选

删除文件后是否删除空白目录。默认为true。

If

条件

可选

是否执行此任务。若该条件计算出为false,则忽略此任务。

日志

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

消息

字符串

可选

显示的消息

文件

文件规范

可选

指定后,将在给定消息之后显示文件的给定列表。

IncludeContents

布尔

可选

指定后,将显示给定文件的内容。

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

移动

将文件从当前目录移动到另一个目录。

文件

文件规范

可选

应用至输入文件列表的过滤器。可选。

文件规范

必需

需要复制其文件的平台(如Engine/*.txt)

文件规范

必需

需要复制到的目录

标签

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

MsBuild

执行MsBuild

项目

字符串

必需

要编译的C#项目文件。可用分号进行间隔,指定多个项目文件。

配置

字符串

可选

要编译的配置

平台

字符串

可选

要编译的平台

参数

字符串

可选

传至编译器的额外选项

冗余度

字符串

可选

MSBuild输出冗余度

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

PakFile

从给定的文件集创建一个PAK文件。

文件

文件规范

必需

添加到pak文件的文件列表、通配符和标签集,由“;”间隔。

输出

文件名

必需

输出的PAK文件

ResponseFile

文件名

可选

响应文件(包含添加到pak文件的文件列表)的路径,无需对其进行单独指定

RebaseDir

目录命名

可选

重设相关文件基数的目录。指定后,列出的目录下最短路径将用于所有文件。

排序

文件名

可选

给出文件排序的脚本

签名

字符串

可选

此pak文件的加密键

压缩

布尔

可选

是否压缩文件

参数

字符串

可选

传至UnrealPak的额外参数

标签

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

重命名

重命名文件或文件组。

文件

文件规范

必需

需要重命名的单个或多个文件

目录名

可选

需要匹配的当前文件名或样式(如 *.txt)。不应包含任何路径分隔符。

路径名

必需

文件的新命名。不应包含任何路径分隔符。

标签

标签列表

可选

应用到重命名文件的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

SetVersion

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

变更

Int32

必需

在版本文件中设置的变更列表

CompatibleChange

Int32

可选

在版本文件中设置的引擎兼容变更列表

分支

字符串

必需

分支字符串

版本

字符串

可选

编译版本字符串

注册者

布尔

可选

是否将IS_LICENSEE_VERSION标签设为true

提升

布尔

可选

是否将ENGINE_IS_PROMOTED_BUILD标签设为

SkipHeader

布尔

可选

设置后,将不更新Version.h;仅更新数据文件(如 Build.version、Metadata.cs)。编辑器运行时可读取build.version中的版本变更列表。

SkipWrite

布尔

可选

设置后,不要对文件进行实际写入,返回将被更新的版本文件即可。对本地文件有用。

标签

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

签名

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

文件

文件规范

必需

文件规范列表,由分号间隔(如 .cpp;Engine/.../.bat);或者标签集的命名

Tag

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

生成

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

Exe

文件名

必需

要生成的可执行文件

Arguments

字符串

可选

新建处理的参数

ErrorLevel

Int32

可选

被认作错误的最小出口代码。

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

暂存

编译中列出的暂存文件接收到输出目录。

项目

文件名

可选

此目标所属的项目

目标

字符串

必需

要暂存的目标名

平台

UnrealTargetPlatform

必需

要暂存的平台

配置

UnrealTargetConfiguration

必需

要暂存的配置

架构

字符串

可选

要暂存的架构

ToDir

字符串

必需

暂存接收文件的目录

覆盖

布尔

可选

是否覆盖现有文件

标签

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

剥离

从文件集中剥离调试信息。

平台

UnrealTargetPlatform

必需

可剥离二进制的平台工具链

BaseDir

目录名

可选

文件存储的目录

文件

文件规范

必需

文件规范列表,由分号间隔(如 Engine/.../*.pdb);或者标签集的命名

OutputDir

目录命名

可选

剥离文件的输出目录。默认为输入路径(覆盖输入文件)。

标签

标签列表

可选

编译此任务产物所应用的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

提交

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

描述

字符串

必需

所提交变更列表的描述

Files

文件规范

必需

要提交的文件

FileType

字符串

可选

提交的文件的Perforce文件类型(如二进制+FS32)

工作区

字符串

可选

工作区命名。指定后,将使用给定的流送和根目录提交文件。否则将使用当前工作区。

流送

字符串

可选

工作区的流送;默认为当前流送。除非同时指定工作区属性,否则将被忽略。

RootDir

目录命名

可选

流送的根目录。若未指定,默认为当前的根目录。

RevertUnchanged

布尔

可选

进行提交前是否恢复未修改的文件

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

SymStore

从文件集剥离符号的任务

平台

UnrealTargetPlatform

必需

处理符号文件必需的平台工具链。

文件

字符串

必需

输出文件的列表。将从该列表中提取PDB。

StoreDir

字符串

必需

压缩文件的输出目录。

产物

字符串

必需

符号保存记录的产物命名。

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

标签

将标签应用至给定文件集。列举“Files”参数给定的标签和文件规格可找到文件列表。与“Filter”参数不匹配的文件将首先从该列表中移除,之后移除由“Except”参数匹配的文件。

BaseDir

目录命名

可选

设置基础目录解决相对路径和样式之间的冲突。设置后,所有绝对样式(如 /Engine/Build/...)将被视为与此路径相对。否则,其将被视为完全绝对。

文件

文件规范

必需

使用的文件集,包括通配符和标签名,由分号间隔。设置后,相对于BaseDir进行解决;否则便相对于分支根目录。

过滤器

文件规范

可选

用于过滤文件列表的样式,包括标签名或通配符。设置后,可能将包含应用至基础目录的样式。若未指定,则默认为所有文件。

Except

文件规范

可选

需要从匹配列表中剔除的样式集。可能包含应用至基础目录的样式的标签名。

With

标签列表

必需

要应用的标签名

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

TagReceipt

从*.target文件读取,标记编译产物和/或运行时依赖性的任务。

文件

文件规范

必需

要读取的接收文件集(*.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

目录名

必需

解压文件的输出路径

标签

标签列表

可选

应用到解压文件的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

压缩

将文件压缩为zip档案包。

FromDir

目录名

必需

读取压缩文件的目录

文件

文件规范

可选

文件规范列表,由分号间隔(如 .cpp;Engine/.../.bat);或者标签集的命名。相对路径取自 FromDir。

ZipFile

文件名

必需

要创建的zip文件

标签

标签列表

可选

应用到已创建zip文件的标签

If

条件

可选

是否执行此任务。若该条件计算出false,则忽略此任务。

Tags