UnrealBuildTool

UnrealBuildTool

#Overview

name: UnrealBuildTool

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

It is referenced in 15 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of UnrealBuildTool is to serve as a build automation tool for Unreal Engine projects. It is responsible for compiling and linking the engine, game code, and plugins, as well as generating project files for various integrated development environments (IDEs).

UnrealBuildTool is a critical component of the Unreal Engine build system and is relied upon by several subsystems and modules, including:

  1. DesktopPlatform: This module uses UnrealBuildTool for generating project files and compiling the engine and game code.
  2. HotReload: This module utilizes UnrealBuildTool for compiling modules during runtime for hot-reloading functionality.
  3. CookOnTheFlyServer: This system uses UnrealBuildTool to calculate build settings and module hashes.
  4. LiveCodingConsole: This tool uses UnrealBuildTool for compiling patches during live coding sessions.
  5. UnrealBuildAccelerator: This system interacts with UnrealBuildTool for distributed build processes.

The value of UnrealBuildTool is typically set within the engine configuration files, such as Engine.ini. It can also be specified via command-line arguments or environment variables.

UnrealBuildTool interacts with various other variables and systems, including:

  1. Build configuration settings
  2. Platform-specific compilation flags
  3. Module definitions and dependencies
  4. Plugin descriptors and build settings

Developers should be aware of the following when using UnrealBuildTool:

  1. It is a critical component of the build process, and errors in its configuration can lead to build failures.
  2. UnrealBuildTool is typically located in the Engine/Binaries/DotNET directory.
  3. It can be invoked directly or through various engine tools and processes.

Best practices when using UnrealBuildTool include:

  1. Keeping it up-to-date with the engine version being used.
  2. Properly configuring build settings and module dependencies in project files.
  3. Using appropriate command-line arguments when invoking it directly.
  4. Ensuring that all required dependencies and SDKs are installed and properly configured.
  5. Regularly cleaning build artifacts to avoid potential conflicts or outdated compilations.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3437, section: [PlatformPaths]

Location: <Workspace>/Engine/Config/Linux/BaseLinuxEngine.ini:5, section: [PlatformPaths]

Location: <Workspace>/Engine/Config/Mac/BaseMacEngine.ini:24, section: [PlatformPaths]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/DesktopPlatform/Private/DesktopPlatformBase.cpp:633

Scope (from outer to inner):

file
function     bool FDesktopPlatformBase::GenerateProjectFiles

