BuildGraph Script Elements

BuildGraph scripts are written in XML. This document covers the types of data found within BuildGraph scripts, as well as their overall structure.

Elements

Elements describe the data that they contain, making them one of the basic building blocks of BuildGraph scripts. The following tables contain items that are provided as metadata, which are exported when running on the build system. Although they're not used directly by BuildGraph when executing tasks locally, they're tagged with [META].

Graph Structure

A BuildGraph script is typically defined with the following elements:

  • <Node>

  • <Aggregate>

  • <Agent>

  • <Trigger>

Node

<Node> is the smallest unit of execution in BuildGraph, having a set of inputs and outputs. Each <Node> consists of a sequence of tasks that are executed in order.

Attribute

Type

Required?

Description

Name

Name

Required

Name of the node.

Requires

Target List

Optional

List of nodes, aggregates, or tagged file sets produced by other nodes that this node requires to execute, separated by semicolons.

Produces

Tag List

Optional

Tagged file sets that this node makes available to other nodes, separated by semicolons.

After

Target List

Optional

List of nodes that this node should run after, if they are part of the current target (ignored if they are not). Separated by semicolons.

NotifyOnWarnings

Boolean

Optional

If false, this node will not produce notifications on warnings. Only used by build systems. Defaults to true. [META]

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Aggregate

<Aggregate> declares a named aggregate that can be used as a synonym for a set of other nodes (or produced tag sets).

Attribute

Type

Required?

Description

Name

Name

Required

Name of the aggregate.

Requires

Target List

Required

List of dependencies for this aggregate. May be nodes, tagged file sets, or agent groups.

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Agent

<Agent> defines requirements for an agent on nodes that will be executed in sequence (without cleaning intermediate directories). <Agent> requirements are ignored when building locally, but must be specified.

Attribute

Type

Required?

Description

Name

Name

Required

Name of the group.

Type

Identifier List

Optional

Type of agent to run on. The meaning of this string is inferred by the host build system; it does not have any intrinsic meaning. [META]

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Trigger

<Trigger> serves as a container for portions of the graph that should only be executed with explicit user intervention. To execute nodes behind a trigger, pass -Trigger=<Name> to the command line.

Attribute

Type

Required?

Description

Name

Name

Required

Name of the trigger.

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Property Manipulation

BuildGraph properties can be modified with the following elements:

  • <Property>

  • <Option>

  • <EnvVar>

Property

<Property> sets the value of a property. If a property in an outer scope has already been declared with the same name, <Property> overwrites it. Otherwise, a new property is declared at the current scope.

Attribute

Type

Required?

Description

Name

Name

Required

Name of the property to set.

Value

String

Required

New value for the property.

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Option

<Option> defines a user option that can be set from the command line. <Option> may only appear at a global scope.

Attribute

Type

Required?

Description

Name

Name

Required

Name of the option (and property) to initialize with the option's value.

Description

String

Required

Description for the option to display when running BuildGraph with the -ListOnly argument.

Restrict

Regex

Optional

Regex that matches valid values for this option (eg. [a-zA-Z]+, true | false).

DefaultValue

String

Required

Default value for the option if the user does not set it explicitly.

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

EnvVar

