Unreal Build.cs 모듈 의존성: Public, Private, Include-only, Dynamic

먼저 구분할 네 가지 축#

Public이라는 단어가 여러 위치에서 등장하지만 모두 같은 기능은 아니다.

예를 들어 header를 Public/에 두었다고 그 class의 non-inline function이 자동으로 DLL 밖에 export되지는 않는다. 반대로 PublicDependencyModuleNames에 module을 추가해도 해당 module의 header가 source에 자동으로 #include되지는 않는다.

권장 module directory 구조#

Unreal Engine Modules 문서는 일반 C++ module을 다음처럼 나누도록 안내한다.

1
Source/
2
└─ Feature/
3
   ├─ Feature.Build.cs
4
   ├─ Public/
5
   │  └─ Feature/
6
   │     └─ FeatureService.h
7
   └─ Private/
8
      ├─ FeatureModule.cpp
9
      └─ Feature/
10
         └─ FeatureService.cpp

• Public/: 이 module에 의존하는 다른 module이 include할 공개 header
• Private/: 현재 module 안에서만 사용할 header와 모든 cpp
• Feature.Build.cs: UBT가 target graph를 만들 때 읽는 compile·link 규칙

이는 C++ class member의 public, private, protected와 무관하다. Private/ header에 public class가 있어도 다른 module의 include surface에는 노출되지 않는다.

다섯 가지 ModuleRules 목록#

ModuleRules에서는 아래 목록을 주로 사용한다.

여기서 “public compile 환경”은 단순 include directory 하나가 아니다. 대상 module이 공개한 include path, system include, public definition 같은 compile 정보를 포함한다. DependencyModuleNames는 이 compile 환경까지 이미 가져오므로 같은 module을 IncludePathModuleNames에도 중복해서 넣지 않는다.

세 module로 보는 전파 범위#

다음 graph에서 Feature는 공개 data contract에는 SharedTypes를 노출하고, 구현에서만 Json을 쓴다. 선택 backend는 interface만 compile하고 runtime에 load한다.

Consumer가 Feature의 Public header를 compile할 때 SharedTypes의 public compile 환경은 도달하지만 Json은 전파되지 않는다. OptionalBackend와는 정상 link edge가 없고, 실제 사용 시점의 load가 별도로 필요하다.

1
#pragma once
2

3
#include "SharedTypes/SharedFeatureOptions.h"
4

5
class FEATURE_API FFeatureService
6
{
7
public:
8
    explicit FFeatureService(FSharedFeatureOptions InOptions);
9

10
private:
11
    FSharedFeatureOptions Options;
12
};

1
PublicDependencyModuleNames.AddRange(
2
    new[]
3
    {
4
        "Core",
5
        "SharedTypes",
6
    }
7
);

1
#pragma once
2

3
#include "Containers/UnrealString.h"
4
#include "Containers/StringView.h"
5

6
class FEATURE_API FFeatureParser
7
{
8
public:
9
    bool Parse(FStringView Text, FString& OutError);
10
};

1
#include "Feature/FeatureParser.h"
2

3
#include "Dom/JsonObject.h"
4
#include "Serialization/JsonReader.h"
5
#include "Serialization/JsonSerializer.h"

1
PrivateDependencyModuleNames.Add("Json");

1
class FJsonObject;
2

3
class FEATURE_API FFeatureInspector
4
{
5
public:
6
    void Inspect(const FJsonObject& Object);
7
};

현실적인 Build.cs 예제#

1
using UnrealBuildTool;
2

3
public class Feature : ModuleRules
4
{
5
    public Feature(ReadOnlyTargetRules Target) : base(Target)
6
    {
7
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
8

9
        PublicDependencyModuleNames.AddRange(
10
            new[]
11
            {
12
                "Core",
13
                "SharedTypes",
14
            }
15
        );
16

17
        PrivateDependencyModuleNames.AddRange(
18
            new[]
19
            {
20
                "CoreUObject",
21
                "Engine",
22
                "Json",
23
            }
24
        );
25
    }
26
}

이 예제의 CoreUObject와 Engine이 항상 Private라는 뜻은 아니다. Feature의 Public class가 UObject나 AActor를 상속하거나 Public header의 reflected declaration이 해당 module을 요구한다면 Public로 이동해야 한다. Build.cs snippet을 복사하기보다 실제 Public include surface를 기준으로 분류한다.

