언리얼 빌드 시스템 가이드

개요

---

언리얼 엔진을 커스터마이징하거나 플러그인같은 것들을 제작하기 위해, 가장 먼저 이해해야 할 것은 언리얼의 빌드 시스템입니다.

물론 언리얼 엔진의 공식 문서에는 [ 언리얼 빌드 시스템 ] 이라는 항목이 존재하지만, 각 주제들이 개별적으로 설명되고 있기 때문에, 처음 접하는 입장에서는 종합적으로 이해하기 어렵습니다.

저도 이런 부분때문에 고생을 많이 했고, 이번 기회에 제대로 정리를 해 볼 생각입니다. 모쪼록 이 문서가 많은 사람들에게 도움이 되었으면 합니다.

이 문서에서는 빌드시스템의 각 항목에 대한 세부적인 내용을 다루기 보다는, 전체적인 윤곽을 보여 주고 문제를 해결하기 위해서 어떤 문서를 찾아야 하는지에 대한 가이드를 제공하려고 합니다.

여러분이 이 문서를 읽고 나면, 다음과 같은 것들을 할 수 있어야 합니다. 만약 그렇지 못하다면 제가 글을 잘 못쓰거나 누락한 부분이 있는 거겠죠.

• 커스텀 빌드를 배포하기 위해서 소스 제어에 어떠한 것들을 등록해야 하는지 알 수 있습니다.
• GenerateProjectFiles.bat 를 어떠한 상황에서 사용하는지 알 수 있습니다.
• 언리얼 엔진의 프로젝트 구성에 대해 이해할 수 있습니다.
• 모듈의 의미를 이해하고 사용할 수 있습니다.
• 언리얼 엔진을 수정하고 배포할 수 있습니다.

이 문서는 "UnrealEngine 4.10.0-release" 와 윈도우즈 시스템을 기반으로 작성되었습니다.

참고로 이 문서에서는 자동화와 배포( automation & depolyment )에 대해서는 다루지 않습니다. 이건 빌드시스템과는 좀 다른 영역이라 나중에 기회가 되면 다루도록 하겠습니다.

공부하면서 정리한 거라서 잘못된 내용이 있을 수 있으므로, 이를 감안하고 보시기 바랍니다. 잘못된 내용들은 수정해 가도록 하겠습니다.

1. 소스 제어 - 기본 데이터 등록

---

언리얼 엔진의 소스를 받는 방법은 [ 언리얼 엔진 소스 코드 내려받기 ]에 나와 있습니다. 그런데 언리얼 엔진의 소스를 받고 나면 어떠한 것들을 소스 컨트롤에 등록해야 하는지 알기 어렵습니다. 어떤 파일들이 공유되어야 하고 어떤 파일들이 개인용 파일들인지 모르기 때문입니다. 뭘 올려야 하는지에 대한 설명도 제대로 없습니다.

언리얼 엔진의 소스를 받으면 다음과 같은 파일들이 생성됩니다.각각의 항목에 대한 자세한 내용은 [ 디렉토리 구조 ] 문서에 잘 나와 있습니다.

일단 소스를 받은 상황에서 아무 것도 하지 마시고, 1 번 항목을 제외하고는 통째로 소스 제어에 등록하시면 됩니다. 저는 git 을 안 쓰기 때문에 1번 항목을 지워버렸습니다.

2. Setup.bat

---

이제 Setup.bat 를 실행해서 의존성 파일들을 설치합니다. 1 번을 통해 소스 제어에 등록된 파일들을 다운로드받은 ( 프로그래머가 아닌 ) 작업자들도 반드시 이를 실행해야만 합니다.

나중에 자동화와 배포에 대해서 정리할 기회가 있으면 그 때 다시 언급하겠지만, 만약 작업자 머신에서 이 배치파일이 실행된 적이 없다면, 프로그래머가 열심히 바이너리를 배포해 놓아도 에디터에서 안드로이드같은 디바이스로 프로그램을 런칭시킬 수 없습니다( 물론 "Engine/Extras/AndroidWorks/Win64/AndroidWorks-1R1-windows.exe" 도 깔려 있어야겠죠. 여기에서는 자동화와 배포에 대한 주제를 다루지 않기 때문에 구체적인 언급은 피하겠습니다 ).

