Choose your operating system:
Windows
macOS
Linux
通常而言,项目特定的实用脚本被实现为 AutomationTool BuildCommand 类。然而有时您需要为项目自动化自定义任务。这时 BuildGraph 便可提供协助。BuildGraph 可通过任意数量的任务进行延展,便于您用最符合自身需求的方式自定义构建自动化任务。以下部分将说明使用 BuildGraph 创建自定义任务的多种方式,包括预定义任务的列表,为创建自定义任务提供良好的起始点。
自定义任务
如需新建自定义任务,需实现一个派生自
CustomTask
类的类并对其应用
[TaskElement]
属性。
TaskElement
构造函数拥有两个参数:其所代表的 XML 元素的命名、和包含其参数的类类型(将在加载时传至构造函数)。
如需从 XML 文件读取参数类域,将
[TaskParameter]
属性附加到任务。附加
TaskParameter
属性将说明形式参数为必须或可选,包括应被应用到实际参数的额外验证。
预定义任务
作为创建任务的起始点,我们提供各种预定义任务供您使用。如果需要上手使用的简单预定义任务,我们推荐将
LogTask
用作一个较好的起始点。如需了解 BuildGraph 的最新改良,请将此页设为书签,以下预定义任务列表将定期更新。
对于打包任务来说,BuildCookRun是一个强力而又常用的工具。更多详情,请参阅概述文档: 构建操作 。
AgeStore
这是从一组文件分离符号的任务。该任务是根据Microsoft调试工具SDK随附的AGESTORE实用程序命名的,但实际上它是一个单独的实现。主要区别在于,它使用最后修改时间来确定要删除哪些文件,而不是上次访问时间。
Platform |
UnrealTargetPlatform |
必需 |
让符号老化所针对的目标平台。 |
StoreDir |
String |
必需 |
符号服务器目录。 |
Days |
Int32 |
必需 |
符号值得保留的天数。 |
BuildDir |
String |
可选 |
构建目录的根目录,用于检查是否存在现有的构建版本指定目录。 |
Filter |
String |
可选 |
在删除服务号之前,目录文件名中要匹配的子字符串。如果有多个构建共享同一个符号服务器,这允许"age store"任务避免从其他构建中删除符号。filter值的具体用法由平台工具链定义的符号服务器结构确定。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Command
调用AutomationTool子进程以运行指定命令。
Name |
String |
必需 |
要执行的命令名称。 |
Arguments |
String |
可选 |
要传递给命令的参数。 |
MergeTelemetryWithPrefix |
String |
可选 |
如果非空,则指示来自命令的遥测合并到具有给定前缀的这个UAT实例的遥测。可能是空(非空)字符串。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Commandlet
产生编辑器以运行commandlet。
Name |
String |
必需 |
要执行的commandlet名称。 |
Project |
File Spec |
可选 |
要通过编辑器运行的项目。 |
Arguments |
String |
可选 |
要传递到commandlet的参数。 |
EditorExe |
FileReference |
可选 |
要使用的编辑器可执行文件。默认为当前平台的开发UE4Editor可执行文件。 |
ErrorLevel |
Int32 |
可选 |
最低等级的退出代码,视作错误处理。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Compile
使用UnrealBuildTool编译目标。
Target |
String |
必需 |
要编译的目标。 |
Configuration |
UnrealTargetConfiguration |
必需 |
要编译的配置。 |
Platform |
UnrealTargetPlatform |
必需 |
编译所针对的平台。 |
Project |
String |
可选 |
要编译的项目 |
Arguments |
String |
可选 |
UnrealBuildTool的其他参数。 |
AllowXGE |
Boolean |
可选 |
是否允许对编译使用XGE。 |
AllowParallelExecutor |
Boolean |
可选 |
是否允许对该编译使用并行执行器。 |
Clean |
Nullable`1 |
可选 |
是否允许清理该目标。如果不指定,则在命令行上传递-Clean参数时清理目标。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Cook
烘焙特定平台的所选贴图
Project |
String |
必需 |
要烘焙的项目文件。 |
Platform |
String |
必需 |
目标烘焙平台(如WindowsNoEditor)。 |
Maps |
String |
可选 |
要烘焙的贴图列表,以"+"字符分隔。 |
Versioned |
Boolean |
可选 |
要传递到烘焙器的其他参数。 |
Arguments |
String |
可选 |
要传递到烘焙器的其他参数。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Copy
将文件从一个目录复制到另一个目录。
Files |
File Spec |
可选 |
要应用于输入文件列表的可选过滤器。 |
From |
File Spec |
必需 |
复制源模式(如Engine/*.txt)。 |
To |
File Spec |
必需 |
复制目标目录。 |
Overwrite |
Boolean |
可选 |
是否覆盖现有文件。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
CsCompile
编译C#项目文件及其依赖项。
Project |
String |
必需 |
要编译的C#项目文件。使用分号可以指定多个项目文件。 |
Configuration |
String |
可选 |
要编译的配置。 |
Platform |
String |
可选 |
要编译的平台。 |
Target |
String |
必需 |
要构建的目标。 |
Arguments |
String |
可选 |
要传递到编译器的其他参数。 |
EnumerateOnly |
Boolean |
可选 |
仅列举构建产品——不会真的编译项目。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
TagReferences |
Tag List |
可选 |
要应用于项目已有的任何非私有引用(如没有复制到输出目录外部引用)的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Delete
删除一组文件。
Files |
File Spec |
必需 |
以分号分隔的指定文件列表(如 .cpp;Engine/.../ .bat)或目标集名称。 |
DeleteEmptyDirectories |
Boolean |
可选 |
删除文件后是否删除空目录。默认为true。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Log
将消息(和其他可选诊断信息)打印到输出日志。
Message |
String |
可选 |
要输出的消息。 |
Files |
File Spec |
可选 |
如果指定,会在指定消息后打印指定文件列表。 |
IncludeContents |
Boolean |
可选 |
如果指定,会打印指定文件的内容。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
ModifyConfig
修改一个配置文件。
File |
File Spec |
必需 |
配置文件的路径。 |
Section |
String |
必需 |
要修改的分段名称。 |
Key |
String |
必需 |
要设置的属性名称。 |
Value |
String |
必需 |
要设置的属性值。 |
Tag |
Tag List |
可选 |
要应用给提取的文件的标记。 |
If |
Condition |
可选 |
是否执行此任务。如果此条件评估false,则将被忽略。 |
Move
将文件从一个目录移动到另一个目录。
Files |
File Spec |
可选 |
要应用于输入文件列表的可选过滤器。 |
From |
File Spec |
必需 |
复制源模式(如Engine/*.txt)。 |
To |
File Spec |
必需 |
复制目标目录。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
MsBuild
执行MsBuild。
Project |
String |
必需 |
要编译的C#项目文件。使用分号可以指定多个项目文件。 |
Configuration |
String |
可选 |
要编译的配置。 |
Platform |
String |
可选 |
要编译的平台。 |
Arguments |
String |
可选 |
要传递到编译器的其他选项。 |
Verbosity |
String |
可选 |
MSBuild输出详情。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
PakFile
根据一组给定文件创建PAK文件。
Files |
File Spec |
必需 |
要添加到pak文件的文件、通配符和标记集列表,以";"字符分隔。 |
Output |
FileReference |
必需 |
要输出的PAK文件。 |
ResponseFile |
FileReference |
可选 |
响应文件的路径,其中包含要添加到pak文件的一列文件——而不是单独指定。 |
RebaseDir |
HashSet`1 |
可选 |
重新作为文件相对基础目录的目录。如果指定,列出目录下面的最短路径将用于每个文件。 |
Order |
FileReference |
可选 |
指定文件顺序的脚本。 |
Sign |
FileReference |
可选 |
该pak文件的加密密钥。 |
Compress |
Boolean |
可选 |
是否压缩文件。 |
Arguments |
String |
可选 |
要传递到 UnrealPak 的其他参数。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Rename
重命名一个文件或一组文件。
Files |
File Spec |
必需 |
要重命名的文件。 |
From |
String |
可选 |
当前文件名或要匹配的模式(如,*.txt)。不应包含任何路径分隔符。 |
To |
String |
必需 |
文件的新名称。不应包含任何路径分隔符。 |
Tag |
Tag List |
可选 |
要对重命名后的文件应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
SanitizeReceipt
该任务通过从`*.target`文件进行读取来标记构建产品和/或运行时依赖项。
Files |
File Spec |
必需 |
要读取的接受文件(*.target)集,包含通配符和标记名称,以分号分隔。 |
EngineDir |
DirectoryReference |
可选 |
引擎文件夹的路径,用于在接收文件中扩展$(EngineDir)属性。默认为当前工作空间的引擎目录。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
SetVersion
使用给定版本信息更新本地版本文件(
Engine/Source/Runtime/Launch/Resources/Version.h
、
Engine/Build/Build.version`和`Engine/Source/Programs/DotNETCommon/Metadata.cs
)。
Change |
Int32 |
必需 |
要在版本文件中设置的更改列表。 |
CompatibleChange |
Int32 |
可选 |
要在版本文件中设置的引擎兼容更改列表。 |
Branch |
String |
必需 |
分支字符串。 |
Build |
String |
可选 |
构建版本字符串。 |
Licensee |
Boolean |
可选 |
是否将IS_LICENSEE_VERSION标志设置为true。 |
Promoted |
Boolean |
可选 |
是否将ENGINE_IS_PROMOTED_BUILD标志设置为true。 |
SkipWrite |
Boolean |
可选 |
如果设置,不会真的写入文件,而是返回将要更新的版本文件。用于本地构建。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Sign
用已安装证书对一组可执行文件签名。
Files |
File Spec |
必需 |
以分号分隔的指定文件列表(如 .cpp;Engine/.../ .bat)或目标集名称。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Spawn
产生外部可执行文件并等待编译。
Exe |
String |
必需 |
要产生的可执行文件。 |
Arguments |
String |
可选 |
新创建的进程的参数。 |
ErrorLevel |
Int32 |
可选 |
被视为错误的最小出口代码。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Stage
将构建接收中列出的文件暂存到输出目录。
Project |
FileReference |
可选 |
该目标所属的项目。 |
Target |
String |
必需 |
要暂存的目标的名称。 |
Platform |
UnrealTargetPlatform |
必需 |
要暂存的平台。 |
Configuration |
UnrealTargetConfiguration |
必需 |
要暂存的配置。 |
Architecture |
String |
可选 |
要暂存的架构。 |
ToDir |
DirectoryReference |
必需 |
接收文件应该暂存到的目录。 |
Overwrite |
Boolean |
可选 |
是否覆盖现有文件。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Strip
从一组文件分离调试信息。
Platform |
UnrealTargetPlatform |
必需 |
用于分离二进制的平台工具链。 |
BaseDir |
DirectoryReference |
可选 |
从中查找文件的目录。 |
Files |
File Spec |
必需 |
以分号分隔的指定文件列表(如Engine/.../*.pdb)或目标集名称。 |
OutputDir |
DirectoryReference |
可选 |
分隔文件的输出目录。默认为输入路径(覆盖输入文件)。 |
Tag |
Tag List |
可选 |
为构建该任务的产品而应用的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Submit
创建一个新的更改列表,并向Perforce流提交一组文件。
Description |
String |
必需 |
已提交更改列表的描述。 |
Files |
File Spec |
必需 |
要提交的文件。 |
FileType |
String |
可选 |
已提交文件的Perforce文件类型(如binary+FS32)。 |
Workspace |
String |
可选 |
工作空间名称。如果指定,则使用给定流和根目录来创建新的工作空间以用于提交文件。如果不指定,则将使用当前工作空间。 |
Stream |
String |
可选 |
工作空间的流;默认为当前流。除非同时指定了Workspace属性,否则忽略。 |
RootDir |
DirectoryReference |
可选 |
流的根目录——如果不指定,默认为当前根目录。 |
RevertUnchanged |
Boolean |
可选 |
是否先还原未更改的文件,然后再尝试提交。 |
Force |
Boolean |
可选 |
强制进行提交——即使需要解析也是如此(始终接受当前版本)。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
SymStore
这是从一组文件分离符号的任务
Platform |
UnrealTargetPlatform |
必需 |
用于处理符号文件的平台工具链。 |
Files |
String |
必需 |
输出文件的列表。将从该列表中抽取PDB。 |
StoreDir |
String |
必需 |
压缩符号的输出目录。 |
Product |
String |
必需 |
符号存储记录的产品名称。 |
BuildVersion |
String |
可选 |
与这些符号关联的构建版本。用于通过将该版本与构建共享中的目录名称匹配以在AgeStore实现清理。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Tag
对一组给定文件应用标记。通过列举标记和通过"Files"参数指定的文件找到文件列表。从该列表,任何没有被"Files"参数匹配的文件都将被移除,后跟"Except"参数匹配的任何文件。
BaseDir |
DirectoryReference |
可选 |
设置基本目录以用于解析相对路径和模式。如果设置,则任何绝对模式(例如/Engine/Build/...)将相对于该路径。如果不设置,则视为真正的绝对路径。 |
Files |
File Spec |
可选 |
要从中工作的文件集,包括通配符和标记名称,以分号分隔。如果设置了BaseDir,则解析为相对于BaseDir,否则相对于分支根目录。 |
FileLists |
File Spec |
可选 |
要从中添加额外文件的文本文件集。每个文件列表都应在每一行有一个文件。 |
Filter |
File Spec |
可选 |
用于过滤文件列表的模式,包括标记名称或通配符。许多包含适用于基本目录(如果设置)的模式。如果不指定,默认为所有文件。 |
Except |
File Spec |
可选 |
要从匹配列表中排除的模式集。许多包含适用于基本目录的模式的标记名称。 |
With |
Tag List |
必需 |
要应用的标记名称。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
TagReceipt
该任务通过从`*.target`文件进行读取来标记构建产品和/或运行时依赖项。
Files |
File Spec |
必需 |
要读取的接受文件(*.target)集,包含通配符和标记名称,以分号分隔。 |
EngineDir |
DirectoryReference |
可选 |
引擎文件夹的路径,用于在接收文件中扩展$(EngineDir)属性。默认为当前工作空间的引擎目录。 |
ProjectDir |
DirectoryReference |
可选 |
项目文件夹的路径,用于在接收文件中扩展$(ProjectDir)属性。默认为当前工作空间的引擎目录。已弃用。 |
BuildProducts |
Boolean |
可选 |
是否标记接收中列出的构建产品。 |
BuildProductType |
String |
可选 |
要标记的构建产品类型(请参阅TargetReceipt.cs - UnrealBuildTool.BuildProductType以了解有效值)。 |
RuntimeDependencies |
Boolean |
可选 |
是否标记接收中列出的运行时依赖项。 |
StagedFileType |
String |
可选 |
要标记的运行时依赖项类型(请参阅TargetReceipt.cs - UnrealBuildTool.StagedFileType以了解有效值)。 |
With |
Tag List |
必需 |
要应用的标记名称。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Unzip
从zip归档解压文件。
ZipFile |
File Spec |
必需 |
要解压的zip文件的路径。 |
ToDir |
DirectoryReference |
必需 |
解压文件的输出目录。 |
Tag |
Tag List |
可选 |
要应用于解压文件的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
WriteTextFile
将文本写入一个文件。
File |
FileReference |
必需 |
要写入的文件路径。 |
Append |
Boolean |
可选 |
可选,是否要添加到文件,而不是覆盖文件内容。 |
Text |
String |
可选 |
要写入文件的文本。 |
Files |
File Spec |
可选 |
如指定,会在给出的信息后面打印给出的文件列表。 |
Tag |
Tag List |
可选 |
要应用于本任务的构建产品的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |
Zip
将文件压缩为zip归档。
FromDir |
DirectoryReference |
必需 |
从中读取压缩文件的目录。 |
Files |
File Spec |
可选 |
以分号分隔的指定文件列表(如 .cpp;Engine/.../ .bat)或目标集名称。从FromDir获取的相对路径。 |
ZipFile |
FileReference |
必需 |
要创建的zip文件。 |
Tag |
Tag List |
可选 |
要应用于已创建zip文件的标记。 |
If |
Condition |
可选 |
是否执行该任务。如果该值评估为false,则被忽略。 |