Choose your operating system:
Windows
macOS
Linux
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.
BuildCookRun is a powerful and commonly used command for packaging tasks. For more information, read the overview that covers Build Operations.
AgeStore
Task that 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.
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. |
BuildDir |
String |
Optional |
The root of the build directory to check for existing buildversion named directories. |
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 toolchain. |
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.
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.
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 |
FileReference |
Optional |
The editor executable to use. Defaults to the development UE4Editor executable for the current platform. |
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. |
Compile
Compiles a target with UnrealBuildTool.
Target |
String |
Required |
The target to compile. |
Configuration |
UnrealTargetConfiguration |
Required |
The configuration to compile. |
Platform |
UnrealTargetPlatform |
Required |
The platform to compile for. |
Project |
String |
Optional |
The project to compile with. |
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 is 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
Project |
String |
Required |
Project file to be cooked. |
Platform |
String |
Required |
The cook platform to target (for example, 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.
Files |
File Spec |
Optional |
Optional filter to be applied to the list of input files. |
From |
File Spec |
Required |
The pattern(s) to copy from (for example, Engine/*.txt). |
To |
File Spec |
Required |
The directory 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.
Project |
String |
Required |
The C# project file to compile. Using semicolons, more than one project file can be specified. |
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. (for example, those that are external and not copied into the output directory). |
If |
Condition |
Optional |
Whether to execute this task. It is ignored if this condition evaluates to false. |
Delete
Delete a set of files.
Files |
File Spec |
Required |
List of file specifications separated by semicolons (for example, .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.
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. |
ModifyConfig
Modifies a config file
File |
File Spec |
Required |
Path to the config file |
Section |
String |
Required |
The section name to modify |
Key |
String |
Required |
The property name to set |
Value |
String |
Required |
The property value to set |
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. |
Move
Moves files from one directory to another.
Files |
File Spec |
Optional |
Optional filter to be applied to the list of input files. |
From |
File Spec |
Required |
The pattern(s) to copy from (for example, Engine/*.txt). |
To |
File Spec |
Required |
The directory 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
Executes MsBuild
Project |
String |
Required |
The C# project file to compile. Using semicolons, more than one project file can be specified. |
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.
Files |
File Spec |
Required |
List of files, wildcards, and tag sets to add to the pak file, separated by ';' characters. |
Output |
FileReference |
Required |
PAK file to output. |
ResponseFile |
FileReference |
Optional |
Path to a Response File that contains a list of files to add to the pak file -- instead of specifying them individually. |
RebaseDir |
HashSet`1 |
Optional |
Directories to rebase the files relative to. If specified, the shortest path under a listed directory will be used for each file. |
Order |
FileReference |
Optional |
Script that gives the order of files. |
Sign |
FileReference |
Optional |
Encryption keys for this pak file. |
Compress |
Boolean |
Optional |
Whether to compress files. |
Arguments |
String |
Optional |
Additional arguments to pass 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.
Files |
File Spec |
Required |
The file or files to rename. |
From |
String |
Optional |
The current file name, or pattern to match (for example, *.txt). Should not include any path separators. |
To |
String |
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. |
SanitizeReceipt
Task that tags build products and/or runtime dependencies by reading from *.target files.
Files |
File Spec |
Required |
Set of receipt files (*.target) to read, including wildcards and tag names, separated by semicolons. |
EngineDir |
DirectoryReference |
Optional |
Path to the Engine folder, used to expand $(EngineDir) properties in receipt files. Defaults to the Engine directory for the current workspace. |
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.
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, do not 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.
Files |
File Spec |
Required |
List of file specifications separated by semicolons (for example, .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.
Exe |
String |
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.
Project |
FileReference |
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 |
DirectoryReference |
Required |
Directory that 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.
Platform |
UnrealTargetPlatform |
Required |
The platform toolchain to strip binaries. |
BaseDir |
DirectoryReference |
Optional |
The directory to find files in. |
Files |
File Spec |
Required |
List of file specifications separated by semicolons (for example, Engine/.../*.pdb), or the name of a tag set. |
OutputDir |
DirectoryReference |
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.
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 (for example, 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 the Workspace attribute is also specified. |
RootDir |
DirectoryReference |
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. |
Force |
Boolean |
Optional |
Force the submit to happen -- even if a resolve is needed (always accept current version). |
If |
Condition |
Optional |
Whether to execute this task. It is ignored if this condition evaluates to false. |
SymStore
Task that strips symbols from a set of files.
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. |
BuildVersion |
String |
Optional |
BuildVersion associated with these symbols. Used for clean-up in AgeStore by matching this version against a directory name in a build share. |
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.
BaseDir |
DirectoryReference |
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. If set, resolved relative to BaseDir, otherwise resolved to the branch root directory. |
FileLists |
File Spec |
Optional |
Set of text files to add additional files from. Each file list should have one file per line. |
Filter |
File Spec |
Optional |
Patterns to filter the list of files by, including tag names or wildcards. If set, may include patterns that apply to the base directory. If not specified, defaults to all files. |
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 that tags build products and/or runtime dependencies by reading from *.target files.
Files |
File Spec |
Required |
Set of receipt files (*.target) to read, including wildcards and tag names, separated by semicolons. |
EngineDir |
DirectoryReference |
Optional |
Path to the Engine folder, used to expand $(EngineDir) properties in receipt files. Defaults to the Engine directory for the current workspace. |
ProjectDir |
DirectoryReference |
Optional |
Path to the project folder, used to expand $(ProjectDir) properties in receipt files. Defaults to the Engine directory for the current workspace -- DEPRECATED. |
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.
ZipFile |
File Spec |
Required |
Path to the zip file to extract. |
ToDir |
DirectoryReference |
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. |
WriteTextFile
Writes text to a file.
File |
FileReference |
Required |
Path to the file to write. |
Append |
Boolean |
Optional |
Optional, whether or not to append to the file rather than overwrite. |
Text |
String |
Optional |
The text to write to the file. |
Files |
File Spec |
Optional |
If specified, causes the given list of files to be printed after the given message. |
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. |
Zip
Compresses files into a zip archive.
FromDir |
DirectoryReference |
Required |
The directory to read compressed files from. |
Files |
File Spec |
Optional |
List of file specifications separated by semicolons (for example, .cpp;Engine/.../.bat), or the name of a tag set. Relative paths are taken from FromDir. |
ZipFile |
FileReference |
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. |