선택 module을 runtime에 load하기#

OptionalBackend의 interface header만 Private 구현에서 compile하고, backend가 있을 때 load하려면 두 목록을 함께 사용한다.

1
PrivateIncludePathModuleNames.Add("OptionalBackend");
2
DynamicallyLoadedModuleNames.Add("OptionalBackend");

1
#include "IOptionalBackendModule.h"
2
#include "Modules/ModuleManager.h"
3

4
IOptionalBackendModule* TryLoadOptionalBackend()
5
{
6
    return FModuleManager::LoadModulePtr<IOptionalBackendModule>(
7
        FName(TEXT("OptionalBackend"))
8
    );
9
}

LoadModulePtr은 module을 찾아 load하고 StartupModule을 호출하며, 찾지 못하면 nullptr을 반환한다. 필수 backend라면 LoadModuleChecked로 invariant를 표현할 수 있지만, 사용자 설치나 platform에 따라 없을 수 있는 선택 기능에는 null을 처리한다.

이 pattern에는 추가 조건이 있다.

1. interface header가 link symbol 없이 사용할 수 있도록 설계되어야 한다.
2. target이 해당 module을 build할 수 있어야 한다.
3. plugin module이라면 .uplugin 또는 .uproject에서 plugin dependency가 enable되어야 한다.
4. descriptor의 Type, platform allow/deny 조건, LoadingPhase가 현재 target과 맞아야 한다.
5. unload를 지원한다면 가져온 pointer와 delegate lifetime을 module보다 길게 보관하지 않는다.

DynamicallyLoadedModuleNames는 “항상 별도 DLL”이라는 뜻도 아니다. monolithic target에서는 module code가 하나의 executable에 compile될 수 있지만 FModuleManager가 정적으로 등록된 initializer로 module lifetime을 관리한다.

외부 vendor DLL의 delay load와 packaging은 다른 기능이다. 일반적으로 PublicAdditionalLibraries, PublicDelayLoadDLLs, RuntimeDependencies를 검토하며, Unreal module용 DynamicallyLoadedModuleNames로 third-party binary staging을 대신하지 않는다.

Public folder와 MYMODULE_API는 별개다#

다른 module이 header를 찾더라도 modular build에서 구현 symbol이 export되지 않으면 unresolved external이 발생한다.

1
class FEATURE_API FFeatureService
2
{
3
public:
4
    void Start();
5
};

Module API Specifiers는 FEATURE_API 같은 macro를 build 상황에 따라 다음처럼 바꾼다.

• module 자체를 modular mode로 compile할 때: export
• 다른 module이 import할 때: import
• monolithic build일 때: 빈 macro

그래서 Shipping monolithic build만 성공하고 Editor DLL build에서 link error가 나는 코드가 생길 수 있다. Public folder, Public dependency, API macro를 각각 확인해야 한다.

UCLASS(MinimalAPI)는 class type 정보를 제한적으로 export하는 선택지다. class가 다른 module에서 보인다고 non-inline method가 모두 외부 호출 가능해지는 것은 아니다. 외부 호출이 필요한 method에는 적절한 module API export가 필요하다.

IWYU와 self-contained header#

Private dependency를 늘리거나 줄이는 것만으로 include hygiene가 완성되지는 않는다. IWYU에서는 아래 원칙을 따른다.

1. 모든 header는 자신이 필요한 header를 직접 include한다.
2. cpp는 대응하는 자신의 header를 먼저 include한다.
3. source에서 PCH header를 직접 include하지 않는다.
4. monolithic Engine.h, UnrealEd.h 대신 필요한 header를 include한다.

PCHUsageMode.UseExplicitOrSharedPCHs는 PCH를 최적화 layer로 유지하면서 source가 우연히 PCH의 transitive include에 기대지 않도록 돕는다. 그러나 unity build와 shared PCH에서는 누락된 dependency가 가려질 수 있다.

변경 뒤에는 최소한 다음을 검증한다.