<EnvVar> declares a property to contain the contents of an environment variable (or an empty string if it's not set). <EnvVar> may only appear at a global scope.

Attribute

Type

Required?

Description

Name

Name

Required

Name of the environment variable to introduce as a property.

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Flow Control

You can control the flow of your BuildGraph scripts with the following elements:

  • <Include>

  • <Do>

  • <Switch>

  • <ForEach>

Include

<Include> processes the contents of another BuildGraph script as if it appeared within this file. <Include> may only appear at a global scope.

Attribute

Type

Required?

Description

Script

String

Required

Path to the script you wan to include (relative to the current script).

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Do

<Do> groups a sequence of elements and only processes them if a condition evaluates as true.

Attribute

Type

Required?

Description

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Switch

<Switch> is similar to a C switch statement because it evaluates the conditions on a sequence of branches, processing the first statement with a condition that evaluates as true.

Example <Switch> statement:

<Switch>
    <Case If=X>
        <Elements go here>
    </Case>
    <Case If=Y>
        <Elements go here>
    </Case>
    <Default>
        <Elements go here>
    </Default>
</Switch>

Attribute

Type

Required?

Description

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

ForEach

<ForEach> expands the body of the element with a given property assigned to each item in a list that is separated by semicolons.

Example <ForEach> statement:

<ForEach Name="Counter" Values="1;2;3;4;5">
    <Log Message="Counter=$(Counter)"/>
</ForEach>

Attribute

Type

Required?

Description

Name

Name

Required

Property to assign to each value in the list.

Values

String List

Required

List of values that are separated by semicolons.

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Diagnostics

You can perform diagnostics on your BuildGraph scripts with the following elements:

  • <Warning>

  • <Error>

Warning

<Warning> outputs a warning message before executing the graph. <Warning> may be included in nodes, agents, triggers, or at global scope. <Warning> will only provide an output if it's still part of the graph after it has been trimmed down to the target being executed.

Attribute

Type

Required?

Description

Message

String

Required

Text to be printed to the log.

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Error

<Error>outputs an error message. <Error> may be included in nodes, agents, triggers, or at global scope. <Error> will only provide an output if it's still part of the graph after it has been trimmed down to the target being executed.

Attribute

Type

Required?

Description

Message

String

Required

Text to be printed to the log.

If

Condition

Optional

Condition to be evaluated. The element is ignored unless the condition evaluates to true.

Tasks

Typically, project-specific utility scripts are implemented as AutomationTool BuildCommand classes. There are times, however, when you'll want to automate custom tasks for your project. This is where BuildGraph can help. BuildGraph can be extended with any number of tasks, enabling you to customize your build automation tasks in ways that suit your specific needs. The following section goes over ways of creating custom tasks using BuildGraph, including a listing of predefined tasks that'll give you a great starting point for creating custom tasks.

Custom Tasks

To create a new custom task, implement a class derived from the CustomTask class and apply the [TaskElement] attribute to it. The TaskElement constructor takes two arguments; the name of the XML element that it's represented by, and the type of class containing its parameters (which is passed to the constructor at load time).

If you want to read parameter class fields from an XML file, attach the [TaskParameter] attribute to the task. Attaching the TaskParameter attribute indicates if the parameter is required or optional, including additional validation that should be applied to the argument.

Predefined Tasks

If you'd like to have a starting point for creating tasks, we're providing a variety of predefined tasks as templates for you to work from. If you're looking for a simple predefined task to start from, we recommend using LogTask as a good starting point. If you want to keep up with our latest improvements to BuildGraph; bookmark this page, because the following list of predefined tasks will be updated periodically.

AgeStore

Task which strips symbols from a set of files. This task is named after the AGESTORE utility that comes with the Microsoft debugger tools SDK, but is actually a separate implementation. The main difference is that it uses the last modified time rather than last access time to determine which files to delete.

Attribute Type Usage Description
Platform UnrealTargetPlatform Required The target platform to age symbols for.
StoreDir String Required The symbol server directory.
Days Int32 Required Number of days worth of symbols to keep.
Filter String Optional A substring to match in directory file names before deleting symbols. This allows the "age store" task to avoid deleting symbols from other builds in the case where multiple builds share the same symbol server. Specific use of the filter value is determined by the symbol server structure defined by the platform tool chain.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Command

Invokes an AutomationTool child process to run the given command.

Attribute Type Usage Description
Name String Required The command name to execute.
Arguments String Optional Arguments to be passed to the command.
MergeTelemetryWithPrefix String Optional If non-null, instructs telemetry from the command to be merged into the telemetry for this UAT instance with the given prefix. May be an empty (non-null) string.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Commandlet

Spawns the editor to run a commandlet.

Attribute Type Usage Description
Name String Required The commandlet name to execute.
Project File Spec Optional The project to run the editor with.
Arguments String Optional Arguments to be passed to the commandlet.
EditorExe File Name Optional The editor executable to use. Defaults to the development UE4Editor executable for the current platform.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Compile

Compiles a target with UnrealBuildTool.

Attribute Type Usage Description
Target String Required The target to compile.
Configuration UnrealTargetConfiguration Required The configuration to compile.
Platform UnrealTargetPlatform Required The platform to compile for.
Arguments String Optional Additional arguments for UnrealBuildTool.
AllowXGE Boolean Optional Whether to allow using XGE for compilation.
AllowParallelExecutor Boolean Optional Whether to allow using the parallel executor for this compile.
Clean Nullable`1 Optional Whether to allow cleaning this target. If unspecified, targets are cleaned if the -Clean argument passed on the command line.
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Cook

Cook a selection of maps for a certain platform

Attribute Type Usage Description
Project String Required Project file to be cooked.
Platform String Required The cook platform to target (eg. WindowsNoEditor).
Maps String Optional List of maps to be cooked, separated by '+' characters.
Versioned Boolean Optional Additional arguments to be passed to the cooker.
Arguments String Optional Additional arguments to be passed to the cooker.
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Copy

Copies files from one directory to another.

Attribute Type Usage Description
Files File Spec Optional Filter to be applied to the list of input files. Optional.
From File Spec Required The pattern(s) to copy from (eg. Engine/*.txt)
To File Spec Required The directory or to copy to.
Overwrite Boolean Optional Whether or not to overwrite existing files.
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

CsCompile

Compiles C# project files, and their dependencies.

Attribute Type Usage Description
Project String Required The C# project file to be compile. More than one project file can be specified by separating with semicolons.
Configuration String Optional The configuration to compile.
Platform String Optional The platform to compile.
Target String Optional The target to build.
Arguments String Optional Additional options to pass to the compiler.
EnumerateOnly Boolean Optional Only enumerate build products; do not actually compile the projects.
Tag Tag List Optional Tag to be applied to build products of this task.
TagReferences Tag List Optional Tag to be applied to any non-private references the projects have (such as those that are external and not copied into the output dir).
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Delete

Delete a set of files.

Attribute Type Usage Description
Files File Spec Required List of file specifications separated by semicolons (eg. *.cpp;Engine/.../*.bat), or the name of a tag set.
DeleteEmptyDirectories Boolean Optional Whether to delete empty directories after deleting the files. Defaults to true.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Log

Print a message (and other optional diagnostic information) to the output log

Attribute Type Usage Description
Message String Optional Message to print out.
Files File Spec Optional If specified, causes the given list of files to be printed after the given message.
IncludeContents Boolean Optional If specified, causes the contents of the given files to be printed out.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Move

Moves files from one directory to another.

Attribute Type Usage Description
Files File Spec Optional Filter to be applied to the list of input files. Optional.
From File Spec Required The pattern(s) to copy from (eg. Engine/*.txt).
To File Spec Required The directory or to copy to.
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

MsBuild

This executes MsBuild.

Attribute Type Usage Description
Project String Required The C# project file to be compile. More than one project file can be specified by separating with semicolons.
Configuration String Optional The configuration to compile.
Platform String Optional The platform to compile.
Arguments String Optional Additional options to pass to the compiler.
Verbosity String Optional The MSBuild output verbosity.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

PakFile

Creates a PAK file from a given set of files.

Attribute Type Usage Description
Files File Spec Required List of files, wildcards and tag sets to add to the pak file, separated by ';' characters.
Output File Name Required PAK file to output.
ResponseFile File Name Optional Path to a Response File that contains a list of files to add to the pak file, instead of specifying them individually.
RebaseDir Directory Name Optional Directories to rebase the files relative to. If specified, the shortest path under a listed directory will be used for each file.
Order File Name Optional Script which gives the order of files.
Sign String Optional Encryption keys for this pak file.
Compress Boolean Optional Whether to compress files.
Arguments String Optional Additional arguments to be passed to UnrealPak.
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Rename

Renames a file, or group of files.

Attribute Type Usage Description
Files File Spec Required The file or files to rename.
From Directory Name Optional The current file name, or pattern to match (eg. *.txt). Should not include any path separators.
To Directory Name Required The new name for the file(s). Should not include any path separators.
Tag Tag List Optional Tag to be applied to the renamed files.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

SetVersion

Updates the local version files (Engine/Source/Runtime/Launch/Resources/Version.h, Engine/Build/Build.version, and Engine/Source/Programs/DotNETCommon/Metadata.cs) with the given version information.

Attribute Type Usage Description
Change Int32 Required The changelist to set in the version files.
CompatibleChange Int32 Optional The engine compatible changelist to set in the version files.
Branch String Required The branch string.
Build String Optional The build version string.
Licensee Boolean Optional Whether to set the IS_LICENSEE_VERSION flag to true.
Promoted Boolean Optional Whether to set the ENGINE_IS_PROMOTED_BUILD flag to true.
SkipWrite Boolean Optional If set, don't actually write to the files - just return the version files that would be updated. Useful for local builds.
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Sign

Signs a set of executable files with an installed certificate.

Attribute Type Usage Description
Files File Spec Required List of file specifications separated by semicolons (eg. *.cpp;Engine/.../*.bat), or the name of a tag set.
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Spawn

Spawns an external executable and waits for it to complete.

Attribute Type Usage Description
Exe File Name Required Executable to spawn.
Arguments String Optional Arguments for the newly created process.
ErrorLevel Int32 Optional The minimum exit code which is treated as an error.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Stage

Stages files listed in a build receipt to an output directory.

Attribute Type Usage Description
Project File Name Optional The project that this target belongs to.
Target String Required Name of the target to stage.
Platform UnrealTargetPlatform Required Platform to stage.
Configuration UnrealTargetConfiguration Required Configuration to be staged.
Architecture String Optional Architecture to be staged.
ToDir String Required Directory the receipt files should be staged to.
Overwrite Boolean Optional Whether to overwrite existing files.
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Strip

Strips debugging information from a set of files.

Attribute Type Usage Description
Platform UnrealTargetPlatform Required The platform toolchain to strip binaries.
BaseDir Directory Name Optional The directory to find files in.
Files File Spec Required List of file specifications separated by semicolons (eg. Engine/.../*.pdb), or the name of a tag set.
OutputDir Directory Name Optional Output directory for the stripped files. Defaults to the input path (overwriting the input files).
Tag Tag List Optional Tag to be applied to build products of this task.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Submit

Creates a new changelist and submits a set of files to a Perforce stream.

Attribute Type Usage Description
Description String Required The description for the submitted changelist.
Files File Spec Required The files to submit.
FileType String Optional The Perforce file type for the submitted files (eg. binary+FS32).
Workspace String Optional The workspace name. If specified, a new workspace will be created using the given stream and root directory to submit the files. If not, the current workspace will be used.
Stream String Optional The stream for the workspace; defaults to the current stream. Ignored unless If the Workspace attribute is also specified.
RootDir Directory Name Optional Root directory for the stream. If not specified, defaults to the current root directory.
RevertUnchanged Boolean Optional Whether to revert unchanged files before attempting to submit.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

SymStore

Task which strips symbols from a set of files

Attribute Type Usage Description
Platform UnrealTargetPlatform Required The platform toolchain required to handle symbol files.
Files String Required List of output files. PDBs will be extracted from this list.
StoreDir String Required Output directory for the compressed symbols.
Product String Required Name of the product for the symbol store records.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Tag

Applies a tag to a given set of files. The list of files is found by enumerating the tags and file specifications given by the 'Files' parameter. From this list, any files not matched by the 'Filter' parameter are removed, followed by any files matched by the 'Except' parameter.

Attribute Type Usage Description
BaseDir Directory Name Optional Set the base directory to resolve relative paths and patterns against. If set, any absolute patterns (for example /Engine/Build/...) are taken to be relative to this path. If not, they are taken to be truly absolute.
Files File Spec Optional Set of files to work from, including wildcards and tag names, separated by semicolons. Resolved relative to BaseDir if set, otherwise to the branch root directory.
Filter File Spec Optional Patterns to filter the list of files by, including tag names or wildcards. May include patterns that apply to the base directory if set. Defaults to all files if not specified.
FileLists File Spec Optional Set of text files to add additional files from. Each file list should have on file per line.
Except File Spec Optional Set of patterns to exclude from the matched list. May include tag names of patterns that apply to the base directory.
With Tag List Required Name of the tag to apply.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

TagReceipt

Task which tags build products and/or runtime dependencies by reading from *.target files.

Attribute Type Usage Description
Files File Spec Required Set of receipt files (*.target) to read, including wildcards and tag names, separated by semicolons.
EngineDir Directory Name Optional Path to the Engine folder, used to expand $(EngineDir) properties in receipt files. Defaults to the Engine directory for the current workspace.
ProjectDir Directory Name Optional Path to the project folder, used to expand $(ProjectDir) properties in receipt files. Defaults to the Engine directory for the current workspace.
BuildProducts Boolean Optional Whether to tag the Build Products listed in receipts.
BuildProductType String Optional Which type of Build Products to tag (See TargetReceipt.cs - UnrealBuildTool.BuildProductType for valid values).
RuntimeDependencies Boolean Optional Whether to tag the Runtime Dependencies listed in receipts.
StagedFileType String Optional Which type of Runtime Dependencies to tag (See TargetReceipt.cs - UnrealBuildTool.StagedFileType for valid values).
With Tag List Required Name of the tag to apply.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Unzip

Extract files from a zip archive.

Attribute Type Usage Description
ZipFile File Name Required Path to the zip file to extract.
ToDir Directory Name Required Output directory for the extracted files.
Tag Tag List Optional Tag to be applied to the extracted files.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.

Zip

Compresses files into a zip archive.

Attribute Type Usage Description
FromDir Directory Name Required The directory to read compressed files from.
Files File Spec Optional List of file specifications separated by semicolons (eg. *.cpp;Engine/.../*.bat), or the name of a tag set. Relative paths are taken from FromDir.
ZipFile File Name Required The zip file to create.
Tag Tag List Optional Tag to be applied to the created zip file.
If Condition Optional Whether to execute this task. It is ignored if this condition evaluates to false.