Source code excerpt:

	}

	// Compile UnrealBuildTool if it doesn't exist. This can happen if we're just copying source from somewhere.
	bool bRes = true;
	Warn->BeginSlowTask(LOCTEXT("GeneratingProjectFiles", "Generating project files..."), true, true);
	if(!FPaths::FileExists(GetUnrealBuildToolExecutableFilename(RootDir)))
	{
		Warn->StatusUpdate(0, 1, LOCTEXT("BuildingUBT", "Building UnrealBuildTool..."));
		bRes = BuildUnrealBuildTool(RootDir, *Warn);

#Loc: <Workspace>/Engine/Source/Developer/DesktopPlatform/Private/DesktopPlatformBase.cpp:702

Scope (from outer to inner):

file
function     FProcHandle FDesktopPlatformBase::InvokeUnrealBuildToolAsync

Source code excerpt:

	FString CmdLineParams = InCmdLineParams;

	// UnrealBuildTool is currently always located in the Binaries/DotNET folder
	FString ExecutableFileName = GetUnrealBuildToolExecutableFilename(FPaths::RootDir());

	// Installed builds never build UBT, UnrealBuildTool should already exist
	bool bSkipBuild = FApp::IsEngineInstalled() || bSkipBuildUBT;
	if (!bSkipBuild)
	{
		// When not using an installed build, we should attempt to build UBT to make sure it is up to date
		// Only do this if we have not already successfully done it once during this session.
		static bool bSuccessfullyBuiltUBTOnce = false;

#Loc: <Workspace>/Engine/Source/Developer/DesktopPlatform/Private/DesktopPlatformBase.cpp:735

Scope (from outer to inner):

file
function     FProcHandle FDesktopPlatformBase::InvokeUnrealBuildToolAsync

Source code excerpt:

	Ar.Logf(TEXT("Launching UnrealBuildTool... [%s %s]"), *ExecutableFileName, *CmdLineParams);

	// Run UnrealBuildTool
	const bool bLaunchDetached = false;
	const bool bLaunchHidden = true;
	const bool bLaunchReallyHidden = bLaunchHidden;

	FProcHandle ProcHandle = FPlatformProcess::CreateProc(*ExecutableFileName, *CmdLineParams, bLaunchDetached, bLaunchHidden, bLaunchReallyHidden, NULL, 0, NULL, OutWritePipe, OutReadPipe);
	if (!ProcHandle.IsValid())

#Loc: <Workspace>/Engine/Source/Developer/DesktopPlatform/Public/IDesktopPlatform.h:364

Scope (from outer to inner):

file
class        class IDesktopPlatform

Source code excerpt:


	/**
	* Determines whether UnrealBuildTool is available
	*
	* @return true if UnrealBuildTool is available
	*/
	virtual bool IsUnrealBuildToolAvailable() = 0;

	/**
	 * Invokes UnrealBuildTool with the given arguments
	 *
	 * @return true if tool was invoked properly
	 */
	virtual bool InvokeUnrealBuildToolSync(const FString& InCmdLineParams, FOutputDevice& Ar, bool bSkipBuildUBT, int32& OutReturnCode, FString& OutProcOutput) = 0;

	/** 
	 * Launches UnrealBuildTool with the specified command line parameters 
	 * 
	 * @return process handle to the new UBT process
	 */
	virtual FProcHandle InvokeUnrealBuildToolAsync(const FString& InCmdLineParams, FOutputDevice& Ar, void*& OutReadPipe, void*& OutWritePipe, bool bSkipBuildUBT = false) = 0;

	/**
	* Runs UnrealBuildTool with the given arguments.
	*
	* @param Description		Task description for FFeedbackContext
	* @param RootDir			Engine root directory for the project to use.
	* @param Arguments			Parameters for UnrealBuildTool
	* @param Warn				Feedback context to use for progress updates
	* @return true if the task completed successfully.
	*/
	virtual bool RunUnrealBuildTool(const FText& Description, const FString& RootDir, const FString& Arguments, FFeedbackContext* Warn) = 0;

	/**
	* Runs UnrealBuildTool with the given arguments.
	*
	* @param Description		Task description for FFeedbackContext
	* @param RootDir			Engine root directory for the project to use.
	* @param Arguments			Parameters for UnrealBuildTool
	* @param Warn				Feedback context to use for progress updates
	* @param OutExitCode		Receives the process exit code
	* @return true if the task completed successfully.
	*/
	virtual bool RunUnrealBuildTool(const FText& Description, const FString& RootDir, const FString& Arguments, FFeedbackContext* Warn, int32& OutExitCode) = 0;

	/**
	* Checks if an instance of UnrealBuildTool is running.
	*
	* @return true if an instance of UnrealBuildTool is running.
	*/
	virtual bool IsUnrealBuildToolRunning() = 0;

	/**
	 * Gets information about the build targets supported by a particular project.
	 *
	 * @return Array of TargetInfo objects
	 */
	virtual const TArray<FTargetInfo>& GetTargetsForProject(const FString& ProjectFile) const = 0;

#Loc: <Workspace>/Engine/Source/Developer/DesktopPlatform/Public/TargetReceiptBuildWorker.h:21

Scope: file

Source code excerpt:


/**
 * Globally registers a UE::DerivedData::IBuildWorkerFactory instance that runs an executable built by UnrealBuildTool.
 * UnrealBuildTool provides the executable information through a TargetReceipt file.
*/
class DESKTOPPLATFORM_API FTargetReceiptBuildWorker
{
public:
	FTargetReceiptBuildWorker(const TCHAR* TargetReceiptFilePath);
	virtual ~FTargetReceiptBuildWorker();

private:
	/**

#Loc: <Workspace>/Engine/Source/Developer/HotReload/Private/HotReload.cpp:270

Scope (from outer to inner):

file
class        class FHotReloadModule : public IHotReloadModule, FSelfRegisteringExec

Source code excerpt:

	void OnModuleCompileSucceeded(FName ModuleName, const FString& ModuleFilename);

	/** Returns arguments to pass to UnrealBuildTool when compiling modules */
	static FString MakeUBTArgumentsForModuleCompiling();

#if WITH_HOT_RELOAD
	/** 
	 *	Starts compiling DLL files for one or more modules.
	 *

#Loc: <Workspace>/Engine/Source/Developer/HotReload/Private/HotReload.cpp:289

Scope (from outer to inner):

file
class        class FHotReloadModule : public IHotReloadModule, FSelfRegisteringExec

Source code excerpt:

#endif

	/** Launches UnrealBuildTool with the specified command line parameters */
	bool InvokeUnrealBuildToolForCompile(const FString& InCmdLineParams, FOutputDevice &Ar);

	/** Checks to see if a pending compilation action has completed and optionally waits for it to finish.  If completed, fires any appropriate callbacks and reports status provided bFireEvents is true. */
	void CheckForFinishedModuleDLLCompile(EHotReloadFlags Flags, bool& bCompileStillInProgress, bool& bCompileSucceeded, FOutputDevice& Ar, bool bFireEvents = true);

	/** Called when the compile data for a module need to be update in memory and written to config */

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/CookOnTheFlyServer.cpp:8054

Scope (from outer to inner):

file
function     TMap<FName, FString> UCookOnTheFlyServer::CalculateCookSettingStrings

Source code excerpt:


	// Calculate the executable hash by combining the module file hash of every loaded module
	// TODO: Write the module file hash from UnrealBuildTool into the .modules file and read it
	// here from the .modules file instead of calculating it on every cook.
	if (bIterativeCalculateExe)
	{
		FString InvalidModule;
		bool bValid = true;
		FXxHash64Builder Hasher;

#Loc: <Workspace>/Engine/Source/Programs/LiveCodingConsole/Private/LiveCodingConsole.cpp:267

Scope (from outer to inner):

file
class        class FLiveCodingConsoleApp
function     ELiveCodingCompileResult CompilePatch

Source code excerpt:

		FString Executable;
		FString Entry;
		if( GConfig->GetString( TEXT("PlatformPaths"), TEXT("UnrealBuildTool"), Entry, GEngineIni ))
		{
			Executable = FPaths::ConvertRelativePathToFull(FPaths::RootDir() / Entry);
		}
		else
		{
			Executable = FPaths::EngineDir() / TEXT("Binaries/DotNET/UnrealBuildTool/UnrealBuildTool.exe");

#Loc: <Workspace>/Engine/Source/Programs/UnrealBuildAccelerator/Common/Public/UbaSessionServer.h:20

Scope (from outer to inner):

file
namespace    uba
class        class SessionServer final : public Session

Source code excerpt:

		// Run process remotely.
		// startInfo contains info about the process to run remotely
		// weight is the expected core usage of the process. If processes are multithreaded it makes sense to increase weight. As an example, in UnrealBuildTool we see cl.exe as 1.5 and clang.exe as 1.0
		// knownInputs is a memory block with null terminated tchar strings followed by an empty null terminated string to end. knownInputsCount is the number of strings in the memory block
		// strings should be absolute or relative to working dir.
		ProcessHandle RunProcessRemote(const ProcessStartInfo& startInfo, float weight = 1.0f, const void* knownInputs = nullptr, u32 knownInputsCount = 0);

		// Will kick off a local process with the same startInfo as the one provided to start the process with id matching raceAgainstRemoteProcessId
		// This can be useful if there are free local cores and we know local machine is faster or network connection to remote is slow

#Loc: <Workspace>/Engine/Source/Programs/UnrealBuildAccelerator/Core/Private/UbaApplicationRules.cpp:329

Scope (from outer to inner):

file
namespace    uba
class        class ApplicationRulesUBTDll : public ApplicationRules
function     virtual bool IsOutputFile

Source code excerpt:

		{
			return false;
			// TODO: These does not work when UnrealBuildTool creates these files multiple times in a row (building multiple targets)
			// ... on output they get stored as file mappings.. and next execution of ubt opens them for write (writing file mappings not implemented right now)
			//return EndsWith(file, fileLen, TC(".modules"))
			//	|| EndsWith(file, fileLen, TC(".target"))
			//	|| EndsWith(file, fileLen, TC(".version"));
		}
	};

#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/HAL/Platform.h:162

Scope: file

Source code excerpt:


// Defines for the availibility of the various levels of vector intrinsics.
// These may be set from UnrealBuildTool, otherwise each platform-specific platform.h is expected to set them appropriately.
#ifndef PLATFORM_ENABLE_VECTORINTRINSICS
	#define PLATFORM_ENABLE_VECTORINTRINSICS	0
#endif
// If PLATFORM_MAYBE_HAS_### is 1, then ### intrinsics are compilable.
// This does not guarantee that the intrinsics are runnable on all instances of the platform however; a runtime check such as cpuid may be required to confirm availability.
// If PLATFORM_ALWAYS_HAS_### is 1, then ## intrinsics will compile and run on all instances of the platform.  PLATFORM_ALWAYS_HAS_### == 1 implies PLATFORM_MAYBE_HAS_### == 1.

#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/Misc/CompilationResult.h:8

Scope: file

Source code excerpt:

 *
 * This enum has to be compatible with the one defined in the
 * Engine\Source\Programs\UnrealBuildTool\System\ExternalExecution.cs file
 * to keep communication between UHT, UBT and Editor compiling processes valid.
 */
namespace ECompilationResult
{
	enum Type
	{
		/** Compilation succeeded */
		Succeeded = 0,
		/** Build was canceled, this is used on the engine side only */
		Canceled = 1,
		/** All targets were up to date, used only with -canskiplink */
		UpToDate = 2,

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Private/IOSRuntimeSettings.cpp:154

Scope (from outer to inner):

file
function     void UIOSRuntimeSettings::PostInitProperties

Source code excerpt:

		PossibleKeyLocations.Add(FPaths::Combine(*FPaths::EngineDir(), TEXT("Restricted"), TEXT("NoRedist"), TEXT("Build"), *RelativeFilePathLocation));
		PossibleKeyLocations.Add(FPaths::Combine(*FPaths::EngineDir(), TEXT("Build"), *RelativeFilePathLocation));
		PossibleKeyLocations.Add(FPaths::Combine(*Path, TEXT("Unreal Engine"), TEXT("UnrealBuildTool"), *RelativeFilePathLocation));

		// Find a potential path that we will use if the user hasn't overridden.
		// For information purposes only
		for (const FString& NextLocation : PossibleKeyLocations)
		{
			if (IFileManager::Get().FileSize(*NextLocation) > 0)

#Loc: <Workspace>/Engine/Source/Runtime/Projects/Private/PluginManager.cpp:91

Scope (from outer to inner):

file
namespace    PluginSystemDefs

Source code excerpt:

{
	/** File extension of plugin descriptor files.
	    NOTE: This constant exists in UnrealBuildTool code as well. */
	static const TCHAR* PluginDescriptorFileExtension = TEXT( ".uplugin" );

	/**
	 * Parsing the command line and loads any foreign plugins that were
	 * specified using the -PLUGIN= command.
	 *
	 * @param  CommandLine    The commandline used to launch the editor.