/ue-module-build-system

Build.cs and Target.cs Field Reference (UE 5.8)

Every field below exists in Engine/Source/Programs/UnrealBuildTool/Configuration/Rules/ModuleRules.cs or TargetRules.cs in UE 5.8. Fields are set inside the constructor of a class deriving from ModuleRules (one per module) or TargetRules (one per target).

Class Structure

using UnrealBuildTool;
using System.IO;                 // Path.Combine, File.Exists

public class MyModule : ModuleRules
{
    public MyModule(ReadOnlyTargetRules Target) : base(Target)
    {
        // All fields are set here
    }
}

ReadOnlyTargetRules Target exposes the target being built: Target.Platform, Target.Configuration, Target.Type, Target.bBuildEditor, Target.bBuildDeveloperTools, Target.bWithLiveCoding, Target.LinkType, Target.ProjectFile, Target.IncludeOrderVersion. Inside the module, ModuleDirectory is the folder containing the Build.cs and PluginDirectory is the owning plugin's root (or null for project modules).

Dependency Fields

PublicDependencyModuleNames

PublicDependencyModuleNames.AddRange(new string[]
{
    "Core",           // FString, TArray, TMap, FName, UE_LOG
    "CoreUObject",    // UObject, UClass, reflection, FInstancedStruct
    "Engine",         // AActor, UWorld, UGameInstance, UActorComponent
    "InputCore",      // FKey, EKeys
});

"Modules that are required by our public source files." Their include paths and link dependencies are inherited by every module that depends on yours. Promote a module here only when a type from it appears in one of your Public/ headers.

PrivateDependencyModuleNames

PrivateDependencyModuleNames.AddRange(new string[]
{
    "Slate",          // SWidget, SCompoundWidget
    "SlateCore",      // FSlateColor, FSlateBrush
    "RenderCore",     // FRenderCommandFence
    "RHI",            // FRHITexture, FRHICommandList
    "Json",           // FJsonObject, FJsonSerializer
    "HTTP",           // FHttpModule, IHttpRequest
});

"Modules that our private code depends on but nothing in our public include files depend on." Not inherited downstream. Default to this list.

PublicIncludePathModuleNames / PrivateIncludePathModuleNames

// Header access only — no link dependency, no exported symbols
PrivateIncludePathModuleNames.Add("AssetRegistry");

Use for forward declarations and header-only types. Calling an exported function from such a module still fails with LNK2019.

DynamicallyLoadedModuleNames

DynamicallyLoadedModuleNames.AddRange(new string[] { "OnlineSubsystem", "OnlineSubsystemSteam" });

"Additional modules this module may require at run-time." UBT builds them but does not link them; load with FModuleManager::Get().LoadModule(...) or FModuleManager::LoadModulePtr<T>(...).

CircularlyReferencedDependentModules

// Legacy escape hatch only — the module must already be in a dependency list
CircularlyReferencedDependentModules.Add("MyOtherModule");

"Only for legacy reason, should not be used in new code." bValidateCircularDependencies (default true) validates cycles against UBT's allow list; disabling it is "strongly discouraged".

Include Path Fields

UBT discovers Public/, Internal/ and Private/ automatically (PublicIncludePaths is documented as "currently not needed as we discover all files from the 'Public' folder"). Use these only for extra folders.

// Extra folders exposed to dependents (rarely needed)
PublicIncludePaths.Add(Path.Combine(ModuleDirectory, "Public", "Interfaces"));

// Extra folders visible only inside this module
PrivateIncludePaths.Add(Path.Combine(ModuleDirectory, "Private", "Helpers"));

// Third-party headers; not checked when resolving header dependencies
string ThirdPartyDir = Path.Combine(ModuleDirectory, "ThirdParty");
PublicSystemIncludePaths.Add(Path.Combine(ThirdPartyDir, "include"));

bLegacyPublicIncludePaths and bLegacyParentIncludePaths (both false under BuildSettingsVersion.V3 and later) control whether other modules' headers may be included by bare file name or relative to their parent folder. Leave them false and write #include "GameFramework/Actor.h".

PCH and IWYU Fields

PCHUsage

PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;   // what BuildSettingsVersion.V2+ defaults to
PrivatePCHHeaderFile = "Private/MyModulePCH.h";    // explicit private PCH (optional)
SharedPCHHeaderFile = "Public/MyModuleSharedPCH.h"; // offer a shared PCH to dependents (engine-style)

IWYUSupport

IWYUSupport = IWYUSupport.Full;

Compiler Flags