3. 소스 제어 - 의존성 파일 등록

---

이 과정을 통해서 생성된 파일들을 소스 제어에 등록하는 것은 취향( ? )의 문제로 보입니다. 만약 언리얼 빌드 시스템에 손을 댈 계획이라면 소스제어에 등록해야 하지만, 그렇지 않다면 등록할 필요가 없습니다.

저같은 경우에는, 언리얼 빌드 시스템에 손을 댈 계획이 없지만, 그래도 두 가지 이유 때문에 의존성 파일들을 소스 제어에 등록해 둡니다.

• Setup.bat 는 의존성 파일들을 먼저 검색하고 없는 파일만 추가적으로 다운로드합니다. 일반적으로 외부에서 데이터를 받는 것보다는 내부에서 받는 것이 빠르기 때문에 미리 올려 놓는 것이 좋습니다. Setup.bat 를 실행했을 때 다운로드받는 양은 적어지고 필요한 작업만 수행합니다.
• 나중에 엔진을 빌드하고 나면 의존성 파일들이 있는 디렉토리와 엔진 바이너리 파일들이 있는 디렉토리가 동일하기 때문에, 파일을 개별적으로 관리하기가 귀찮아집니다. 그냥 통째로 "Engine/Binaries" 폴더를 등록하는 것이 편합니다( 의존성 파일들이 해당 디렉토리에만 있는 의미는 아니니 헷갈리지 않길 바랍니다 ).

참고로 다른 자리에서 Setup.exe 를 실행하면 콘솔 프롬프트에 일부 파일을 덮어 쓸 것이냐는 질문을 하는데, 이 때 No 를 선택하시면 됩니다.

만약 의존성 파일을 등록해야겠다고 판단하셨다면, 새롭게 추가된 파일들을 모두 등록하시면 됩니다( 여기까지는 그냥 엔진 루트 디렉토리를 통째로 등록하면 됩니다 ).

4. GenerateProjectFiles.bat

---

이제 프로젝트 관련 파일들을 생성할 차례입니다. 이 파일은 프로그래머만 실행하시면 됩니다. 이 파일을 실행하게 되면 언리얼 엔진 소스 폴더를 열심히 돌면서 자동으로 프로젝트 파일을 생성합니다. 이와 관련한 도움말은 [ 자동 프로젝트 파일 생성 ] 이 있습니다.

요즘은 멀티 플랫폼에서 개발하는 시대이기 때문에, 특정 버전의 프로젝트 파일을 제공하는 것은 불합리합니다. 물론 make 파일을 사용하면 되지만, 이를 구성별로 사용자가 따로 관리하는 것은 어렵습니다. 그래서 언리얼은 이러한 과정을 모두 자동화했습니다. 안 그랬으면 UE42013.sln, UE42015.sln 같은 파일들을 만들어서 배포해야겠죠. 좀 더 나가면 UE4Editor2015.sln 같은 솔루션을 배포해야 할 수도 있었습니다.

제가 이전에 프로젝트를 진행하면서 그런 짓을 좀 해 봤는데, 정말 할 짓이 아닙니다. 파일 하나를 추가하면 솔루션이나 프로젝트를 열어서 일일이 추가해 줘야 하고, 삭제나 이동도 마찬가지입니다.

언리얼은 이 과정을 자동화시켜 사용하기 편하게 만들었습니다. 어떤 파일이 추가/삭제/이동되면 그냥 GenerateProjectFiles.bat 을 한 번 실행해 주기만 하면 됩니다. 프로젝트 관련 파일들은 Intermediate 디렉토리에 생성되며, 이러한 것들은 소스 제어에 등록될 필요가 없습니다. VS 에서 파일 구조를 filter 같은 것을 사용해서 관리하기 보다는, 실제 디렉토리를 중심으로 filter 가 생성되도록 하는 것이 더 합리적이고 파일을 찾기도 편합니다.

