모듈 프로퍼티

모듈 은 언리얼 엔진(UE) 의 기본 구성 요소입니다. 엔진은 대규모 모듈 컬렉션으로 구현되며, 게임은 자체 모듈을 제공하여 이를 확장합니다. 각 모듈은 함수 기능 세트를 캡슐화하고 다른 모듈에서 사용할 퍼블릭 인터페이스 및 컴파일 환경(매크로, 인클루드 경로 등)을 제공할 수 있습니다.

모듈은 확장자가 .build.cs 인 C# 소스 파일을 통해 선언되며, 프로젝트의 Source 디렉터리에 저장됩니다. 모듈에 속한 C++ 소스 코드는 .build.cs 파일과 함께 저장되거나 서브디렉터리에 저장됩니다. 각 .build.cs 파일은 ModuleRules 베이스 클래스에서 파생된 클래스를 선언하고 생성자에서 어떻게 빌드되어야 하는지를 제어하는 프로퍼티를 설정합니다. 이러한 .build.cs 파일은 언리얼 빌드 툴(UBT) 로 컴파일되고 전체 컴파일 환경을 결정하도록 구성됩니다.

.build.cs 파일의 일반적인 구조는 다음과 같습니다.

	using UnrealBuildTool;
	using System.Collections.Generic;
	public class MyModule : ModuleRules
	{
		public MyModule(ReadOnlyTargetRules Target) : base(Target)
		{
			// 여기에 프로퍼티 및 세팅이 들어갑니다
		}
	}

Copy full snippet

