UBT 中定义的 C++ 宏

UE4 引擎里面定义了很多引擎中的宏和一些处理逻辑,如 WITH_ENGINE/WITH_EDITOR 等,它们部分是 UBT 通过读取 *.target.cs 文件中的配置来定义的,有些逻辑是通过读取 *.Build.cs 的配置处理的。
我读了一下 UBT 的代码,抽出来部分 UBT 中配置文件 (Target.cs/Build.cs) 参数与 MACRO 的相互定义,作为速查手册。
*.Target.cs的参数可以看:UnrealBuildSystem/Targets
*.Build.cs的参数可以看:UnrealBuildSystem/ModuleFiles
UE 的构建系统文档: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
48
// 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");
}
}