ue-module-build-system

Name: ue-module-build-system
Author: quodsoler

593installs39forks

How to install ue-module-build-system?

quodsoler/unreal-engine-skills/ue-module-build-system

$npx -y skills add quodsoler/unreal-engine-skills --skill ue-module-build-system

Installs into the current project.

Summary

Use when working with Build.cs, Target.cs, module creation, plugin setup, or build errors in Unreal Engine — including "unresolved external symbol," "cannot open include file," IWYU violations, missing API macros, or dependency configuration. See also ue-cpp-foundations for UObje

Files · 1

View on GitHub

SKILL.md

1	# UE Module & Build System
2
3	You are an expert in Unreal Engine's module and build system. You understand Unreal Build Tool (UBT), ModuleRules, TargetRules, the .uproject manifest, plugin architecture, and the IWYU include discipline enforced by UE5.
4
5	## Before Starting
6
7	Read `.agents/ue-project-context.md` if it exists — it provides module names, engine version, active plugins, and build targets that affect dependency and include configuration.
8
9	Ask which situation applies:
10	1. Configuring dependencies in an existing Build.cs
11	2. Creating a new module from scratch
12	3. Creating a new plugin
13	4. Resolving a build error (linker, include, or IWYU)
14	5. Setting up Target.cs for a new build target
15
16	---
17
18	## Build.cs Anatomy
19
20	Every UE module has a `ModuleName.Build.cs` file next to its `Public/` and `Private/` directories.
21
22	```csharp
23	// Source/MyModule/MyModule.Build.cs
24	using UnrealBuildTool;
25
26	public class MyModule : ModuleRules
27	{
28	public MyModule(ReadOnlyTargetRules Target) : base(Target)
29	{
30	// PCH settings — use IWYU in UE5
31	PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
32	// Enable strict IWYU (recommended for new modules in UE5)
33	bEnforceIWYU = true;
34
35	// Types accessible to modules that depend on MyModule
36	PublicDependencyModuleNames.AddRange(new string[]
37	{
38	"Core",
39	"CoreUObject",
40	"Engine",
41	});
42
43	// Types used only internally (not re-exported in public headers)
44	PrivateDependencyModuleNames.AddRange(new string[]
45	{
46	"Slate",
47	"SlateCore",
48	});
49
50	// Load at runtime but don't link at compile time
51	DynamicallyLoadedModuleNames.Add("OnlineSubsystem");
52	}
53	}
54	```
55
56	### Public vs Private Dependencies
57
58	\| Field \| When to use \|
59	\|---\|---\|
60	\| `PublicDependencyModuleNames` \| A type from the dependency appears in your public headers \|
61	\| `PrivateDependencyModuleNames` \| The dependency is consumed only in Private/ .cpp files \|
62
63	A common mistake: putting everything in `PublicDependencyModuleNames`. This bloats transitive include paths for every downstream module. Only promote to public when your public headers actually `#include` headers from that module.
64
65	### Include Paths
66
67	```csharp
68	// Expose extra paths to modules that depend on you
69	PublicIncludePaths.Add(Path.Combine(ModuleDirectory, "Public/Interfaces"));
70
71	// Expose extra paths only to this module's own source
72	PrivateIncludePaths.Add(Path.Combine(ModuleDirectory, "Private/Helpers"));
73	```
74
75	UBT automatically adds `Public/` and `Private/` — you rarely need to set these manually unless you have nested subdirectory headers you want to import without path prefixes.
76
77	### API Export Macro
78
79	UBT generates `MODULENAME_API` from the module's directory name, uppercased. Any class, function, or variable that must be visible across DLL boundaries needs this macro:
80
81	```cpp
82	// Public/MyClass.h
83	#pragma once
84	#include "CoreMinimal.h"
85
86	class MYMODULE_API FMyClass
87	{
88	public:
89	void DoSomething();
90	};
91
92	// Standalone exported function
93	MYMODULE_API void MyFreeFunction();
94	```
95
96	Missing `MYMODULE_API` on a class that another module references causes "unresolved external symbol" linker errors.
97
98	### PCH and IWYU
99
100	```csharp
101	// UE5 recommended — each file includes exactly what it uses
102	PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
103	bEnforceIWYU = true;
104
105	// Legacy — one monolithic PCH (avoid for new modules)
106	PCHUsage = PCHUsageMode.UseSharedPCHs;
107	```
108
109	With IWYU, every `.cpp` file includes its own `.h` first, then only what it directly uses:
110
111	```cpp
112	// Private/MyClass.cpp
113	#include "MyClass.h" // own header first
114	#include "Engine/Actor.h" // only includes this file directly uses
115	```
116
117	### Compiler Flags
118
119	```csharp
120	// C++ exceptions — disable unless third-party code requires them
121	bEnableExceptions = false;
122
123	// Runtime type information — disable unless using dynamic_cast
124	bUseRTTI = false;
125
126	// Third-party static libraries shipped with the engine
127	AddEngineThirdPartyPrivateStaticDependencies(Target, "zlib", "OpenSSL");
128	```
129
130	---
131
132	## Target.cs
133
134	Located at `Source/ProjectName.Target.cs` (and `Source/ProjectNameEditor.Target.cs`).
135
136	```csharp
137	// Source/MyGame.Target.cs
138	using UnrealBuildTool;
139	using System.Collections.Generic;
140
141	public class MyGameTarget : TargetRules
142	{
143	public MyGameTarget(TargetInfo Target) : base(Target)
144	{
145	Type = TargetType.Game;
146	DefaultBuildSettings = BuildSettingsVersion.Latest;
147	IncludeOrderVersion = EngineIncludeOrderVersion.Latest;
148
149	// All game modules that UBT should compile
150	ExtraModuleNames.AddRange(new str

People who liked this also viewed

6 picks

Type

ue-module-build-system

593installs39forks

View on GitHub

How to install ue-module-build-system?

quodsoler/unreal-engine-skills/ue-module-build-system

$npx -y skills add quodsoler/unreal-engine-skills --skill ue-module-build-system

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# UE Module & Build System
2
3	You are an expert in Unreal Engine's module and build system. You understand Unreal Build Tool (UBT), ModuleRules, TargetRules, the .uproject manifest, plugin architecture, and the IWYU include discipline enforced by UE5.
4
5	## Before Starting
6
7	Read `.agents/ue-project-context.md` if it exists — it provides module names, engine version, active plugins, and build targets that affect dependency and include configuration.
8
9	Ask which situation applies:
10	1. Configuring dependencies in an existing Build.cs
11	2. Creating a new module from scratch
12	3. Creating a new plugin
13	4. Resolving a build error (linker, include, or IWYU)
14	5. Setting up Target.cs for a new build target
15
16	---
17
18	## Build.cs Anatomy
19
20	Every UE module has a `ModuleName.Build.cs` file next to its `Public/` and `Private/` directories.
21
22	```csharp
23	// Source/MyModule/MyModule.Build.cs
24	using UnrealBuildTool;
25
26	public class MyModule : ModuleRules
27	{
28	public MyModule(ReadOnlyTargetRules Target) : base(Target)
29	{
30	// PCH settings — use IWYU in UE5
31	PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
32	// Enable strict IWYU (recommended for new modules in UE5)
33	bEnforceIWYU = true;
34
35	// Types accessible to modules that depend on MyModule
36	PublicDependencyModuleNames.AddRange(new string[]
37	{
38	"Core",
39	"CoreUObject",
40	"Engine",
41	});
42
43	// Types used only internally (not re-exported in public headers)
44	PrivateDependencyModuleNames.AddRange(new string[]
45	{
46	"Slate",
47	"SlateCore",
48	});
49
50	// Load at runtime but don't link at compile time
51	DynamicallyLoadedModuleNames.Add("OnlineSubsystem");
52	}
53	}
54	```
55
56	### Public vs Private Dependencies
57
58	\| Field \| When to use \|
59	\|---\|---\|
60	\| `PublicDependencyModuleNames` \| A type from the dependency appears in your public headers \|
61	\| `PrivateDependencyModuleNames` \| The dependency is consumed only in Private/ .cpp files \|
62
63	A common mistake: putting everything in `PublicDependencyModuleNames`. This bloats transitive include paths for every downstream module. Only promote to public when your public headers actually `#include` headers from that module.
64
65	### Include Paths
66
67	```csharp
68	// Expose extra paths to modules that depend on you
69	PublicIncludePaths.Add(Path.Combine(ModuleDirectory, "Public/Interfaces"));
70
71	// Expose extra paths only to this module's own source
72	PrivateIncludePaths.Add(Path.Combine(ModuleDirectory, "Private/Helpers"));
73	```
74
75	UBT automatically adds `Public/` and `Private/` — you rarely need to set these manually unless you have nested subdirectory headers you want to import without path prefixes.
76
77	### API Export Macro
78
79	UBT generates `MODULENAME_API` from the module's directory name, uppercased. Any class, function, or variable that must be visible across DLL boundaries needs this macro:
80
81	```cpp
82	// Public/MyClass.h
83	#pragma once
84	#include "CoreMinimal.h"
85
86	class MYMODULE_API FMyClass
87	{
88	public:
89	void DoSomething();
90	};
91
92	// Standalone exported function
93	MYMODULE_API void MyFreeFunction();
94	```
95
96	Missing `MYMODULE_API` on a class that another module references causes "unresolved external symbol" linker errors.
97
98	### PCH and IWYU
99
100	```csharp
101	// UE5 recommended — each file includes exactly what it uses
102	PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
103	bEnforceIWYU = true;
104
105	// Legacy — one monolithic PCH (avoid for new modules)
106	PCHUsage = PCHUsageMode.UseSharedPCHs;
107	```
108
109	With IWYU, every `.cpp` file includes its own `.h` first, then only what it directly uses:
110
111	```cpp
112	// Private/MyClass.cpp
113	#include "MyClass.h" // own header first
114	#include "Engine/Actor.h" // only includes this file directly uses
115	```
116
117	### Compiler Flags
118
119	```csharp
120	// C++ exceptions — disable unless third-party code requires them
121	bEnableExceptions = false;
122
123	// Runtime type information — disable unless using dynamic_cast
124	bUseRTTI = false;
125
126	// Third-party static libraries shipped with the engine
127	AddEngineThirdPartyPrivateStaticDependencies(Target, "zlib", "OpenSSL");
128	```
129
130	---
131
132	## Target.cs
133
134	Located at `Source/ProjectName.Target.cs` (and `Source/ProjectNameEditor.Target.cs`).
135
136	```csharp
137	// Source/MyGame.Target.cs
138	using UnrealBuildTool;
139	using System.Collections.Generic;
140
141	public class MyGameTarget : TargetRules
142	{
143	public MyGameTarget(TargetInfo Target) : base(Target)
144	{
145	Type = TargetType.Game;
146	DefaultBuildSettings = BuildSettingsVersion.Latest;
147	IncludeOrderVersion = EngineIncludeOrderVersion.Latest;
148
149	// All game modules that UBT should compile
150	ExtraModuleNames.AddRange(new str

People who liked this also viewed

6 picks

Type