빌드 프로세스 이해하기 (솔루션 구조 내 주요 폴더, 빌드 설정 이해하기,전체 솔루션 빌드 vs 부분 빌드, 빌드 전후 체크 포인트,빌드 문제 해결하기)

 

솔루션 구조 내 주요 폴더

 

IDE 상에서 보여지는 폴더 구조와 실제 프로젝트의 폴더 구조가 다르다

  • 프로젝트 폴더들이 계층적으로 표시되는데, 실제 Windows 탐색기에서 보았던 프로젝트 폴더 구조와는 조금 다를 수 있습니다.
  • IDE 가 빌드와 관리를 편하게 하기 위해서, 일종의 가상 형태로 구조를 재구성.

 

솔루션 구조 내 Root 폴더들: Engine, Games, Programs, Rules, Visualizers

 

Engine 폴더

  • 언리얼 엔진 자체 소스 코드와 리소스가 담긴 곳입니다.
  • 에디터 작동, 엔진 코어 관련 코드가 포함되어 있어서 엔진 수정시 들어오는 폴더

 

Games (중요)

  • 우리가 만든 프로젝트 코드가 모두 들어 있습니다.
  • 내부에는 Source, Config, .uproject 파일 등이 있으며, C++로 작성하는 게임 로직을 이 폴더에서 가장 많이 다루게 됩니다.

Programs 

  • 엔진 동작에 필요한 유틸리티 프로그램이나 서버 모듈이 담겨 있습니다.
  • 외부 프로그램들이 담겨있습니다.

Rules

  • 엔진과 게임 등 각 모듈의 빌드 규칙을 정의해 놓은 파일들이 모여 있습니다.
  • 모듈 의존성, 플러그인 활성화 여부, 빌드 대상 등을 제어합니다.

Visualizers 

  • Visual Studio 디버거에서 언리얼 엔진의 복잡한 자료구조 (예: FVector, FString)를 보다 읽기 쉽게 시각화할 수 있도록 도와주는 설정 파일이 들어 있습니다.

프로젝트 루트 폴더 (Games / ProjectName)

  • 이 폴더가 “프로젝트 루트”이며, 게임 개발에 필요한 모든 리소스와 설정 파일이 이곳에 모여 있습니다
    • Cpp, Header files...

프로젝트 루트 폴더 주요 구성 요소

  • Config
    • .ini 파일을 통해 에디터와 게임의 초기 상태를 지정합니다.
      • DefaultEditor.ini: 에디터 환경 설정 (뷰포트, UI 등)
      • DefaultEngine.ini: 엔진 전반 설정 (렌더링, 네트워킹 등)
      • DefaultGame.ini: 게임플레이 관련 설정 (게임 모드, 플레이어 컨트롤러 클래스 등)
      • DefaultInput.ini: 키보드·마우스·패드 등의 기본 입력 바인딩
  • Source
    • 실제 C++ 소스 코드(.cpp, .h)가 들어 있습니다.
    • 최초 프로젝트 생성 시에는 프로젝트명.cpp, 프로젝트명.h 등 최소 파일만 있지만, 새 클래스를 만들수록 점차 늘어납니다.
    • 빌드 설정 관련 주요 파일도 포함됩니다.
      • 프로젝트명.Build.cs: 해당 프로젝트에 필요한 모듈, 라이브러리, 종속성 등을 정의
      • 프로젝트명.Target.cs, 프로젝트명Editor.Target.cs: 각각 게임 실행용, 에디터용 빌드 방식을 정의
  • 프로젝트명.uproject
    • 언리얼 에디터에서 이 파일을 열면 프로젝트를 직접 실행할 수 있습니다.
    • 에디터는 이 파일을 통해 “어떤 콘텐츠와 설정을 불러올지”를 판단합니다.

 

 

 빌드 설정 이해하기

C++ 코드 빌드의 목적

  • C++ 코드를 수정했다면, 이를 컴파일 (Compile) + 링크 (Link) 해 “동적 라이브러리 (DLL)”로 만들어야 합니다.
  • 생성된 DLL은 언리얼 에디터가 실행될 때 자동으로 로드되며, 이를 통해 수정된 게임 로직 (함수, 클래스 등)이 에디터와 게임에서 즉시 반영됩니다.

