[번역] UnrealBuildAccelerator(UBA)를 활용한 분산형 빌드

역자의 말. 5.4.X 초기 버전을 받아서 첫 1주일 정도에는 개발팀의 혼란이 야기 될 정도의 버그 투성이 상태로 릴리스 됬던 것을 기억합니다. 그 당시에 개발팀 리더분께서 "햐~ 그래도 UBA 가 들어온거 하나로 용서가 되네" 라고 말 할 정도로 개발 환경에 큰 영향을 준것은 확실히 맞았습니다. 엔진 소스 버전 관리를 하는 저로서는 최근 5.3.2 소스코드에 수정 한 내용들을 5.4.0 으로 마이그레이션 하면서... 함수 이름이 바뀐 것들 부터 두 개의 클래서가 하나로 통합 된 것들이며 전처리 명명이 바뀐 것들까지 정말 힘들게 마이그레이션을 진행 했었는데요... 저 역시 "  햐~ 그래도 UBA 가 들어와서 용서가 되네" 라고 할 정도였어요. 암튼... 최근 두 번의 핫픽스가 진행 되면서 5.4.3 이 되었네요? UBA 와 ZEN 멀티 쿡킹은 잘 살펴봐야 할 부분이고 CI/CD 측면에서 멋진 Life Saver 가 되어 주고 있습니다. ( 사족으로 몇 달 동안 페스트빌드를 종종 쓰긴 했지만 정말 오픈소스의 한계 때문에 너무 고칠것들이 많았다능... )

---

저자: 켄 쿠아노 : 애픽게임즈 일본.

UBA 는 UE5.4 에서 베타로 공개된 기능입니다.

1. 개요 UE5.4부터 도입된 UnrealBuildAccelerator(이하 UBA)를 사용하여 분산 빌드하기 위한 설정 방법을 설명합니다. 아래는 분산 빌드 이미지입니다. 로컬 PC에서만 빌드할 때는 빌드 시간이 많이 걸렸습니다. 분산 빌드는 빌드 작업을 다른 PC로 분산시켜 로컬 PC가 아닌 다른 PC에서 빌드 작업을 처리함으로써 빌드 시간을 단축할 수 있습니다.

UE5.4에서 UBA는 베타 버전으로 출시되었으며, 소스 코드 빌드 및 셰이더 컴파일 빌드(실험적 기능)에서 분산 빌드를 구현하여 간단한 설정으로 사용할 수 있습니다.

2024-04-26_13h20_571084×598 23.8 KB

 

2024-04-26_13h21_031096×612 37.9 KB

 

2. 로컬 네트워크에서 수동으로 분산 빌드하기 

여기서는 로컬 네트워크 환경에서 UnrealBuildAccelerator를 사용하여 분산 빌드가 가능한지 테스트하는 방법을 설명합니다.

자동으로 분산 빌드 환경을 구축하려면 이 단계를 건너뛰고 3단계로 넘어가세요.

2.1. 소스 코드 분산 빌드 엔진 코드 등 소스 코드의 분산 빌드가 동작하기 위한 설정 방법을 설명한다. 아래 구성에서 로컬 PC와 원격 PC에 UBA를 배치하여 분산 빌드할 수 있을 때까지의 방법을 설명한다. 전제로 로컬 PC에는 엔진 코드를 포함한 소스 코드가 존재하고, 원격 PC는 아무것도 설정되어 있지 않은 PC라고 가정합니다.

1. 원격 PC에 UBA 배치 

원격 PC에 엔진이 설치되어 있지 않아도 상관없지만, 분산 빌드를 실행하기 위해 UBA의 애플리케이션을 배치해 두면 된다. 이미 빌드된 환경(예: 소스 코드를 빌드하는 로컬 PC 등)에서 UBA가 포함된 애플리케이션을 미리 복사해 두면 문제없다. UBA는 엔진의 아래 위치에 있으므로, x64 폴더 이하를 복사하여 원격 PC의 임의의 위치(아무 곳이나 상관없다)에 배치한다.

[EngineRoot]\Engine\Binaries\Win64\UnrealBuildAccelerator\x64\UbaAgent.exe

2. 원격 PC에서 UBA 실행 원격 PC에 UBA를 배치한 후, UBA를 실행하여 로컬 PC에서 분산 빌드 시작을 대기 상태로 만들기 위해 다음과 같은 배치 파일을 생성하고 실행합니다. 디렉토리를 지정하여 실행하면 UBA는 접속 대기 상태가 된다. 

• 포맷

[EngineRoot]\Engine\Binaries\Win64\UnrealBuildAccelerator\x64\UbaAgent.exe -host=[HostPCIpAddress] -dir=[CacheDirPath]

• 실행 예시

