6-2. BuildGraph 활용 | UE5 Editor Tools Deep Dive

01

BuildGraph 개요

UE5 내장 빌드 자동화 시스템

BuildGraph는 UE5에 내장된 XML 기반 빌드 자동화 시스템입니다. 빌드, 쿠킹, 패키징, 테스트를 하나의 스크립트로 정의하고, 여러 머신에서 분산 실행할 수 있습니다.

개념	설명
`Node`	단일 작업 단위 (빌드, 쿠킹, 테스트 등)
`Agent`	노드를 실행하는 머신 (로컬 또는 빌드 팜)
`Trigger`	수동 승인이 필요한 게이트
`Property`	빌드 설정 변수 (플랫폼, 설정 등)
`Badge`	빌드 상태 표시 (CIS 연동)

BuildGraph 위치

BuildGraph 스크립트는 보통 Engine/Build/Graph/에 있으며, 프로젝트별 스크립트는 Build/ 폴더에 배치합니다. Engine/Build/Graph/Examples/에 예제가 포함되어 있습니다.

02

BuildGraph XML 구조

기본 빌드 스크립트 작성하기

                    Build/MyBuildGraph.xml
                    <?xml version="1.0" encoding="utf-8"?>
<BuildGraph xmlns="http://www.epicgames.com/BuildGraph">

  <!-- 옵션 정의 -->
  <Option Name="ProjectPath"
    DefaultValue="D:/Projects/MyGame/MyGame.uproject"
    Description="Project file path" />

  <Option Name="Platform"
    DefaultValue="Win64"
    Description="Target platform" />

  <Option Name="Configuration"
    DefaultValue="Development"
    Description="Build configuration" />

  <!-- 프로퍼티 -->
  <Property Name="OutputDir"
    Value="D:/Builds/$(Platform)/$(Configuration)" />

  <!-- 에이전트 1: 컴파일 -->
  <Agent Name="Compile Agent" Type="CompileWin64">

    <Node Name="Compile Editor"
      Produces="#EditorBinaries">
      <Compile
        Target="MyGameEditor"
        Platform="$(Platform)"
        Configuration="$(Configuration)"
        Arguments="-Project=$(ProjectPath)" />
    </Node>

    <Node Name="Compile Game"
      Produces="#GameBinaries">
      <Compile
        Target="MyGame"
        Platform="$(Platform)"
        Configuration="$(Configuration)"
        Arguments="-Project=$(ProjectPath)" />
    </Node>

  </Agent>

  <!-- 에이전트 2: 쿠킹 & 패키징 -->
  <Agent Name="Cook Agent" Type="CookWin64">

    <Node Name="Cook Content"
      Requires="#EditorBinaries"
      Produces="#CookedContent">
      <Cook
        Project="$(ProjectPath)"
        Platform="$(Platform)" />
    </Node>

    <Node Name="Package Game"
      Requires="#GameBinaries;#CookedContent"
      Produces="#PackagedGame">
      <Stage
        Project="$(ProjectPath)"
        Platform="$(Platform)"
        Configuration="$(Configuration)"
        StagingDir="$(OutputDir)" />
    </Node>

  </Agent>

  <!-- 에이전트 3: 테스트 -->
  <Agent Name="Test Agent" Type="TestWin64">

    <Node Name="Run Tests"
      Requires="#EditorBinaries">
      <Command
        Name="RunUnrealTests"
        Arguments="$(ProjectPath) -RunTests -LogCmds='global None, LogAutomationController Log'" />
    </Node>

    <Node Name="Asset Audit"
      Requires="#EditorBinaries">
      <Command
        Name="RunAssetAudit"
        Arguments="$(ProjectPath) -run=AssetAudit -RootPath=/Game" />
    </Node>

  </Agent>

</BuildGraph>
                

03

BuildGraph 실행

커맨드라인에서 BuildGraph 스크립트 실행하기

                    BuildGraph 실행 명령
                    :: 전체 빌드 실행