DLL(Dynamic-Link Library, 동적 연결 라이브러리) 은 여러 프로그램이 공통으로 사용하는 함수, 데이터, 리소스를 모아둔 파일입니다. 실행 파일(EXE)에 코드를 모두 포함시키지 않고 별도로 분리하여, 프로그램 실행 중에 필요할 때만 불러와(동적으로 연결하여) 사용합니다.

 

빌드 구성 및 플랫폼 확인

 

빌드 구성 (Configuration) 종류: DebugGame, DebugGame Editor, Development, Development Editor, Shipping

  • Debug / DebugGame: 최적화를 비활성화하여 중단점(Breakpoints)을 통한 상세한 버그 추적 및 변수 검사가 가능합니다.  
    • DebugGame
      • 게임 로직만 디버그 정보를 포함하고, 엔진은 최적화된 상태로 빌드합니다.
      • 언리얼 에디터 없이, 독립된 실행 파일 환경에서 게임 로직을 디버깅할 때 사용됩니다. 엔진 코드는 디버깅이 제한적이며, 게임 로직만 효과적으로 디버깅 가능합니다.
    • DebugGame Editor
      • 에디터 환경에서 게임 로직을 디버그하기 편한 설정입니다.
      • 에디터 플레이 중에 C++ 로직을 추적하거나 브레이크포인트를 걸어볼 수 있습니다.

 

  • Development (기본값): 최적화와 디버그 심벌을 적절히 타협하여 일반적인 개발 및 에디터 작업에 사용됩니다.
    • Development
      • 디버그 정보를 최소화해 실행 속도를 높인 개발용 빌드입니다.
      • 독립 실행 파일 환경 테스트·개발 단계에서 주로 쓰입니다.
    • Development Editor
      • 에디터에서도 개발·테스트를 원활히 할 수 있도록 구성된 빌드 모드입니다.
      • Live Coding 사용 시나리오와 궁합이 좋고, 초·중급자들이 자주 사용합니다.
      • 본 강의에서도 기본 모드로 활용합니다. 

 

  • Shipping
    • 최종 사용자에게 배포할 때 사용하는 릴리스 빌드입니다.
    • 디버그 정보를 제거하고, 성능 최적화가 극대화됩니다.
더보기

! 주의 할점 !

 

언리얼 엔진(Unreal Engine)에서 Shipping 빌드를 하면 기본적으로 디버그 관련 요소(로그, 덤프 파일, 어설션)가 모두 제거되거나 최적화됩니다.
아래 주요 차이점과 주의사항을 반드시 확인해야 합니다.
 
1. 로그(Log) 및 어설션(check) 비활성화
Shipping 빌드에서는 성능 최적화를 위해 PrintString이나 UE_LOG 같은 로그가 기록되지 않으며, C++ 코드의 check() 매크로도 실행되지 않습니다.
  • 주의: 개발 중에 쓴 check(Pointer != nullptr); 같은 코드가 Shipping에서는 아예 무시되므로, 릴리즈 빌드에서 널 포인터 에러가 발생해 크래시가 날 수 있습니다. 안전한 런타임 체크는 check() 대신 if문이나 ensure()를 사용해야 합니다. 

 

2. 콘솔 명령어(Console Command) 차단
Shipping 빌드에서는 화면에 콘솔 창을 띄우거나 stat fps, stat gpu 같은 통계(Stats) 명령어를 사용할 수 없습니다.
  • 주의: 게임 내 설정을 위한 콘솔 명령어를 사용하는 UI 버튼이 있다면 작동하지 않을 수 있습니다. 
 
3. 코드 최적화로 인한 디버깅 한계
Shipping 빌드 시 컴파일러가 코드를 고도로 최적화(코드 인라인화, 변수 레지스터 할당 등)하므로, Visual Studio에서 프로세스를 연결(Attach)해도 코드 흐름을 정확히 따라가기 어렵습니다. 
 
4. 에디터와 다른 동작 (타이밍 이슈)
에디터 환경(PIE)에서는 잘 작동하던 로직이 Shipping 빌드에서는 다르게 동작하는 경우가 많습니다. 
  • 이유: 데이터 로딩 속도나 렌더링 최적화 등으로 인해 실행 타이밍이 달라지기 때문입니다. 특히 멀티플레이어 환경이나 비동기 로딩을 사용하는 경우 릴리즈 환경에서만 발생하는 버그가 생길 수 있습니다.

