Z's Blog

Macro defined by UBT in UE4

Posted on In , Views:
Symbols count in article: 3.1k Reading time ≈ 8 mins.

UE4 Engine defines many macros and some processing logic within the engine, such as WITH_ENGINE/WITH_EDITOR, etc. Some of these are defined by UBT through reading the configurations in *.target.cs files, and some logic is processed by reading configurations in *.Build.cs.

I have read some of the UBT code and extracted part of the configuration files (Target.cs/Build.cs) parameters and their mutual definitions with MACROs as a quick reference manual.
You can view the parameters in *.Target.cs here: UnrealBuildSystem/Targets
You can view the parameters in *.Build.cs here: UnrealBuildSystem/ModuleFiles
UE’s build system documentation: Build Tools

IS_PROGRAM

  • (TargetType) Target.Program

Type (TargetType): The type of target.

1
2
3
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

GlobalCompileEnvironment.Definitions.Add(String.Format("IS_PROGRAM={0}", TargetType == TargetType.Program ? "1" : "0"));

ENABLE_PGO_PROFILE

  • (bool) bPGOProfile

Whether to enable Profile Guided Optimization (PGO) instrumentation in this build.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bPGOProfile)
{
	GlobalCompileEnvironment.Definitions.Add("ENABLE_PGO_PROFILE=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("ENABLE_PGO_PROFILE=0");
}

ENGINE_BASE_DIR_ADJUST

  • (String) ExeBinariesSubFolder

Subfolder to place executables in, relative to the default location.

1
2
3
4
5
6
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if(!String.IsNullOrEmpty(Rules.ExeBinariesSubFolder))
{
	GlobalCompileEnvironment.Definitions.Add(String.Format("ENGINE_BASE_DIR_ADJUST={0}", Rules.ExeBinariesSubFolder.Replace('\\', '/').Trim('/').Count(x => x == '/') + 1));
}

WITH_DEV_AUTOMATION_TESTS

  • (bool) bForceCompileDevelopmentAutomationTests

Whether to compile development automation tests.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bForceCompileDevelopmentAutomationTests)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_DEV_AUTOMATION_TESTS=1");
}else
{
    switch(Configuration)
	{
		case UnrealTargetConfiguration.Test:
		case UnrealTargetConfiguration.Shipping:
				GlobalCompileEnvironment.Definitions.Add("WITH_DEV_AUTOMATION_TESTS=0");
				break;
		default:
				GlobalCompileEnvironment.Definitions.Add("WITH_DEV_AUTOMATION_TESTS=1");
				break;
	}
}

WITH_PERF_AUTOMATION_TESTS

  • (bool) bForceCompilePerformanceAutomationTests

Whether to compile performance automation tests.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bForceCompilePerformanceAutomationTests)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_PERF_AUTOMATION_TESTS=1");
}
else
{
	switch (Configuration)
	{
		case UnrealTargetConfiguration.Shipping:
			GlobalCompileEnvironment.Definitions.Add("WITH_PERF_AUTOMATION_TESTS=0");
			break;
		default:
			GlobalCompileEnvironment.Definitions.Add("WITH_PERF_AUTOMATION_TESTS=1");
		break;
	}
}

IS_MONOLITHIC

  • (TargetLinkType) LinkType

Monolithic Mode, which puts all code together in a single executable file.Module API Specifiers

1
2
3
4
5
6
7
8
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

// ...
bCompileMonolithic = (Rules.LinkType == TargetLinkType.Monolithic);

// ... 
GlobalCompileEnvironment.Definitions.Add(String.Format("IS_MONOLITHIC={0}", ShouldCompileMonolithic() ? "1" : "0"));
// ...

WITH_ENGINE

  • (bool) bCompileAgainstEngine

Enabled for all builds that include the engine project. Disabled only when building standalone apps that only link with Core.

WITH_UNREAL_DEVELOPER_TOOLS

  • bBuildDeveloperTools
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bCompileAgainstEngine)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_ENGINE=1");
	GlobalCompileEnvironment.Definitions.Add(
		String.Format("WITH_UNREAL_DEVELOPER_TOOLS={0}", Rules.bBuildDeveloperTools ? "1" : "0"));
}
else
{
	GlobalCompileEnvironment.Definitions.Add("WITH_ENGINE=0");
	// Can't have developer tools w/out engine
	GlobalCompileEnvironment.Definitions.Add("WITH_UNREAL_DEVELOPER_TOOLS=0");
}