bEnableExceptions = true;                     // C++ exceptions (default false)
bUseRTTI = true;                              // typeid / dynamic_cast (default false)
MinCpuArchX64 = MinimumCpuArchitectureX64.AVX2; // None, AVX, AVX2, AVX512; null = target default
bEnableBufferSecurityChecks = true;           // default true
bDisableStaticAnalysis = true;                // skip this module when -StaticAnalyzer is on
bUseUnity = false;                            // per-module unity override
bTreatAsEngineModule = true;                  // apply engine warning/include rules to a project module

OptimizeCode

OptimizeCode = CodeOptimization.Always;              // even in Debug
OptimizeCode = CodeOptimization.Never;               // even in Shipping (debugging a module)
OptimizeCode = CodeOptimization.InNonDebugBuilds;    // Development/Test/Shipping
OptimizeCode = CodeOptimization.InShippingBuildsOnly;
OptimizeCode = CodeOptimization.Default;             // follow the build configuration

CppStandard

CppStandard = CppStandardVersion.Cpp20;   // Cpp20, Cpp23, Latest; Default, EngineDefault and Minimum equal Cpp20 (Cpp14/Cpp17 are [Obsolete] in 5.8)

ModuleRules.CppStandard is nullable and overrides TargetRules.CppStandard for one module.

Warnings

bWarningsAsErrors promotes every warning. Individual categories live on CppCompileWarningSettings (type CppCompileWarnings, Configuration/Rules/CppCompileWarnings.cs); each accepts WarningLevel.Default, Off, Warning or Error. Module settings override the target's.

bWarningsAsErrors = true;
CppCompileWarningSettings.ShadowVariableWarningLevel = WarningLevel.Error;
CppCompileWarningSettings.UnsafeTypeCastWarningLevel = WarningLevel.Warning;
CppCompileWarningSettings.DeprecationWarningLevel = WarningLevel.Error;

Third-Party Libraries

AddEngineThirdPartyPrivateStaticDependencies

// Static, private link to libraries under Engine/Source/ThirdParty/<Name>/<Name>.Build.cs
AddEngineThirdPartyPrivateStaticDependencies(Target, "zlib", "OpenSSL", "libcurl");

// Dynamic (DLL) variant
AddEngineThirdPartyPrivateDynamicDependencies(Target, "OpenSSL");

UBT notes: "There is no AddThirdPartyPublicStaticDependencies function." Third-party modules are always private.

PublicAdditionalLibraries / PublicSystemLibraries / PublicDelayLoadDLLs / PublicFrameworks

string ThirdPartyDir = Path.Combine(ModuleDirectory, "ThirdParty");

PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyDir, "lib", "Win64", "MyLib.lib")); // full path to a .lib/.a
PublicSystemLibraries.Add("ws2_32.lib");                                                  // system library by name
PublicDelayLoadDLLs.Add("MyLib.dll");                                                     // Windows delay-load
// PublicFrameworks: Apple frameworks by name (Mac, IOS, TVOS, VisionOS)

RuntimeDependencies

"List of files which this module depends on at runtime. These files will be staged along with the target."

RuntimeDependencies.Add("$(PluginDir)/Binaries/ThirdParty/MyLib/Win64/MyLib.dll");             // staged next to binaries
RuntimeDependencies.Add("$(ProjectDir)/Config/MyRuntimeData.json", StagedFileType.NonUFS);     // explicit type
RuntimeDependencies.Add("$(BinaryOutputDir)/MyLib.dll", Path.Combine(ThirdPartyDir, "bin", "Win64", "MyLib.dll"), StagedFileType.NonUFS); // copy from source path

StagedFileType: UFS (inside the pak/IoStore), NonUFS (loose file, default), DebugNonUFS, SystemNonUFS. Path variables UBT expands: $(EngineDir), $(ProjectDir), $(PluginDir), $(BinaryOutputDir).

Preprocessor Definitions

PublicDefinitions.Add("MYGAME_WITH_DEBUG_MENU=1");   // visible to this module and its dependents
PrivateDefinitions.Add("MYGAME_WITH_DEBUG_MENU=0");  // visible only inside this module

Target-wide equivalents: TargetRules.GlobalDefinitions (every module including engine) and ProjectDefinitions (project modules only).

Helper Methods on ModuleRules

SetupIrisSupport(Target);                 // adds Iris replication dependencies based on target settings
SetupGameplayDebuggerSupport(Target);     // adds GameplayDebugger when the target supports it
SetupModulePhysicsSupport(Target);        // adds physics module dependencies

Platform-Conditional Patterns

