ProjectCustomBuilds

ProjectCustomBuilds

#Overview

name: ProjectCustomBuilds

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 2 C# build files meaning it may affect the build system logic.

#Summary

#Usage in the C++ source code

The purpose of ProjectCustomBuilds is to define and manage custom build configurations for a specific Unreal Engine project. It allows developers to create and configure project-specific build settings that can be used during the packaging and deployment process.

This setting variable is primarily used by the Unreal Engine’s packaging and deployment systems. Based on the callsites, it is utilized in the following subsystems and modules:

  1. DeveloperToolSettings module
  2. TurnkeySupport module

The value of this variable is set in the project’s configuration files and can be edited through the Project Settings interface in the Unreal Editor. It is defined as a TArray of FProjectBuildSettings, allowing multiple custom build configurations to be specified.

ProjectCustomBuilds interacts with other variables and systems, such as:

  1. EngineCustomBuilds: Another array of custom build settings, but for engine-level configurations.
  2. The Turnkey platform menu system, which uses these custom builds to populate build options for different platforms and devices.

Developers should be aware of the following when using this variable:

  1. Custom builds defined here are project-specific and separate from engine-level custom builds.
  2. These builds can be targeted for specific devices or platforms.
  3. The custom build configurations are used to generate menu entries in the editor’s packaging and deployment interfaces.

Best practices when using this variable include:

  1. Clearly name and document each custom build configuration for easy identification and management.
  2. Ensure that the custom build settings are appropriate for the target platform and device.
  3. Regularly review and update custom build configurations to maintain compatibility with project requirements and engine updates.
  4. Use the Project Settings interface in the Unreal Editor to manage these custom builds, ensuring consistency and reducing the risk of manual configuration errors.
  5. Consider version control implications when modifying custom build settings, especially in team environments.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseGame.ini:88, 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:628

Scope (from outer to inner):

file
class        class UProjectPackagingSettings : public UObject

Source code excerpt:

	 */
	UPROPERTY(config, EditAnywhere, Category=Packaging, meta=(DisplayName = "Additional builds for this project."))
	TArray<FProjectBuildSettings> ProjectCustomBuilds;

	/** If set, platforms that destructively edit the iostore containers during packaging will save a copy prior to doing so. */
	UPROPERTY(config, EditAnywhere, Category = Packaging)
	bool bRetainStagedDirectory;

	/**

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

Scope (from outer to inner):

file
function     static void MakeTurnkeyPlatformMenu

Source code excerpt:

		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
		MakeCustomBuildMenuEntries(Section, PackagingSettings->ProjectCustomBuilds, IniPlatformName, FString(), FString(), ToolTipFormat);


		UProjectPackagingSettings* AllPlatformPackagingSettings = GetMutableDefault<UProjectPackagingSettings>();

		// Populate Flavor Selection menu with available flavors
		// Flavor Selection exists for Android to be able to package ASTC, DXT, ETC2, etc

#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:1412

Scope (from outer to inner):

file
function     static void MakeTurnkeyPlatformMenu
lambda-function

Source code excerpt:

						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
						MakeCustomBuildMenuEntries(CustomBuildSection, PackagingSettings->ProjectCustomBuilds, IniPlatformName, DeviceId, DeviceName, ToolTipFormat);
					}


					FTurnkeySdkInfo SdkInfo = ITurnkeySupportModule::Get().GetSdkInfoForDeviceId(DeviceId);
					FText SdkText, SdkToolTip;
					FormatSdkInfo(DeviceId, SdkInfo, SdkText, SdkToolTip);

#References in C# build files

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

Location: <Workspace>/Engine/Source/Programs/AutomationTool/Turnkey/Commands/CreateBuild.cs:721

					List<string> ExistingBuilds;
					ConfigHierarchy Config = ConfigCache.ReadHierarchy(ConfigHierarchyType.Game, ProjectFile.Directory, BuildHostPlatform.Current.Platform);
					Config.GetArray(SettingsSection, "ProjectCustomBuilds", out ExistingBuilds);

					string Name;
					if (ExistingBuilds != null && ExistingBuilds.Count > 0)
					{
						TurnkeyUtils.Log($"Here are the existing builds your project already has (and their descrptions):");
						foreach (string Build in ExistingBuilds)

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

				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);
				}