WITH_COREUOBJECT

  • (bool)bCompileAgainstCoreUObject

Enabled for all builds that include the CoreUObject project. Disabled only when building standalone apps that only link with Core.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bCompileAgainstCoreUObject)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_COREUOBJECT=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("WITH_COREUOBJECT=0");
}

USE_STATS_WITHOUT_ENGINE

  • (bool) bCompileWithStatsWithoutEngine

Whether to include stats support even without the engine.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bCompileWithStatsWithoutEngine)
{
	GlobalCompileEnvironment.Definitions.Add("USE_STATS_WITHOUT_ENGINE=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("USE_STATS_WITHOUT_ENGINE=0");
}

WITH_PLUGIN_SUPPORT

  • (bool) bCompileWithPluginSupport

Whether to include plugin support.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bCompileWithPluginSupport)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_PLUGIN_SUPPORT=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("WITH_PLUGIN_SUPPORT=0");
}

WITH_PERFCOUNTERS

  • (bool) bWithPerfCounters

Whether to include PerfCounters support.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bWithPerfCounters)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_PERFCOUNTERS=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("WITH_PERFCOUNTERS=0");
}

USE_LOGGING_IN_SHIPPING

  • (bool) bUseLoggingInShipping

Whether to turn on logging for test/shipping builds.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bUseLoggingInShipping)
{
	GlobalCompileEnvironment.Definitions.Add("USE_LOGGING_IN_SHIPPING=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("USE_LOGGING_IN_SHIPPING=0");
}

WITH_LOGGING_TO_MEMORY

  • (bool) bLoggingToMemoryEnabled

Whether to turn on logging to memory for test/shipping builds.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bLoggingToMemoryEnabled)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_LOGGING_TO_MEMORY=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("WITH_LOGGING_TO_MEMORY=0");
}

USE_CACHE_FREED_OS_ALLOCS

  • (bool) bUseCacheFreedOSAllocs

Whether to turn on logging to memory for test/shipping builds.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bUseCacheFreedOSAllocs)
{
	GlobalCompileEnvironment.Definitions.Add("USE_CACHE_FREED_OS_ALLOCS=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("USE_CACHE_FREED_OS_ALLOCS=0");
}

USE_CHECKS_IN_SHIPPING

  • (bool) bUseChecksInShipping

Whether to turn on checks (asserts) for test/shipping builds.

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bUseChecksInShipping)
{
	GlobalCompileEnvironment.Definitions.Add("USE_CHECKS_IN_SHIPPING=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("USE_CHECKS_IN_SHIPPING=0");
}

UE_BUILD_MINIMAL

  • (bool) bCompileLeanAndMeanUE

Whether to compile lean and mean version of UE.

1
2
3
4
5
6
7
8
9
10
11
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

// Propagate whether we want a lean and mean build to the C++ code.
if (Rules.bCompileLeanAndMeanUE)
{
	GlobalCompileEnvironment.Definitions.Add("UE_BUILD_MINIMAL=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("UE_BUILD_MINIMAL=0");
}

WITH_EDITOR

  • (bool) bBuildEditor

Whether to compile the editor or not. Only desktop platforms (Windows or Mac) will use this, other platforms force this to false.

1
2
3
4
5
6
7
8
9
10
11
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

// bBuildEditor has now been set appropriately for all platforms, so this is here to make sure the #define 
if (Rules.bBuildEditor)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_EDITOR=1");
}
else if (!GlobalCompileEnvironment.Definitions.Contains("WITH_EDITOR=0"))
{
	GlobalCompileEnvironment.Definitions.Add("WITH_EDITOR=0");
}

WITH_EDITORONLY_DATA

  • (bool) bBuildWithEditorOnlyData

Whether to compile WITH_EDITORONLY_DATA disabled. Only Windows will use this, other platforms force this to false.

1
2
3
4
5
6
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bBuildWithEditorOnlyData == false)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_EDITORONLY_DATA=0");
}

WITH_SERVER_CODE

  • (bool) bWithServerCode

Compile server-only code.

1
2
3
4
5
6
7
8
9
10
11
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