• consumer test module이 대상 Public header 하나만 include해도 compile되는가?
• cpp의 첫 include가 대응 header일 때 compile되는가?
• non-unity, PCH 비활성 test에서도 누락된 direct include가 드러나지 않는가?
• 제거한 Public dependency의 type이나 definition이 Public header에 남아 있지 않은가?
• modular Editor build와 monolithic target에서 모두 symbol export가 올바른가?

UE 5.2에는 Clang 기반 IWYU 도구 연동도 추가됐지만, tool을 실행하는 것과 IWYU 방식으로 header를 작성하는 것은 구분한다. UE 4.27에서도 같은 self-contained header 원칙과 non-unity/PCH-off 검증이 유효하다.

Runtime module과 Editor module의 방향#

.Build.cs는 compile·link edge를 정의하고, .uplugin 또는 .uproject descriptor는 module의 activation과 host type을 정의한다. 둘 중 하나만 맞춰서는 충분하지 않다.

1
InventoryEditor  ──depends on──▶  InventoryRuntime
2
InventoryRuntime ──must not───▶  InventoryEditor

Editor Modules 안내는 runtime 기능과 editor customization을 별도 module로 나누고 Editor→Runtime 방향으로 의존하도록 권장한다. Runtime module이 UnrealEd, details customization 같은 Editor module을 참조하면 Shipping target에서 build할 수 없다.

Plugins 문서의 계층 규칙도 지켜야 한다. project module은 Engine module을 사용할 수 있지만 Engine plugin/module이 특정 project module에 아래 방향으로 의존할 수는 없다. plugin enable 여부와 module Type·LoadingPhase는 dependency 목록으로 우회할 수 없다.

순환 의존성은 Private로 바꿔도 해결되지 않는다#

A가 B를 Private로, B가 A를 Private로 선언해도 link graph의 cycle은 그대로다. CircularlyReferencedDependentModules는 legacy 용도이므로 새 의존성에 사용하지 않는다.

새 cycle을 발견하면 다음 순서로 구조를 바꾼다.

• 양쪽이 공유하는 DTO·interface를 더 낮은 SharedTypes module로 추출한다.
• Public header의 concrete type을 forward declaration이나 작은 interface로 줄인다.
• 직접 호출을 delegate, event, subsystem 또는 IModularFeatures 같은 registration boundary로 바꾼다.
• 선택 backend를 include-only interface와 runtime dynamic load 뒤로 이동한다.
• Runtime과 Editor 구현을 별도 module로 분리해 dependency 방향을 한쪽으로 만든다.

결정 순서#

새 dependency를 추가할 때 다음 질문을 위에서부터 확인하면 된다.

1. 대상 type이 현재 module의 Public header를 compile하는 데 필요한가?
   • 필요하면 PublicDependencyModuleNames.
2. Private header 또는 cpp에서만 compile·link하면 되는가?
   • 그렇다면 PrivateDependencyModuleNames.
3. 정상 import/link 없이 interface header의 compile 환경만 필요한가?
   • 공개 interface면 PublicIncludePathModuleNames, 구현 전용이면 PrivateIncludePathModuleNames.
4. runtime에 명시적으로 load할 Unreal module인가?
   • DynamicallyLoadedModuleNames와 descriptor/FModuleManager load를 함께 설계.
5. 다른 DLL에서 non-inline symbol을 호출하는가?
   • Public folder와 별도로 MYMODULE_API export 확인.
6. plugin activation, module type, loading phase, platform 조건이 맞는가?
7. consumer module, non-unity/PCH-off, modular/monolithic target에서 검증했는가?

핵심은 “header냐 cpp냐”보다 누가 이 compile·link 계약을 소비하는가이다. 공개 계약에 필요한 dependency만 Public로 전파하고 구현 세부는 Private에 가둔다. compile-only와 dynamic load가 정말 필요한 드문 경우에는 두 단계가 자동으로 연결되지 않는다는 점을 명시적으로 처리한다.

참고 자료#

• Epic Games: Unreal Engine Modules
• Epic Games: Module Properties
• Epic Games: Include What You Use
• Epic Games UE 4.27: Include What You Use
• Epic Games: Module API Specifiers
• Epic Games: Plugins
• Epic Games: Setting up Editor Modules
• Epic Games: FModuleManager
• Epic Games: FModuleManager::LoadModulePtr
• Epic Games UE 5.2 release notes