C:\EPIC\Github\UnrealEngine\Engine\Binaries\Win64\UnrealBuildAccelerator\x64\UbaAgent.exe -host=-host=192.168.11.10 -dir=d:\cache

원격 PC에서 UBA를 실행하면 호스트와의 연결 대기 상태가 됩니다.

로컬 PC에서 분산 태스크가 던져지면 자동으로 빌드 출력을 표시합니다.

3. 로컬 PC에서 UBT를 사용하여 빌드 실행 UBT를 지정하여 UBA에서 엔진 리빌드를 실행합니다. 아래는 명령어 실행 형식 예시이며, 그 아래에 실행 예시가 나와 있습니다. 인수 지정은 아래 내용을 따릅니다.

"-UBA"는 UBA를 사용하여 분산 빌드를 수행하도록 지정합니다. "-UBAVisualizer"는 분산 빌드 작업을 나타내는 애플리케이션 실행을 지정한다. "-UBAForceRemote"는 원격 PC에서만 빌드 실행 여부를 지정한다.

• 형식

[EngineRoot]\Engine\Build\BatchFiles\RunUBT.bat UnrealEditor Win64 Development -Rebuild -UBA -UBAVisualizer

• 실행 예시

C:\EPIC\Github\UnrealEngine\Engine\Build\BatchFiles\RunUBT.bat UnrealEditor Win64 Development -Rebuild -UBA -UBAVisualizer

"-UBAForceRemote" 없는 경우 ⇒ 로컬 + 원격으로 빌드 실행

"-UBAForceRemote" 추가 시 ⇒ 원격으로만 빌드 실행

2.2. 분산 셰이더 컴파일 소스 코드 빌드와 마찬가지로 셰이더 컴파일을 분산 실행하여 테스트하기 위한 설정은 다음과 같다. 기본적인 UBA 배치에 대해서는 2.1.에서 완료한 것으로 가정하고, 아래에서는 셰이더 컴파일을 실행하기 위한 설정 및 확인 방법에 대해 설명한다.

• 프로젝트 플러그인에서 UBAController 활성화하기 프로젝트를 실행한 후 UBAController 플러그인을 활성화합니다.
• Engine.ini 에서 UBAController 활성화 프로젝트의 DefaultEngine.ini 에 다음과 같은 정의를 추가합니다.

[UbaController]
Enabled=True

• 에디터 시작 시 아래 인수를 붙여 실행 셰이더 컴파일을 분산시킬 수 있는지 확인하기 위해, 아래 인수를 붙여 프로젝트를 실행합니다. 이 명령어를 통해 셰이더 컴파일이 강제로 실행되어 분산되는 것을 확인할 수 있습니다.

-noshaderddc -noxgeshadercompiler

주의: -noshaderddc -noxgeshadercompiler 명령은 셰이더 컴파일을 쉽게 실행하기 위한 명령으로 실제로는 사용하지 않으며, 패키징 등을 통해 셰이더 컴파일을 실행하는 것이 실제 사용 방법입니다.

3. 로컬 네트워크에서 자동 분산 빌드 지금까지 수동으로 분산 빌드를 확인하는 방법에 대해 알아보았는데, 이제부터는 자동으로 분산 빌드를 수행하기 위한 설정 방법에 대해 알아보겠습니다. 실제로 분산 빌드를 수행하기 위해서는 분산 대상과 분산 작업을 제어해야 하는데, UBA는 빌드를 수행하기 위한 애플리케이션이며, 이 UBA에 대한 자동 배포 제어를 수행하는 것이 HordeServer / HorderAgent이다.

HordeServer는 빌드 머신 PC에 설치하는 애플리케이션으로, 네트워크 상에 존재하는 HordeAgent를 등록하여 UBA와 연동하여 분산 지시를 수행합니다. HordeAgent는 원격 PC에 설치되는 애플리케이션으로, 설치된 PC에 존재하는 UBA와 연동하여 분산 빌드를 처리하기 때문에 분산 빌드를 위해서는 HordeServer를 설치해야 한다.

2024-04-26_13h25_131097×613 60.5 KB

 

여기서부터의 내용은 아래 페이지를 기반으로 합니다.

https://github.com/EpicGames/UnrealEngine/blob/5.4/Engine/Source/Programs/Horde/Docs/Tutorials/RemoteCompilation.md

3.1. 빌드 머신 PC 설정 HordeServer 설치 

1. HordeServer 설치는 Engine/Extras/Horde/UnrealHordeServer.msi를 실행하여 HordeServer를 설치합니다. Engine/Extras/Horde/ 아래 내용은 다운로드에 포함되어 있지 않지만, Setup.bat를 실행하면 디렉터리가 생성되어 접근할 수 있습니다. 설치 프로그램을 실행한 후 나머지는 변경하지 않고 모두 [Next]를 선택하면 OK입니다(변경이 필요한 경우 필요에 따라 내용을 변경해 주시면 됩니다).

