EngineCustomBuilds

EngineCustomBuilds

#Overview

name: EngineCustomBuilds

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 4 C++ source files. Also referenced in 1 C# build file meaning it may affect the build system logic.

#Summary

#Usage in the C++ source code

The purpose of EngineCustomBuilds is to store a collection of custom build configurations for the Unreal Engine. This variable is part of the project packaging settings and is used to define and manage custom build processes for the engine.

EngineCustomBuilds is primarily used by the Unreal Engine’s packaging and build system, specifically within the TurnkeySupport module. This module is responsible for creating and managing build menus and options in the Unreal Editor.

The value of this variable is set in the project’s configuration files, as indicated by the UPROPERTY(config) attribute in the UProjectPackagingSettings class declaration.

EngineCustomBuilds interacts with ProjectCustomBuilds, another similar variable that stores custom build configurations specific to the current project. Both variables are used in conjunction to populate build menus and options for different platforms and devices.

Developers should be aware that:

  1. EngineCustomBuilds is an array of FProjectBuildSettings, allowing multiple custom build configurations.
  2. These custom builds appear in the editor’s build menus, providing additional options for packaging and deployment.
  3. The custom builds can be targeted for specific platforms or devices.

Best practices when using this variable include:

  1. Clearly naming and documenting each custom build configuration for easy identification.
  2. Ensuring that custom build configurations are compatible with the target platforms and devices.
  3. Regularly reviewing and updating custom builds to maintain compatibility with engine updates.
  4. Using project-specific custom builds (ProjectCustomBuilds) for project-specific requirements, and EngineCustomBuilds for more general or reusable configurations.
  5. Testing custom build configurations thoroughly to ensure they produce the expected results.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseGame.ini:87, section: [/Script/UnrealEd.ProjectPackagingSettings]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Developer/DeveloperToolSettings/Classes/Settings/ProjectPackagingSettings.h:638

Scope (from outer to inner):

file
class        class UProjectPackagingSettings : public UObject

Source code excerpt:

	 */
	UPROPERTY(config)
	TArray<FProjectBuildSettings> EngineCustomBuilds;

	/**
	* The type name of a CustomStageCopyHandler subclass to instanciate during the copy build to staging directory step. See SetupCustomStageCopyHandler() in CopyBuildToStagingDirectory.Automation.cs and CustomStageCopyHandler.cs
	*/
	UPROPERTY(config)
	FString CustomStageCopyHandler;

#Loc: <Workspace>/Engine/Source/Editor/TurnkeySupport/Private/TurnkeySupportModule.cpp:1214

Scope (from outer to inner):

file
function     static void MakeTurnkeyPlatformMenu

Source code excerpt:

		FText ToolTipFormat = LOCTEXT("TurnkeyTooltip_EngineCustomBuild", "Execute the '{BuildName}' command.\n{BuildHelp}\n--\nThis runs the following command:\nRunUAT {CommandLine}");
#endif
		MakeCustomBuildMenuEntries(Section, PackagingSettings->EngineCustomBuilds, IniPlatformName, FString(), FString(), ToolTipFormat);
		
#if ALLOW_CONTROL_TO_COPY_COMMANDLINE
		ToolTipFormat = LOCTEXT("TurnkeyTooltip_ProjectCustomBuild_WithCopy", "Execute this project's custom '{BuildName}' command.\n{BuildHelp}\n--\nThis runs the following command:\nRunUAT {CommandLine}\nHold Control to copy the final BuildCookRun commandline to the clipboard.\nThis custom command comes from Project Settings.");
#else
		ToolTipFormat = LOCTEXT("TurnkeyTooltip_ProjectCustomBuild", "Execute this project's custom '{BuildName}' command.\n{BuildHelp}\n--\nThis runs the following command:\nRunUAT {CommandLine}\nThis custom command comes from Project Settings.");
#endif

#Loc: <Workspace>/Engine/Source/Editor/TurnkeySupport/Private/TurnkeySupportModule.cpp:1394

Scope (from outer to inner):

file
function     static void MakeTurnkeyPlatformMenu
lambda-function

Source code excerpt:

				FNewToolMenuDelegate::CreateLambda([IniPlatformName, DeviceName, DeviceId, PackagingSettings](UToolMenu* SubToolMenu)
				{
					if (HasBuildForDeviceOrNot(PackagingSettings->EngineCustomBuilds, true) || HasBuildForDeviceOrNot(PackagingSettings->ProjectCustomBuilds, true))
					{
						FToolMenuSection& CustomBuildSection = SubToolMenu->AddSection("DeviceCustomBuilds", LOCTEXT("TurnkeySection_DeviceCustomBuilds", "Builds For Devices"));

						// these ToolTipFormats will be formatted inside the MakeCustomBuildMenuEntries function with some named args
						// the empty strings passed in is the deviceId, which means to show builds that don't contain DeviceId components
#if ALLOW_CONTROL_TO_COPY_COMMANDLINE

#Loc: <Workspace>/Engine/Source/Editor/TurnkeySupport/Private/TurnkeySupportModule.cpp:1405

Scope (from outer to inner):

file
function     static void MakeTurnkeyPlatformMenu
lambda-function

Source code excerpt:

						FText ToolTipFormat = LOCTEXT("TurnkeyTooltip_EngineCustomBuildDevice", "Execute the '{BuildName}' command on {DeviceName}.\n{BuildHelp}\n--\nThis runs the following command:\nRunUAT {CommandLine}");
#endif
						MakeCustomBuildMenuEntries(CustomBuildSection, PackagingSettings->EngineCustomBuilds, IniPlatformName, DeviceId, DeviceName, ToolTipFormat);

#if ALLOW_CONTROL_TO_COPY_COMMANDLINE
						ToolTipFormat = LOCTEXT("TurnkeyTooltip_ProjectCustomBuildDevice", "Execute this project's custom '{BuildName}' command on {DeviceName}.\n{BuildHelp}\n--\nThis runs the following command:\nRunUAT {CommandLine}\nHold Control to copy the final BuildCookRun commandline to the clipboard.\nThis custom command comes from Project Settings.");
#else
						ToolTipFormat = LOCTEXT("TurnkeyTooltip_ProjectCustomBuild_WithCopyDevice", "Execute this project's custom '{BuildName}' command on {DeviceName}.\n{BuildHelp}\n--\nThis runs the following command:\nRunUAT {CommandLine}\nThis custom command comes from Project Settings.");
#endif

#References in C# build files

This variable is referenced in the following C# build files:

Location: <Workspace>/Engine/Source/Programs/AutomationTool/Turnkey/Commands/ExecuteBuild.cs:39

				List<string> EngineBuilds;
				List<string> ProjectBuilds;
				GameConfig.GetArray("/Script/UnrealEd.ProjectPackagingSettings", "EngineCustomBuilds", out EngineBuilds);
				GameConfig.GetArray("/Script/UnrealEd.ProjectPackagingSettings", "ProjectCustomBuilds", out ProjectBuilds);

				List<string> Builds = new List<string>();
				if (EngineBuilds != null)
				{
					Builds.AddRange(EngineBuilds);