BuildGraph 스크립트 태스크 | 언리얼 엔진 4.27 문서

보통 프로젝트 전용 유틸리티 스크립트는 AutomationTool BuildCommand 클래스로 구현됩니다. 하지만 가끔은 프로젝트의 커스텀 태스크를 자동화하고 싶을 때가 있습니다. 그럴 때 BuildGraph 가 도움이 될 수 있습니다. BuildGraph 는 몇 개의 태스크로도 확장시킬 수 있어, 요구에 딱 맞도록 빌드 자동화 태스크를 커스터마이징할 수 있습니다. 여기서는 BuildGraph 를 사용하여 커스텀 태스크를 만드는 방법과 아울러, 별도의 커스텀 태스크 제작에 참고가 되는 미리정의된 태스크 목록을 포함해서 알아보도록 하겠습니다.

커스텀 태스크

커스텀 태스크를 새로 만들려면, CustomTask 클래스에서 파생된 클래스를 구현하고 [TaskElement] 어트리뷰트를 적용합니다. TaskElement 생성자는 인수를 둘 받습니다. 하나는 그것이 표현하는 XML 요소 이름, 다른 하나는 그 파라미터가 들어있는 클래스 유형입니다 (이것이 로드 시간에 생성자에 전달됩니다).

XML 파일에서 파라미터 클래스 필드를 읽으려면, 태스크에 [TaskParameter] 어트리뷰트를 붙입니다. TaskParameter 어트리뷰트를 붙이면 파라미터가 필수인지 옵션인지를 나타내며, 여기에는 인수에 적용시킬 추가 인증까지 포함됩니다.

미리정의된 태스크

별도의 태스크 제작을 위한 시작점으로, 미리 정의된 태스크를 템플릿으로 다양하게 제공하고 있으니, 여기서부터 작업을 하시면 됩니다. 미리 정의된 태스크 견본 간단한 것을 찾는 경우, LogTask 부터 시작해 보면 좋습니다. BuildGraph 최신 개선 사항 소식을 받아보시려는 경우, 이 페이지를 북마크 등록하세요. 주기적으로 미리 정의된 태스크 목록을 업데이트하겠습니다.

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.
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.

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.