그런데 가끔 이 파일을 실행하면 아주 오랫 동안 아무 반응이 없을 때가 있습니다( 요즘 머신에서 15 초 넘어 가면 문제가 있습니다 ). 반응이 없어서 콘솔을 닫고 파일을 재실행하면 UnrealBuildTool.exe 가 사용중이라서 어쩌고 하면서 에러가 뜹니다. 이 경우에는 컴퓨터를 재시작하시고 Avast 같은 안티 바이러스 도구를 일시적으로 정지시키십시오. 엔진 폴더를 검사에서 배제하는 방법을 써 봤지만 소용이 없더군요. 그리고 나서 실행하시면 됩니다( 예전에는 디렉토리나 UnrealBuildTool.exe 파일을 배제하는 것만으로 됐던 것 같은데, 왜 그런지 모르겠네요. Windows 10 64bits 입니다 ). 추가 : Avast 에서 DeepScreen 기능을 아예 꺼버리니 제대로 동작합니다.

추가 : GenerateProjectFiles 를 실행하면 노란색으로 ucrt 경로 관련 경고가 출력될 경우가 있습니다. 이 경우에는 빌드도 제대로 안 되므로 반드시 해결해야 합니다. 그 방법은 [ UE4 빌드시에 ucrt 경로 충돌 문제 해결방법 ]에 정리해 뒀습니다.

 

이제 엔진 루트에 UE4.sln 이라는 솔루션 파일이 생성되어 있는 것을 확인하실 수 있습니다. 프로젝트 관련 ( 임시 ) 파일들은 "Engine/Intermediate" 디렉토리 안에 생성됩니다. 이 디렉토리는 소스제어에 등록할 필요가 없습니다. 참고로 솔루션 파일도 재생성할 수 있으므로 소스 제어에 등록할 필요가 없습니다.

5. 엔진 빌드하기

---

이제 엔진을 빌드해 줄 차례입니다. 언리얼 엔진을 빌드하려고 하면서 가장 어려웠던 점은 솔루션 구성을 이해하는 것입니다. 엄청나게 많은 구성들이 존재하기 때문에 머리가 엄청나게 복잡해집니다. 이와 관련한 문서는 [ 게임 프로젝트 컴파일하기 ] 와 [ 소스에서 언리얼 엔진 빌드하기 ] 등이 있습니다.

구성은 크게 5 종류의 카테고리로 나뉩니다. 각 항목은 다음과 같은 의미를 가집니다.

항목	설명
Debug	모든 프로젝트의 바이너리가 디버깅 심볼을 가지도록 합니다.
DebugGame	게임 프로젝트의 바이너리만 디버깅 심볼을 가지도록 합니다.
Development	일반적인 프로젝트에서의 Release 환경설정과 같습니다.
Test	Shipping 에서 콘솔, 통계, 프로우파일링을 추가한 것입니다.
Shipping	최상의 성능을 가진 설정입니다.

자 이제 우리는 어떠한 구성을 빌드해서 나오는 바이너리를 사용자에게 제공해야 하는걸까요? 도움말에서는 "DevelopmentEditor + Win64 + UE4" 를 빌드할 것을 권장하고 있습니다( 빌드하는데 상당히 오랜 시간이 걸리므로, 빌드를 걸어 놓고 그냥 딴 일을 하시기 바랍니다 ).

빌드할 때도 "Performing full C++ include scan (no include cache file)" 이라는 로그 이후에 오랫동안 아무런 반응이 없으면, Avast 같은 안티 바이러스 도구를 일시적으로 정지시켜야 합니다.