using UnrealBuildTool; using System.Collections.Generic; public class MyModule : ModuleRules { public MyModule(ReadOnlyTargetRules Target) : base(Target) { // 여기에 프로퍼티 및 세팅이 들어갑니다 } }

읽기 전용 프로퍼티

$ IsPlugin (Boolean): 플러그인이 이 모듈을 포함하면 True를 반환합니다.

$ Logger (ILogger): 타깃 로거의 접근자입니다.

$ HasPackageOverride (Boolean): 이 모듈에 지정된 오버라이드 타입이 있을 경우 True를 반환합니다.

$ AutoSdkDirectory (String): 활성 호스트 플랫폼을 위한 AutoSDK 디렉터리입니다.

$ EngineDirectory (String): 현재 엔진 디렉토리입니다.

$ PluginDirectory (String): 이 플러그인을 포함하는 디렉터리의 프로퍼티입니다. 서드 파티 종속성에 경로를 추가할 때 유용합니다.

$ ModuleDirectory (String): 이 모듈을 포함하는 디렉터리의 프로퍼티입니다. 서드 파티 종속성에 경로를 추가할 때 유용합니다.

$ TestsDirectory (String): 모듈의 하위 레벨 테스트 디렉터리 'Tests'를 반환합니다.

$ IsVcPackageSupported (Boolean): 빌드 환경설정에 VcPkg가 지원되는지 여부를 반환합니다.

읽기/쓰기 프로퍼티

$ Type (ModuleType): 모듈의 타입입니다.

$ BinariesSubFolder (String): 다이내믹 링크 라이브러리(Dynamic-Link Library, DLL)를 빌드할 때 이 모듈을 배치할 Binaries/PLATFORM 폴더의 서브폴더입니다. TargetPlatform이나 ShaderFormat 모듈처럼 검색을 통해서 찾아지는 모듈에서만 사용해야 합니다. 트래킹에 FindModule을 사용하지 않으면 모듈을 찾을 수 없습니다.

$ PrivatePCHHeaderFile (String): 이 모듈에 대한 명시적 프라이빗 사전 컴파일된 헤더(Precompiled Header, PCH)입니다. 이 모듈이 공유 PCH를 사용하지 않음을 의미합니다.

$ SharedPCHHeaderFile (String): 이 모듈에서 제공하는 공유 PCH의 헤더 파일 이름입니다. 퍼블릭 C++ 헤더 파일에 대한 유효한 상대 경로여야 합니다. 여러 C++ 모듈에 포함된 헤더 파일에 대해서만 설정해야 합니다.

$ ShortName (String): 이 모듈의 중간 디렉터리와 파일에 대체 이름을 지정합니다. 경로 길이 제한에 도달했을 때 유용합니다.

$ bTreatAsEngineModule (Boolean): 이 모듈을 엔진 모듈(예: 엔진 정의 사용, PCH, DebugGame 환경설정에서 최적화가 활성화된 컴파일)로 취급해야 하는지 여부입니다. 생성된 규칙 어셈블리에 기반한 디폴트로 초기화됩니다.

$ bUseRTTI (Boolean): 런타임 타입 정보를 사용합니다.

$ bCodeCoverage (Boolean): 코드 커버리지 컴파일/링크 지원을 활성화합니다.

$ MinCpuArchX64 (Nullable): 지원하는 x64 플랫폼에서 SSE 또는 AVX 인트린직(intrinsic)을 사용하는 경우 컴파일러가 AVX 인스트럭션을 생성하도록 지시합니다. 이 프로퍼티를 활성화하면 PC 플랫폼의 최소 사양이 변경되며 그에 따른 실행 파일은 AVX 지원 없는 머신에서 충돌합니다.

$ bEnableBufferSecurityChecks (Boolean): 버퍼 보안 검사를 활성화합니다. 이 프로퍼티는 심각한 보안 위험을 방지하기 때문에 일반적으로 활성화해야 합니다.

$ bEnableExceptions (Boolean): 예외 처리를 활성화합니다.

$ bEnableObjCExceptions (Boolean): 오브젝트 C 예외 처리를 활성화합니다.

$ bEnableObjCAutomaticReferenceCounting (Boolean): 오브젝트 C ARC(Automatic Reference Counting)를 활성화합니다. True로 설정하면 이 모듈에 대해 공유 PCH를 사용하면 안 됩니다. 엔진은 단기적으로 ARC를 광범위하게 사용하지 않습니다. 이렇게 하지 않으면 공유 PCH가 컨슈머와 다른 플래그로 컴파일되었기 때문에 컴파일 오류가 발생합니다.

$ bWarningsAsErrors (Boolean): 모든 경고를 오류로 활성화할지 여부입니다. UE는 원래 대부분의 경고를 오류로 활성화하지만, 지원 중단 경고와 같은 일부 경고는 비활성화합니다.

$ bEnableUndefinedIdentifierWarnings (Boolean): #if 표현식에서 정의되지 않은 식별자를 사용하면 경고를 표시합니다.

$ bDisableStaticAnalysis (Boolean): 모든 스태틱 분석(clang, msvc, pvs-studio)을 비활성화합니다.

$ bStaticAnalyzerExtensions (Boolean): EspXEngine 플러그인을 사용하여 추가 분석 툴 확장 경고를 활성화합니다. MSVC에서만 지원됩니다. 자세한 내용은 C++ Core Guidelines 검사기 사용를 참조하세요. 기본적으로 많은 수의 경고가 추가됩니다. 활성화된 경우 StaticAnalyzerRulesets를 사용하는 것이 좋습니다.

$ StaticAnalyzerRulesets (HashSet): 경고를 필터링하는 데 사용해야 하는 스태틱 분석 툴 규칙 세트입니다. MSVC에서만 지원됩니다. 자세한 내용은 규칙 집합을 사용하여 실행할 C++ 규칙 지정를 참조하세요.

$ StaticAnalyzerCheckers (HashSet): 디폴트 대신 활성화할 스태틱 분석 툴 검사기입니다. Clang에서만 지원됩니다. 전체 목록은 Analyzer Checkers를 참조하세요. 또는 clang -Xclang -analyzer-checker-help 또는 실험단계 검사기 목록의 경우 clang -Xclang -analyzer-checker-help-alpha 를 실행하세요.

$ StaticAnalyzerDisabledCheckers (HashSet): 비활성화할 디폴트 스태틱 분석 툴 검사기입니다. 'StaticAnalyzerCheckers'가 채워진 경우 사용되지 않습니다. Clang에서만 지원됩니다. 디폴트 비활성화 검사기 'deadcode.DeadStores'와 'security.FloatLoopCounter'를 오버라이드합니다. 전체 목록은 Analyzer Checkers를 참조하세요. 또는 clang -Xclang -analyzer-checker-help 또는 실험단계 검사기 목록의 경우 clang -Xclang -analyzer-checker-help-alpha 를 실행하세요.

$ StaticAnalyzerAdditionalCheckers (HashSet): 활성화할 디폴트가 아닌 스태틱 분석 툴 검사기입니다. 'StaticAnalyzerCheckers'가 채워진 경우 사용되지 않습니다. Clang에서만 지원됩니다. 전체 목록은 Analyzer Checkers를 참조하세요. 또는 clang -Xclang -analyzer-checker-help 또는 실험적 체커 목록의 경우 clang -Xclang -analyzer-checker-help-alpha 를 실행하세요.

$ bMergeUnityFiles (Boolean): 빠른 컴파일을 위해 모듈 및 생성된 Unity 파일을 병합할지 여부입니다.

$ MinSourceFilesForUnityBuildOverride (Int32): 통합 빌드 전 이 모듈에서 해당 모듈에 대해 활성화되는 소스 파일 수입니다. -1 외의 값으로 설정하면 'MinGameModuleSourceFilesForUnityBuild'에서 제어하는 디폴트 세팅을 오버라이드합니다.

$ MinFilesUsingPrecompiledHeaderOverride (Int32): 0이 아닌 경우 'BuildConfiguration.MinFilesUsingPrecompiledHeader'를 오버라이드합니다.

$ NumIncludedBytesPerUnityCPPOverride (Int32): 0이 아닌 경우 'Target.NumIncludedBytesPerUnityCPP'를 오버라이드합니다.

$ bBuildLocallyWithSNDBS (Boolean): 모듈이 '#import'를 사용하여 SN-DBS로 컴파일할 때 로컬에서 빌드해야 합니다.

$ bEnableNonInlinedGenCppWarnings (Boolean): 일치하는 수동 작성 cpp 파일에 인라인될 수 있는 .gen.cpp 파일이 있는 경우 경고를 활성화합니다.

$ IsRedistributableOverride (Nullable): 이 모듈에 대한 재배포 오버라이드 플래그입니다.

$ bLegalToDistributeObjectCode (Boolean): 모듈에 대해 예를 들어 CarefullyRedist, NotForLicensees, NoRedist가 아닌 코드/종속성이 있는 경우에도 이 모듈의 출력을 공개적으로 배포할 수 있는지 여부입니다. 바이너리는 릴리즈하지만 소스는 릴리즈하지 않으려는 경우 이 프로퍼티를 사용해야 합니다.

$ AllowedRestrictedFolders (List): 제한된 폴더 이름을 전파하지 않고 이 바이너리를 컴파일할 때 참조하도록 허용되는 폴더 목록입니다.

$ AliasRestrictedFolders (Dictionary): 에일리어싱된 제한된 폴더 레퍼런스의 세트입니다.

$ IWYUSupport (IWYUSupport): 실행 시 소스 코드를 수정하기 위해 'IWYU(include what you see)'를 허용합니다. bEnforceIWYU가 true일 때 이 변수가 중요합니다.

$ bAddDefaultIncludePaths (Boolean): 모듈에 연결된 모든 디폴트 인클루드 경로를 추가할지 여부입니다(예: 'Source/Classes' 폴더, 'Source/Public' 아래의 서브 폴더).

$ bIgnoreUnresolvedSymbols (Boolean): 모듈에서 허상(예: 미해결 외부) 심볼을 무시할지 여부입니다.

$ bPrecompile (Boolean): 이 모듈을 사전 컴파일해야 하는지 여부입니다. 타깃에서 bPrecompile 플래그가 디폴트로 지정됩니다. 모듈이 사전 컴파일되지 않게 하려면 이 플래그를 지우세요.

$ bUsePrecompiled (Boolean): 이 모듈에서 사전 컴파일된 데이터를 사용해야 하는지 여부입니다. 설치된 어셈블리에서 생성된 모듈의 경우 항상 true입니다.

$ bAllowConfidentialPlatformDefines (Boolean): 이 모듈이 PLATFORM_XXXX 스타일 정의를 사용할 수 있는지 여부입니다. XXXX 는 비밀 플랫폼 이름입니다. 이 프로퍼티는 엔진이나 다른 공유 코드에서 #if PLATFORM_XXXX 블록 내부의 비밀 정보를 노출하지 않도록 하는 데 사용됩니다. 그러나 언리얼 엔진 사용자 게임 코드에서는 이를 허용하는 것이 좋습니다.

$ bAllowAutoRTFMInstrumentation (Boolean): AutoRTFMCompiler가 활성화된 경우에만 이 모듈에 대한 AutoRTFM 인스트루먼테이션을 활성화합니다.

$ PublicIncludePathModuleNames (List): 모듈의 퍼블릭 헤더가 액세스해야 하지만 '임포트' 또는 링크할 필요는 없는 헤더 파일과 모듈 이름의 목록(경로 필요 없음)입니다.

$ PublicDependencyModuleNames (List): 퍼블릭 종속성 모듈 이름의 목록(경로 필요 없음)입니다(자동으로 프라이빗/퍼블릭 인클루드 수행). 이러한 모듈은 퍼블릭 소스 파일에 필요한 모듈입니다.

$ PrivateIncludePathModuleNames (List): 모듈의 프라이빗 코드 파일이 액세스해야 하지만 '임포트' 또는 링크할 필요는 없는 헤더 파일과 모듈 이름의 목록(경로 필요 없음)입니다.

$ PrivateDependencyModuleNames (List): 프라이빗 종속성 모듈 이름 목록입니다. 프라이빗 코드는 이 모듈에 의존하지만 퍼블릭 인클루드 파일은 의존하지 않습니다.

$ CircularlyReferencedDependentModules (List): 레거시 목적으로만 있는 프로퍼티며, 새로운 코드에 사용해서는 안 됩니다. 순환 참조로 취급해야 하는 모듈 종속성의 목록입니다. 이러한 모듈은 퍼블릭 또는 프라이빗 종속 모듈 목록에 이미 추가되어 있어야 합니다.

$ PublicSystemIncludePaths (List): 시스템/라이브러리 인클루드 경로 목록입니다. 일반적으로 외부(서드 파티) 모듈에 사용됩니다. 헤더 종속성을 확인할 때 확인되지 않는 안정적인 퍼블릭 헤더 파일 디렉터리입니다.

$ PublicIncludePaths (List): 다른 모듈에 노출된 인클루드 파일의 모든 경로 목록입니다. ('Public' 폴더에서 모든 파일을 검색하기 때문에 현재는 필요하지 않은 세팅입니다).

$ InternalncludePaths (List): 다른 내부 모듈에 노출된 인클루드 파일의 모든 경로 목록입니다. ('Internal' 폴더에서 모든 파일을 검색하기 때문에 현재 필요하지 않은 세팅입니다).

$ PrivateIncludePaths (List): 이 모듈의 내부 인클루드 파일의 모든 경로 목록으로, 다른 모듈에 노출되지 않습니다('Private' 경로로 최소 1회 인클루드, 상대 경로를 피하려는 경우 인클루드 횟수가 늘어남).

$ PublicSystemLibraryPaths (List): 시스템 라이브러리 경로 목록입니다(.lib 파일의 디렉터리). 외부 (서드 파티) 모듈의 경우 대신 'PublicAdditionalLibaries'를 사용하세요.

$ PrivateRuntimeLibraryPaths (List): 런타임 시 라이브러리에 대한 검색 경로 목록입니다(예: .so 파일).

$ PublicRuntimeLibraryPaths (List): 런타임 시 라이브러리에 대한 검색 경로 목록입니다(예: .so 파일).

$ PublicAdditionalLibraries (List): 추가 라이브러리 목록입니다(확장자를 포함한 '.lib' 파일의 이름). 일반적으로 외부(서드 파티) 모듈에 사용됩니다.

$ DependenciesToSkipPerArchitecture (Dictionary>): 연결 시 무시할 종속성의 아키텍처별 목록이며(여러 아키텍처를 빌드할 때 유용하며 하나의 아키텍처에 하나의 lib만 필요함), 이를 사용하는 것은 툴 체인에 달려 있습니다.

$ PublicPreBuildLibraries (List): 추가 사전 빌드 라이브러리의 목록입니다(확장자를 포함한 .lib 파일의 이름). 일반적으로 아직 빌드 중인 추가 타깃에 사용되지만 TargetRules.PreBuildSteps 또는 TargetRules.PreBuildTargets 중 하나를 사용합니다.

$ PublicSystemLibraries (List): 사용할 시스템 라이브러리의 목록입니다. 일반적으로 이름을 통해 참조된 후 시스템 경로를 통해 찾을 수 있습니다. .lib 파일을 참조해야 할 경우 대신 PublicAdditionalLibraries를 사용하세요.

$ PublicFrameworks (List): XCode 프레임워크의 목록입니다(iOS 및 MacOS).

$ PublicWeakFrameworks (List): 약한 프레임워크의 목록입니다(OS 버전 트랜지션용).

$ PublicAdditionalFrameworks (List): 추가 프레임워크의 목록입니다. 일반적으로 Mac 및 iOS의 외부(서드 파티) 모듈에 사용됩니다.

$ AdditionalBundleResources (List): Mac 또는 iOS의 앱 번들에 복사해야 하는 추가 리소스 목록입니다.

$ TypeLibraries (List): 헤더를 생성해야 하는 타입 라이브러리의 목록입니다(Windows 전용).

$ PublicDelayLoadDLLs (List): 딜레이 로드 DLL 목록입니다. 일반적으로 외부(서드 파티) 모듈에 사용됩니다.

$ PrivateDefinitions (List): 이 모듈에 대한 프라이빗 컴파일러 정의입니다.

$ PublicDefinitions (List): 이 모듈에 대한 퍼블릭 컴파일러 정의입니다.

$ DynamicallyLoadedModuleNames (List): 런타임에 이 모듈에 필요할 수 있는 추가 모듈입니다.

$ RuntimeDependencies (RuntimeDependencyList): 런타임에 이 모듈이 의존하는 파일의 목록입니다. 이 파일은 타깃과 함께 스테이징됩니다.

$ AdditionalPropertiesForReceipt (ReceiptPropertyList): 빌드를 받을 때 추가할 추가 프로퍼티 목록입니다.

$ PrecompileForTargets (PrecompileTargetsType): 이 모듈을 사전 컴파일해야 하는 타깃입니다.

$ ExternalDependencies (List): 수정 시 makefile을 무효화하는 외부 파일입니다. 상대 경로는 .build.cs 파일을 기준으로 해석됩니다.

$ SubclassRules (List): 수정 시 makefile을 무효화하는 서브클래스 규칙 파일입니다.

$ bRequiresImplementModule (Nullable): 이 모듈이 IMPLEMENT_MODULE 매크로를 구현해야 하는지 여부입니다. 글로벌 오버로드를 수행하기 위해 IMPLEMENT_MODULE 매크로를 사용하기 때문에 대부분의 UE 모듈에는 이 프로퍼티가 필요합니다(예: 'GMalloc'에 포워딩하는 신규/삭제 연산자).

$ bValidateCircularDependencies (Boolean): 더 느린 빌드에서 허용 목록 순환 모듈 종속성 결과에 대해 순환 종속성의 유효성을 검사할지 여부입니다. 이 옵션은 비활성화하지 않는 것이 좋습니다. 허용 목록에 대해 항상 유효한 엔진 모듈의 경우 이 옵션은 무시됩니다.

$ CppStandard (Nullable): 이 모듈을 컴파일하는 데 사용할 표준입니다.

$ CStandard (Nullable): 이 모듈을 컴파일하는 데 사용할 표준입니다.

$ GenerateHeaderFuncs (List>>): 헤더 파일을 생성하기 위해 호출되는 하위 디렉터리 이름 및 함수 목록입니다. 하위 디렉터리 이름은 생성된 코드 디렉터리에 추가되어 헤더가 내부에 생성되는 새 디렉터리를 형성합니다.

$ ModuleSymbolVisibility (SymbolVisibility): 심볼의 비저빌리티를 제어합니다.

$ Name (String): 이 모듈의 이름입니다.

$ OverridePackageType (PackageOverrideType): 서로 다른 패키지 플래그가 설정되는 모듈의 오버라이드 타입입니다. 모듈이 플러그인의 일부인 경우 이미 .uplugin 파일에 설정되어 있기 때문에 사용할 수 없습니다.

$ OptimizeCode (CodeOptimization): 이 모듈의 코드가 최적화되어야 하는 상황입니다.

$ OptimizationLevel (OptimizationMode): 속도 및/또는 코드 크기에 대한 최적화 레벨의 미세 조정을 허용합니다. 이를 위해서는 프라이빗 PCH(또는 권장되지 않는 NoPCH)가 필요합니다.

$ PCHUsage (PCHUsageMode): 이 모듈의 사전 컴파일된 헤더 사용입니다.

$ DefaultBuildSettings (BuildSettingsVersion): 기본적으로 사용할 엔진 버전의 빌드 세팅입니다.

$ IncludeOrderVersion (EngineIncludeOrderVersion): 이 모듈을 컴파일할 때 사용할 인클루드 순서의 버전입니다. 명령줄 또는 모듈 규칙에서 -ForceIncludeOrder 를 통해 오버라이드될 수 있습니다.

$ bUseAVX (Boolean): 구버전: 지원하는 플랫폼에서 SSE 또는 AVX 인트린직(intrinsic)을 사용하는 경우 컴파일러가 AVX 인스트럭션을 생성하도록 지시합니다. 이 프로퍼티를 활성화하면 PC 플랫폼의 최소 사양이 변경되며 그에 따른 실행 파일은 AVX 지원 없는 머신에서 충돌합니다.

$ DeterministicWarningLevel (WarningLevel): 결정론적 경고를 처리하는 방식입니다(실험적).

$ ShadowVariableWarningLevel (WarningLevel): 섀도 변수 경고를 처리하는 방식입니다.

$ UnsafeTypeCastWarningLevel (WarningLevel): 안전하지 않은 묵시적 타입 형변환 경고를 처리하는 방식입니다(예: double->float 또는 int64->int32).

$ ModuleIncludePathWarningLevel (WarningLevel): 일반 모듈 포함 경로 유효성 검사 메시지를 처리하는 방식입니다.

$ ModuleIncludePrivateWarningLevel (WarningLevel): 프라이빗 모듈 포함 경로 유효성 검사 메시지를 처리하는 방식이며, 여기서 모듈은 프라이빗 헤더를 노출하는 포함 경로를 추가합니다.

$ ModuleIncludeSubdirectoryWarningLevel (WarningLevel): 불필요 모듈 서브 디렉터리 포함 경로 유효성 검사 메시지를 처리하는 방식입니다.

$ bUseUnity (Boolean): Unity 빌드가 활성화되었고 이 특정 모듈이 Unity로 빌드될 경우 이것을 사용하여 오버라이드할 수 있습니다. 'BuildConfiguration.cs'의 모듈별 환경설정을 사용하여 설정할 수 있습니다.

$ bEnforceIWYU (Boolean): PCHUsage가 ExplicitOrSharedPCH로 설정된 경우 'IWYU(include what you see)' 규칙을 적용합니다. 모놀리식 헤더(예: Engine.h, UnrealEd.h 등)가 사용될 경우 경고하고 먼저 소스 파일에 일치하는 헤더가 포함되어 있는지 확인합니다.

$ bLegacyPublicIncludePaths (Boolean): 이 모듈이 Public 폴더의 루트를 기준으로 다른 모듈에서 포함된 헤더에 적합한지 여부입니다. 이렇게 하면 컴파일러에 전달해야 하는 검색 경로의 수가 줄어들어, 퍼포먼스가 향상되고 컴파일러 명령줄 길이가 줄어듭니다.

$ bLegacyParentIncludePaths (Boolean): 이 모듈이 부모 디렉터리를 기준으로 다른 모듈에서 포함된 헤더에 적합한지 여부입니다. 이렇게 하면 컴파일러에 전달해야 하는 검색 경로의 수가 줄어들어, 퍼포먼스가 향상되고 컴파일러 명령줄 길이가 줄어듭니다.