Tip: Shipping 빌드에서 크래시(Crash) 추적하기

Shipping 빌드에서만 발생하는 치명적인 크래시를 분석하려면, 패키징 설정(Project Settings)에서 [Include Debug Files in Shipping Builds] 옵션을 켜고 빌드하여 .pdb (디버그 심볼) 파일을 확보해 두어야 합니다. 이 파일과 크래시 덤프(.dmp) 파일이 있어야 릴리즈 빌드의 크래시 원인을 역추적할 수 있습니다.

플랫폼 (Platform) 설정

  • 기본적으로 Win64가 선택되어 있으며, 이는 Windows 64비트 환경을 의미합니다.
  • 모바일 (Android, iOS), 콘솔 (PS, Xbox 등)로 빌드하려면 해당 플랫폼용 SDK를 추가로 설치해야 합니다.

전체 솔루션 빌드 vs 부분 빌드

 

  • 기존 C/C++ 에서의 빌드 과정: 파일 수정 -> 빌드 (컴파일 + 링) -> DLL 파일 생성
  • 언리얼에서의 빌드 과정: 파일 수정 -> 빌드 (컴파일 + 링) -> DLL 파일 생성 -> 언리얼 에디터
    • 즉 언리얼에서 그 DLL 파일을 가져와서 실행 하는 과정이 하나 더 추가됨
  • 언리얼 C++ 프로젝트는 “전체 솔루션 빌드”와 “부분 빌드”로 나누어 빌드할 수 있습니다.

 

전체 솔루션 빌드 

전체 솔루션 빌드 (VS Stuiod 기준 단축키: Ctrl + Shift + B)

 

  • 엔진, 유틸리티, 게임 등 모든 모듈을 통째로 빌드합니다.
  • 첫 빌드나 엔진 소스를 수정했을 때, 또는 엔진 전체 파일이 필요한 경우에 사용합니다.
  • 프로젝트 규모가 크면 시간이 오래 걸릴 수 있습니다.

 

 

부분 빌드

  • Solution Explorer에서 프로젝트 (예: ProjectName)를 우클릭 → Build Selected Projects
  • 엔진이나 다른 모듈을 제외하고, 게임 프로젝트 코드만 빠르게 빌드합니다.
  • 일반적으로 C++ 로직만 수정했다면 이 방법을 쓰는 것이 효율적입니다.전체 솔루션 빌드 vs. 부분 빌드
    •  

 

빌드 전후 체크 포인트

 

빌드 시작 전

  • 언리얼 에디터는 가급적 종료하고 빌드하는 편이 안전합니다.
  • 에디터가 실행 중이면 수정된 DLL을 교체하지 못해 빌드 에러가 발생할 수 있습니다.

빌드 진행

  • 첫 빌드 (전체 솔루션 빌드)는 엔진 모듈까지 모두 새로 컴파일하므로 오래 걸릴 수 있지만, 이후에는 변경된 소스만 컴파일해서 빌드 시간이 크게 단축됩니다.
  • 경고 (Warning)나 에러 (Error)가 뜨면 Error List 창에서 구체적인 원인을 확인할 수 있습니다.

빌드 결과

  • “Build completed” 메시지가 나오면 정상 빌드된 것입니다.
  • 빌드 후, 프로젝트 폴더의 Binaries/Win64 폴더 내에 UnrealEditor-프로젝트명.dll 등이 새로 생성됩니다.
  • 이제 언리얼 에디터를 실행하면, 이 DLL을 로드해 수정된 로직이 적용됩니다.

VS Studio 의 경우 (Rider는 안해도됨) 빌드 후 실행 대상 설정

Solution Explorer에서 UE5 프로젝트 (ProjectName)을 우클릭하고, Set as Startup Project를 선택하세요.

  • 이렇게 하면, 디버깅 시 실행될 기본 프로젝트로 설정됩니다.
  • UE5 에디터와 함께 실행하거나, Visual Studio의 디버깅 도구를 사용할 때 편리합니다.
  • 이후 F5 (Start Debugging) 또는 Debug → Start Debugging을 선택해 UE5 에디터를 실행할 수 있습니다.
  • 디버깅 실행 상태를 종료하고 싶다면, 언리얼 에디터 상에서 종료를 하거나, Visual Studio에서 Shift + F5를 누르면 에디터가 종료됩니다.