빌드가 끝나면 에디터를 실행하는 데 전혀 문제가 없습니다( 커스텀 혹은 인하우스 빌드는 런처를 통해서 실행할 수 없습니다, 엔진 루트의 "Engine/Binaries/Win64/UE4Editor.exe" 를 실행해야 합니다 ). 원래 에디터를 처음 실행할 때는 45% 정도에서 오래 멈춰 있으니 성급하게 끄지 말아 주세요.

그런데 에디터를 잘 가지고 놀다가 플레이( Play In Editor, PIE )를 하는 것은 상관없는데, 실행( Launch )를 하면 에러가 발생합니다.

이런 류의 에러는 앞으로 안드로이드용 개발을 하다가도 자주 만나게 되는 에러입니다. 

XXXEditor 구성을 사용하면, "UE4Editor-$(Platform)-$(Configuration).exe" 라는 바이너리를 생성합니다. 하지만 DevelopmentEditor 구성에서는 그냥 "UE4Editor.exe" 를 생성합니다.

그리고 Debug, DebugGame, Development, Test, Shipping 은 각각의 구성에 맞게 "UE4Game-$(Platform)-$(Configuration).exe" 라는 바이너리를 생성합니다. 이것이 하나의 에디터에서 다양한 플랫폼의 실행 파일을 런칭할 수 있는 비법( ? )입니다.

DevelopmentEditor 구성으로 UE4Editor.exe 를 빌드하면 기본적으로 UE4Game-Win64-Development.exe 를 런칭합니다. 다른 구성으로 빌드된 바이너리를 런칭하기 위해서는 "실행 > 프로젝트 런처" 를 클릭합니다.

그리고 나서 나오는 다이얼로그에서 오른쪽 상단의 "고급" 버튼을 클릭합니다. 그러면 각 구성과 플랫폼별로 런칭할 수 있는 구성이 나옵니다.

만약 해당 구성으로 빌드한 적이 없다면 또 "UE4Game 바이너리가 없습니다" 라는 에러 메시지를 만나게 되겠죠.

어쨌든 정리하자면 그냥 개발하는 동안에는 "DevelopmentEditor + Win64 + UE4" 와 "Development + Win64 + UE4" 구성만 빌드하면 됩니다. 만약 에디터에서 안드로이드 플랫폼에 프로젝트를 런칭하기를 원한다면 "Development + Andoroid + UE4" 를 빌드하면 됩니다.

프로젝트 런처를 통해서 실행한 프로그램을 프로세스에 연결해서 디버깅해 보고 싶다면 "Debug + Win64 + UE4" 같은 구성도 미리 빌드해 놓는 것도 좋겠죠. 하지만 이런 구성은 다른 개발자들에게 배포할 필요는 없으므로 소스 제어에는 등록할 필요가 없을 것 같습니다.

6. 소스 제어 - 바이너리 등록

---

"DevelopmentEditor + Win64 + UE4", "Development + Win64 + UE4", "Development + Android + UE4" 를 빌드했다면, "Engine/Binaries" 디렉토리를 통째로 소스 제어에 등록하시면 됩니다. 물론 3 번에서 의존성 파일을 등록하지 않았다면 그것을 배제하는 작업을 좀 해야겠죠. 추가 : 플러그인들도 빌드되기 때문에 Plugins 디렉토리도 같이 등록해야 합니다. 이 때 각 하위 디렉토리의 Intermediate 디렉토리에 있는 것들은 등록에서 배제해야 합니다.

추가적으로 다른 구성을 등록해야겠다고 생각하시면 그렇게 하셔도 상관은 없습니다. 아래와 같이 플랫폼별로 디렉토리가 세분화되어 있기 때문에 관리하기가 어렵지는 않을 겁니다.

7. 모듈 이해하기

---

언리얼에서 CPP 프로그래밍을 하다가 보면 모듈( Module )이라는 용어가 자주 등장합니다. 이와 관련해서는 [ 언리얼 아키텍처 ], [ 모듈 API 지정자 ], [ 게임플레이 모듈 ] 등의 도움말이 있지만, 그리 친절하지는 않습니다.

 