// Check if server-only code should be compiled out.
if (Rules.bWithServerCode == true)
{
	GlobalCompileEnvironment.Definitions.Add("WITH_SERVER_CODE=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("WITH_SERVER_CODE=0");
}

WITH_CEF3

1
2
3
4
5
6
7
8
9
10
11
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

// Set the define for whether we're compiling with CEF3
if (Rules.bCompileCEF3 && (Platform == UnrealTargetPlatform.Win32 || Platform == UnrealTargetPlatform.Win64 || Platform == UnrealTargetPlatform.Mac || Platform == UnrealTargetPlatform.Linux))
{
	GlobalCompileEnvironment.Definitions.Add("WITH_CEF3=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("WITH_CEF3=0");
}

WITH_XGE_CONTROLLER

  • bUseXGEController
  • TargetType.Editor && UnrealTargetPlatform is Win32/Win64
1
2
3
4
5
6
7
8
9
10
11
12
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

if (Rules.bUseXGEController &&
	Rules.Type == TargetType.Editor &&
	(Platform == UnrealTargetPlatform.Win32 || Platform == UnrealTargetPlatform.Win64))
{
	GlobalCompileEnvironment.Definitions.Add("WITH_XGE_CONTROLLER=1");
}
else
{
	GlobalCompileEnvironment.Definitions.Add("WITH_XGE_CONTROLLER=0");
}

UBT_MODULE_MANIFEST

1
2
3
4
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

// ...
GlobalCompileEnvironment.Definitions.Add(String.Format("UBT_MODULE_MANIFEST=\"{0}\"", ModuleManifest.GetStandardFileName(AppName, Platform, Configuration, Architecture, false)));

UBT_MODULE_MANIFEST_DEBUGGAME

1
2
3
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

GlobalCompileEnvironment.Definitions.Add(String.Format("UBT_MODULE_MANIFEST_DEBUGGAME=\"{0}\"", ModuleManifest.GetStandardFileName(AppName, Platform, UnrealTargetConfiguration.DebugGame, Architecture, true)));

UBT_COMPILED_PLATFORM

1
2
3
4
5
6
7
8
9
10
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

public UEBuildTarget(SerializationInfo Info, StreamingContext Context)
{
	// ...
	Platform = (UnrealTargetPlatform)Info.GetInt32("pl");
	// ...
}

GlobalCompileEnvironment.Definitions.Add("UBT_COMPILED_PLATFORM=" + Platform.ToString());

UBT_COMPILED_TARGET

  • TargetType
1
2
3
// Programs/UnrealBuildTool/Configuration/UEBuildTarget.cs

GlobalCompileEnvironment.Definitions.Add("UBT_COMPILED_TARGET=" + TargetType.ToString());

WITH_PHYSX

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
- (bool) bCompilePhysX

>Whether to include PhysX support.

// Programs/UnrealBuildTool/Configuration/ModuleRules.cs
// SetupModulePhysXAPEXSupport(ReadOnlyTargetRules Target)
// definitions used outside of PhysX/APEX need to be set here, not in PhysX.Build.cs or APEX.Build.cs, 
// since we need to make sure we always set it, even to 0 (because these are Private dependencies, the
// defines inside their Build.cs files won't leak out)
if (Target.bCompilePhysX == true)
{
	PrivateDependencyModuleNames.Add("PhysX");
	PublicDefinitions.Add("WITH_PHYSX=1");
}
else
{
	PublicDefinitions.Add("WITH_PHYSX=0");
}

WITH_APEX

Whether to include PhysX APEX support.

WITH_APEX_CLOTHING

WITH_CLOTH_COLLISION_DETECTION

WITH_PHYSX_COOKING

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Programs/UnrealBuildTool/Configuration/ModuleRules.cs
// SetupModulePhysXAPEXSupport(ReadOnlyTargetRules Target)
if (Target.bCompileAPEX == true)
{
	if (!Target.bCompilePhysX)
	{
		throw new BuildException("APEX is enabled, without PhysX. This is not supported!");
	}

	PrivateDependencyModuleNames.Add("APEX");
	PublicDefinitions.Add("WITH_APEX=1");
	PublicDefinitions.Add("WITH_APEX_CLOTHING=1");
	PublicDefinitions.Add("WITH_CLOTH_COLLISION_DETECTION=1");
	PublicDefinitions.Add("WITH_PHYSX_COOKING=1");  // APEX currently relies on cooking even at runtime

}
else
{
	PublicDefinitions.Add("WITH_APEX=0");
	PublicDefinitions.Add("WITH_APEX_CLOTHING=0");
	PublicDefinitions.Add("WITH_CLOTH_COLLISION_DETECTION=0");
	PublicDefinitions.Add(string.Format("WITH_PHYSX_COOKING={0}", Target.bBuildEditor && Target.bCompilePhysX ? 1 : 0));  // without APEX, we only need cooking in editor builds
}

WITH_NVCLOTH

  • (bool) bCompileNvCloth

Whether to include NvCloth.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Programs/UnrealBuildTool/Configuration/ModuleRules.cs
// SetupModulePhysXAPEXSupport(ReadOnlyTargetRules Target)
if (Target.bCompileNvCloth == true)
{
	if (!Target.bCompilePhysX)
	{
		throw new BuildException("NvCloth is enabled, without PhysX. This is not supported!");
	}

	PrivateDependencyModuleNames.Add("NvCloth");
                PublicDefinitions.Add("WITH_NVCLOTH=1");

}
else
{
	PublicDefinitions.Add("WITH_NVCLOTH=0");
}

bUsesSlate

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Programs/UnrealBuildTool/Configuration/UEBuildTargets.cs
// void PrepareReceipts(UEToolChain ToolChain, List<KeyValuePair<FileReference, BuildProductType>> BuildProducts, List<KeyValuePair<FileReference, BuildProductType>> PrecompileOnlyBuildProducts, EHotReload HotReload)

if (Rules.bUsesSlate)
{
	AddRuntimeDependenciesFromDir(DirectoryReference.Combine(UnrealBuildTool.EngineDirectory, "Content", "Slate"), StagedFileType.UFS);
	AddRuntimeDependenciesFromDir(DirectoryReference.Combine(UnrealBuildTool.EngineDirectory, "Content", "SlateDebug"), StagedFileType.UFS);

	if (ProjectFile != null)
	{
		AddRuntimeDependenciesFromDir(DirectoryReference.Combine(ProjectDirectory, "Content", "Slate"), StagedFileType.UFS);
		AddRuntimeDependenciesFromDir(DirectoryReference.Combine(ProjectDirectory, "Content", "SlateDebug"), StagedFileType.UFS);
	}
}

bIsBuildingConsoleApplication

True if this is a console application that’s being built.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
// Programs/UnrealBuildTool/Platform/Windows/VCToolChains.cs
// void AppendLibArguments(LinkEnvironment LinkEnvironment, List<string> Arguments)
void AppendLibArguments(LinkEnvironment LinkEnvironment, List<string> Arguments)
{
	// Prevents the linker from displaying its logo for each invocation.
	Arguments.Add("/NOLOGO");

	// Prompt the user before reporting internal errors to Microsoft.
	Arguments.Add("/errorReport:prompt");

	//
	//	PC
	//
	if (LinkEnvironment.Platform == CppPlatform.Win32 || LinkEnvironment.Platform == CppPlatform.Win64)
	{
		// Set machine type/ architecture to be 64 bit.
		if (LinkEnvironment.Platform == CppPlatform.Win64)
		{
			Arguments.Add("/MACHINE:x64");
		}
		// 32 bit executable/ target.
		else
		{
			Arguments.Add("/MACHINE:x86");
		}

		{
			if (LinkEnvironment.bIsBuildingConsoleApplication)
			{
				Arguments.Add("/SUBSYSTEM:CONSOLE");
			}
			else
			{
				Arguments.Add("/SUBSYSTEM:WINDOWS");
			}
		}
	}

	//
	//	Shipping & LTCG
	//
	if (LinkEnvironment.Configuration == CppConfiguration.Shipping)
	{
		// Use link-time code generation.
		Arguments.Add("/LTCG");
	}
}
The article is finished. If you have any questions, please comment and communicate.

Scan the QR code on WeChat and follow me.

Title:Macro defined by UBT in UE4
Author:LIPENGZHA
Publish Date:2019/01/09 18:17
Word Count:3.1k Words
Link:https://en.imzlp.com/posts/5214/
License: CC BY-NC-SA 4.0
Reprinting of the full article is prohibited.
Your donation will encourage me to keep creating!