public MyModule(ReadOnlyTargetRules Target) : base(Target)
{
    PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

    PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine" });

    // Editor-only dependencies
    if (Target.bBuildEditor)
    {
        PrivateDependencyModuleNames.AddRange(new string[] { "UnrealEd", "ToolMenus", "EditorFramework" });
    }

    // Platform-specific libraries
    if (Target.Platform == UnrealTargetPlatform.Win64)
    {
        PublicAdditionalLibraries.Add(Path.Combine(ModuleDirectory, "lib", "Win64", "MyLib.lib"));
        PublicDelayLoadDLLs.Add("MyLib.dll");
    }
    else if (Target.Platform == UnrealTargetPlatform.Mac)
    {
        PublicAdditionalLibraries.Add(Path.Combine(ModuleDirectory, "lib", "Mac", "libMyLib.a"));
    }

    // Configuration-specific code
    if (Target.Configuration != UnrealTargetConfiguration.Shipping)
    {
        PrivateDependencyModuleNames.Add("EngineSettings");
        PublicDefinitions.Add("MYGAME_WITH_DEBUG_MENU=1");
    }
    else
    {
        PublicDefinitions.Add("MYGAME_WITH_DEBUG_MENU=0");
    }

    // Server-only / client-only code paths
    if (Target.Type == TargetType.Server)
    {
        PrivateDefinitions.Add("MYGAME_WITH_DEBUG_MENU=0");
    }
}

Target.Platform Values (UnrealTargetPlatform)

Win64, Mac, Linux, LinuxArm64, IOS, TVOS, VisionOS, Android. Console platforms come from platform extensions and are not part of the public enum.

Target.Configuration Values (UnrealTargetConfiguration)

Target.LinkType Values (TargetLinkType)

Default (Modular for Editor, Monolithic for Game/Client/Server), Monolithic (one executable, IS_MONOLITHIC), Modular (one DLL per module).

TargetRules Reference (Target.cs)

using UnrealBuildTool;
using System.Collections.Generic;

public class MyGameTarget : TargetRules
{
    public MyGameTarget(TargetInfo Target) : base(Target)
    {
        Type = TargetType.Game;
        DefaultBuildSettings = BuildSettingsVersion.V7;              // 5.8 defaults; Latest == V7
        IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_8;   // Latest == Unreal5_8

        ExtraModuleNames.AddRange(new string[] { "MyGame", "MyGameCore" });

        bUseUnityBuild = false;              // faster incremental builds, slower full builds
        bUseAdaptiveUnityBuild = true;       // default: files you edit leave the unity blob
        bAllowLTCG = Target.Configuration == UnrealTargetConfiguration.Shipping;
        bUseLoggingInShipping = false;       // keep UE_LOG in Shipping when true
        bUseChecksInShipping = false;        // keep check()/ensure() in Shipping when true
        bWithLiveCoding = true;              // Live Coding support (editor/development)
        CppStandard = CppStandardVersion.Cpp20;
        bWarningsAsErrors = false;
        CppCompileWarningSettings.ShadowVariableWarningLevel = WarningLevel.Error;
        GlobalDefinitions.Add("MYGAME_WITH_DEBUG_MENU=1");
    }
}

BuildSettingsVersion

UBT Command-Line Modes

UnrealBuildTool -Mode=<Name> selects a tool mode; Modes/*.cs in UBT define these names: Build (default), Clean, GenerateProjectFiles, IWYU, FixIncludePaths, InlineGeneratedCpps, QueryTargets, Query, JsonExport, WriteMetadata, GenerateClangDatabase, Analyze, Test, UnrealHeaderTool, ValidatePlatforms, PrintBuildGraphInfo, ProfileUnitySizes, Deploy. Compile one translation unit with -SingleFile=<path>.

Common Engine Module Reference

Every module name below is a 5.8 module. The "Plugin" column names the .uplugin that must be enabled in .uproject (blank for engine modules that are always available).

API Macro Generation Rules

UBT builds the export macro by upper-casing the module name and appending _API (Configuration/UEBuildModule.cs) and defines it per compile as one of empty, DLLEXPORT or DLLIMPORT:

• Module MyPlugin → MYPLUGIN_API
• Module MyPlugin_Runtime → MYPLUGIN_RUNTIME_API
• Module Core → CORE_API

DLLEXPORT/DLLIMPORT expand to __declspec(dllexport)/__declspec(dllimport) on Windows (Windows/WindowsPlatform.h) and to __attribute__((visibility("default"))) on Unix platforms (Unix/UnixPlatform.h). In monolithic builds the macro is empty. Engine headers wrap the module macro in a file-local #define UE_API CORE_API … #undef UE_API pair; project headers write MYGAME_API directly.