제가 대충 정리한 [ 언리얼 엔진 모듈 ] 항목을 참조하십시오. 해당 문서는 새로운 정보를 습득할 때마다 계속 업데이트 됩니다.

이러한 모듈 개념을 잘 이해하고 있어야, 나중에 다른 모듈을 사용하는데 어려움을 겪지 않게 됩니다.

8. CPP 프로젝트 만들기

---

이제 CPP 프로젝트를 하나 만들어 보겠습니다. 

자 이제 솔루션에는 BlankCpp 라는 프로젝트가 포함됩니다. 어떻게 포함되었을까요? 당연히 내부적으로 GenerateProjectFiles.bat 을 실행시켜서 포함시킨 것입니다. 

제가 언리얼을 처음 만질 때, 가장 두려웠던 것이 GenerateProjectFiles.bat 을 실행하는 것이었습니다. 혹시 뭔가 데이터가 날라가지 않을까라는 의심이 들었는데, 디렉토리에 파일이 남아 있으면 제대로 프로젝트가 생성되기 때문에 걱정하지 않으셔도 됩니다.

어쨌든 솔루션 익스플로러를 확인해 봅시다.

역시 여기에도 BlankCpp.Build.cs 라는 녀석이 생성되어 있는 것을 볼 수 있습니다. 즉 BlankCpp 모듈인 것입니다.

우리는 UE4 를 이미 빌드했기 때문에, BlankCpp 만 빌드하면 됩니다.

9. 소스제어 - CPP 프로젝트 데이터 등록

---

BlankCpp 프로젝트를 빌드했으면 이제 소스 제어에 올릴 차례입니다. 프로젝트 관련 파일들은 재생성하면 된다고 했기 때문에 올릴 필요가 없습니다. 그래서 아래 그림과 같이 선택된 디렉토리와 파일만 등록하면 됩니다.

그런데 다른 자리에서는 어떻게 프로젝트 파일을 생성하냐구요? "GenerateProjectFiles.bat BlankCpp.uproject -Game" 이라고 콘솔 창에서 입력하시면 됩니다. 아니면 uproject 를 열어서 에디터에서 다음과 같은 메뉴를 사용하셔도 됩니다.

또는 BlankCpp.uproject 파일의 컨텍스트 메뉴에서 생성할 수 있습니다.

어쨌든 전부다 본질은 GenerateProjectFiles.bat 에 있습니다.

10. 결론

---

언리얼 엔진의 빌드 시스템에 대해서 이해하면 개발이 편해지지만, 그렇지 못하면 지옥을 겪게 됩니다.

아직 제가 모르는 부분도 많고 자세히 다루지 않은 부분도 있습니다. 단지 이 문서에서는 가이드만 제시하는 것이기 때문에 다른 문서들을 참조하면서 해 보시기 바랍니다.

이 문서에서는 모듈에 대해서만 잠깐 다루고 타깃에 대해서는 다루지 않았는데, "*.Build.cs" 와 마찬가지로 "*.Target.cs" 라는 파일들이 존재합니다. 이건 dll 단위로 존재하게 됩니다. 자세한 내용은 [ 언리얼 빌드 시스템 타겟 파일 ] 도움말에서 찾아 보시기 바랍니다.

추가 : setup.bat 실행 후에 AndroidWorks 를 설치하셨다면, setup.bat 를 다시 실행해 주셔야 합니다.

 

추가 : 혹시 엔진을 커스터마이징해서 배포하는 팀( 혹은 사람 )과 엔진을 받아서 사용하는 팀이 구분되어 있고 서로의 영역을 건드리지 않는다면, [ 빌드 그래프 ] 와 [ Installed Build 참고서 ] 를 참고해서 배포하시기 바랍니다. 그냥 빌드해서 서밋하시면 코드가 변경되었기 때문에 엔진 코드를 수정하면 게임 칸텐츠를 작업하는 측에서 엔진까지 빌드해야 하는 경우가 생깁니다.