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:
- DesktopPlatform: This module uses UnrealBuildTool for generating project files and compiling the engine and game code.
- HotReload: This module utilizes UnrealBuildTool for compiling modules during runtime for hot-reloading functionality.
- CookOnTheFlyServer: This system uses UnrealBuildTool to calculate build settings and module hashes.
- LiveCodingConsole: This tool uses UnrealBuildTool for compiling patches during live coding sessions.
- 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:
- Build configuration settings
- Platform-specific compilation flags
- Module definitions and dependencies
- Plugin descriptors and build settings
Developers should be aware of the following when using UnrealBuildTool:
- It is a critical component of the build process, and errors in its configuration can lead to build failures.
- UnrealBuildTool is typically located in the Engine/Binaries/DotNET directory.
- It can be invoked directly or through various engine tools and processes.
Best practices when using UnrealBuildTool include:
- Keeping it up-to-date with the engine version being used.
- Properly configuring build settings and module dependencies in project files.
- Using appropriate command-line arguments when invoking it directly.
- Ensuring that all required dependencies and SDKs are installed and properly configured.
- 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]
- INI Section:
PlatformPaths
- Raw value:
Engine/Build/BatchFiles/Build.bat
- Is Array:
False
Location: <Workspace>/Engine/Config/Linux/BaseLinuxEngine.ini:5, section: [PlatformPaths]
- INI Section:
PlatformPaths
- Raw value:
Engine/Build/BatchFiles/Linux/Build.sh
- Is Array:
False
Location: <Workspace>/Engine/Config/Mac/BaseMacEngine.ini:24, section: [PlatformPaths]
- INI Section:
PlatformPaths
- Raw value:
Engine/Build/BatchFiles/Mac/Build.sh
- Is Array:
False
#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.