RunUAT.bat BuildGraph ^
    -Script=Build/MyBuildGraph.xml ^
    -Target="Package Game" ^
    -set:ProjectPath=D:/Projects/MyGame/MyGame.uproject ^
    -set:Platform=Win64 ^
    -set:Configuration=Shipping

:: 특정 노드만 실행
RunUAT.bat BuildGraph ^
    -Script=Build/MyBuildGraph.xml ^
    -Target="Run Tests" ^
    -set:ProjectPath=D:/Projects/MyGame/MyGame.uproject

:: 그래프 미리보기 (실행 없이 검증)
RunUAT.bat BuildGraph ^
    -Script=Build/MyBuildGraph.xml ^
    -Target="Package Game" ^
    -PreviewOnly

:: 분산 빌드 (여러 머신)
RunUAT.bat BuildGraph ^
    -Script=Build/MyBuildGraph.xml ^
    -Target="Package Game" ^
    -SharedStorageDir=\\BuildFarm\Shared
                

노드 의존성

Requires 속성으로 노드 간 의존성을 정의합니다. Produces로 산출물을 선언하면, 해당 산출물을 Requires하는 노드는 자동으로 순서가 결정됩니다. 독립적인 노드는 병렬 실행됩니다.

04

고급 BuildGraph 패턴

조건부 실행, 트리거, 멀티 플랫폼

                    XML - 조건부 & 멀티 플랫폼
                    <!-- 조건부 실행 -->
<Option Name="WithTests"
  DefaultValue="true"
  Description="Run automated tests" />

<Node Name="Run Tests"
  Requires="#EditorBinaries"
  If="$(WithTests)">
  <!-- WithTests가 true일 때만 실행 -->
</Node>

<!-- 멀티 플랫폼 반복 -->
<ForEach Name="TargetPlatform"
  Values="Win64;Linux;Android">

  <Agent Name="Cook $(TargetPlatform)"
    Type="Cook$(TargetPlatform)">
    <Node Name="Cook $(TargetPlatform)"
      Produces="#Cooked_$(TargetPlatform)">
      <Cook
        Project="$(ProjectPath)"
        Platform="$(TargetPlatform)" />
    </Node>
  </Agent>

</ForEach>

<!-- 수동 승인 트리거 -->
<Trigger Name="Deploy to Staging">
  <Node Name="Deploy"
    Requires="#PackagedGame">
    <!-- 배포 로직 -->
  </Node>
</Trigger>
                

SUMMARY

핵심 요약

BuildGraph는 UE5 내장 XML 기반 빌드 자동화 시스템으로, 빌드-쿠킹-패키징-테스트 파이프라인을 정의합니다
Node는 작업 단위, Agent는 실행 머신, Produces/Requires로 의존성 그래프를 구성합니다
RunUAT.bat BuildGraph -Script=... -Target=...으로 실행하며, -set:으로 옵션을 전달합니다
ForEach로 멀티 플랫폼 빌드를, If로 조건부 실행을, Trigger로 수동 승인 게이트를 구현합니다
SharedStorageDir을 지정하면 여러 머신에서 분산 빌드를 수행하여 빌드 시간을 단축할 수 있습니다

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: BuildGraph XML 스크립트 작성

BuildGraph XML 파일을 작성하여 빌드, 쿠킹, 스테이징의 기본 파이프라인을 정의하세요. , , 요소를 사용하고, RunUAT BuildGraph -script=MyBuild.xml -set:Platform=Win64로 실행하세요.

실습 2: 조건부 빌드 노드 구성

BuildGraph에서

심화 과제: 완전 자동화 릴리스 파이프라인

BuildGraph로 버전 번호 생성, 빌드, 쿠킹, 패키징, 테스트 실행, 배포까지의 전체 릴리스 파이프라인을 설계하세요. 빌드 실패 시 알림, 테스트 결과 리포트, 아티팩트 아카이빙을 포함하세요.