⚠️ 선택하지 않으면 발생하는 문제
  • UE5 솔루션(.sln)에는 내가 만든 게임 프로젝트(SpartaProject) 외에도 언리얼 엔진 소스 코드 프로젝트(UE5)가 함께 포함되어 있습니다.
  • 기본값으로 UE5 프로젝트가 시작 프로젝트로 설정되어 있으면, F5 키를 눌렀을 때 게임이 아닌 엔진 자체가 단독으로 실행되거나 컴파일 에러가 발생할 수 있습니다.

빌드 문제 해결하기

변경 사항 미반영 문제란?

  • C++ 코드를 수정하고 빌드를 완료 하였음에도 불구하고, 언리얼 에디터에서 반영이 안 되는 경우가 있습니다.
  • 빌드 캐시 문제, 프로젝트 설정 문제, 파일 경로 오류 등 다양한 원인으로 발생할 수 있습니다.
    • 컴파일 대상 누락: IDE 혹은 엔진이 수정된 소스를 인식 못 해 빌드 대상에서 누락됨
    • DLL 교체 문제: 언리얼 에디터가 실행 중이거나 DLL 파일이 다른 프로세스에 의해 사용 중인 경우, 새로 빌드된 DLL 파일이 교체되지 않는 문제
    • 캐시 문제: 이전 빌드 결과물이 남아 새 빌드 결과를 덮어씌우지 못함
    • 파일 경로 문제: 헤더 파일 경로나 플러그인 설정이 잘못되어 컴파일에 포함되지 않음

 

단계별 해결 가이드

  1. 언리얼 에디터와 IDE 종료
    • 실행 중인 프로세스들이 빌드 파일을 잠글 수 있으므로, 모두 끄고 새로 시작하는 것이 좋습니다.
  2. 프로젝트 폴더에서 Intermediate, DerivedDataCache, Saved 폴더 삭제
    • 이 폴더들은 빌드 캐시 및 임시 데이터를 담고 있습니다.
    • 삭제 후 다시 빌드하면 새로 생성되어, 잘못된 캐시로 인한 오류를 해결할 수 있습니다.
  3. .uproject 파일을 우클릭 → “Generate Visual Studio project files”
    • 솔루션(.sln) 파일과 프로젝트 설정을 재생성하여, 누락되었거나 꼬인 구성을 복구합니다.
    • JetBrains Rider에서는 탐색기의 .uproject 우클릭 메뉴가 직접 지원되지 않으므로, 에디터 내장 기능을 사용해 프로젝트 파일을 갱신해야 합니다. Rider의 솔루션 탐색기에서 프로젝트 루트를 우클릭 후 Advanced | Refresh Rider Uproject project를 선택하면 됩니다
  4. IDE 에서 클린 빌드 수행
    • 새로 생성된 솔루션 (.sln 파일)을 IDE에서 열고 다음을 수행
      • Build → Clean Solution으로 기존 빌드 산출물을 정리
      • Build → Build Solution으로 프로젝트 재빌드
    • 에러가 난다면 Output 창과 Error List를 확인해 원인을 파악하고 수정합니다.
  5. 언리얼 에디터 다시 실행
    • 에디터를 다시 실행해 코드 변경 사항이 반영되었는지 확인합니다.
    • 여전히 문제가 해결되지 않는다면, 프로젝트 내 Saved/Logs 폴더에 있는 로그 파일을 열어 구체적인 에러 메시지를 확인하거나, 엔진 버전 및 프로젝트 설정을 점검해보세요.

 

 

Conclustion

 

  • 솔루션 구조 내 Root(주요) 폴더들: Engine, Games, Programs, Rules, Visualizers
  • 프로젝트 루트 폴더 주요 구성 요소: Config, Source, 프로젝트명.uproject
  • 빌드 구성 (Configuration) 종류: DebugGame, DebugGame Editor, Development, Development Editor, Shipping
  • 전체 솔루션 빌드 vs 부분 빌드

 

추천

 

[페이지] Unreal Engine | 언리얼 엔진

 

 

저작자표시 동일조건 (새창열림)
  • hELLO · Designed By 정상우.v4.10.6

    • 티스토리툴바