2. 빌드 머신 PC의 IP 주소 확인 PC에서 명령 프롬프트를 열고 ipconfig를 입력하여 빌드 머신의 IP 주소를 확인한다. 그림의 경우, "10.7.101.8"이 빌드 머신의 IP 주소이므로 나중에 사용할 수 있도록 메모해 둔다.

3.2. 로컬 PC 설정 

1. UBA 이용 설정 추가 로컬 PC에서는 분산 빌드를 수행하기 위해 호스트(빌드 머신 PC)를 지정합니다. 호스트 지정은 Engine/Saved/UnrealBuildTool/BuildConfiguration.xml을 열고 IP를 지정한다. BuildConfiguration.xml에 아래 내용을 추가(또는 Copy&Paste)하여 서버(의 항목)를 방금 확인한 빌드 머신의 IP 주소로 바꿉니다.

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">

    <BuildConfiguration>
        <!-- Enable support for UnrealBuildAccelerator -->
        <bAllowUBAExecutor>true</bAllowUBAExecutor>
    </BuildConfiguration>

    <Horde>
        <!-- Address of the Horde server -->
        <!-- Server>http://{{ SERVER_HOST_NAME }}:13340</Server -->
        <Server>http://10.7.101.8:13340</Server>

        <!-- Pool of machines to offload work to. Horde configures Win-UE5 by default. -->
        <WindowsPool>Win-UE5</WindowsPool>
    </Horde>

    <UnrealBuildAccelerator>
        <!-- Enable for visualizing UBA progress (optional) -->
        <bLaunchVisualizer>true</bLaunchVisualizer>
    </UnrealBuildAccelerator>
</Configuration>

빌드 머신 PC의 IP 주소가 "10.7.101.8"인 경우, "http://10.7.101.8:13340 1"을 입력한다.

3.3. 원격 PC 설정 

원격 PC에는 HordeAgent를 설치하고, HordeAgent를 설치한 후 HordeServer에 PC를 분산 대상 PC로 등록한다. 이를 통해 HordeServer는 HordeAgent에 작업을 분산할 수 있게 되며, 자동으로 분산 대상 PC에 할당할 수 있게 된다.

1. HordeAgent 설치 HordeAgent의 설치 프로그램은 HordeServer의 PC에 접속하여 설치 프로그램을 얻습니다. 원격 PC에서 WebBrowser를 열고 http://[HostIp]:13340을 입력(예: http://10.7.101.8:13340 1)합니다. [TOOLS]에서 HordeAgent 설치 프로그램을 다운로드하여 설치한다.

2024-04-26_17h13_411026×533 98.2 KB

 

설치 프로그램 설정은 기본적으로 변경할 필요 없이 [Next]를 눌러 진행하면 되지만, 마지막 HordeServer IP를 지정하는 부분에서는 메모해 둔 HordeServer(빌드 머신 PC)의 IP, "http://[HostIp ]:13340"을 입력(예: http://10.7.101.8:13340 1 )합니다.

HordeAgent를 HordeServer에 등록 [SERVER]->[Agent Enrollments]에서 HordeAgent의 PC를 등록합니다.

HordeAgent가 설치된 PC가 목록에 표시되므로 ①→②→③ 순서대로 하드웨어를 선택하고 [Enroll Agents] 버튼을 눌러 등록합니다.

2024-04-26_17h20_471920×1040 148 KB

 

등록이 완료되면 [SERVER]->[Agents] 목록에 표시가 추가됩니다.

이상으로 설정이 완료되었습니다. 로컬 PC에서 빌드하면 분산 빌드를 이용할 수 있습니다.

4. 트러블슈트 

• 소스코드 몇 줄 수정하는 정도로는 분산되지 않고 로컬 빌드만으로 완료되므로, 분산되어 있는지 확인하려면 엔진 리빌드를 통해 확인하는 것이 좋다.

RunUBT.bat UnrealEditor Win64 Development -Rebuild -UBA

• 로컬 PC가 무선랜 연결로도 이용이 가능하지만, 무선랜 연결에서 잘 작동하지 않는 경우 유선랜으로 한 번 확인해 보시기 바랍니다. 

2.네트워크 연결이 잘 안 되는 경우는 포트가 열려있지 않을 수 있습니다.

• 클라우드 네트워크 환경의 PC를 빌드에 참여시키고자 하는 경우 UE5.4 현재 미지원입니다.

3. HordeServer와 HordeAgent를 같은 PC에 설치해도 되나요?

• 효율적인 빌드가 불가능할 수 있으므로 권장하지 않습니다.

---

원문

UnrealBuildAccelerator (UBA) を利用した分散ビルドのセットアップ方法