언리얼 엔진의 Wine 지원 컨테이너 퀵스타트 | 언리얼 엔진 5.7 문서

필요한 사전 지식

이 페이지의 콘텐츠를 이해하고 사용하려면 다음 주제에 대한 사전 지식이 필요합니다.

이 퀵스타트는 언리얼 엔진에 사용할 Wine 지원 컨테이너 이미지의 빌드를 돕도록 설계되었고, 이를 통해 Linux에서 Windows 개발 및 클라우드 디플로이 워크플로를 실행할 수 있습니다. 이 가이드에서는 다음 주제를 다룹니다.

컴퓨터에 Docker 설치하기.
Wine 지원 컨테이너 이미지 빌드용 스크립트를 포함하는 Wine Resources 저장소 다운로드하기.
Windows 워크로드를 실행하기 위해 언리얼 엔진과 Wine 모두를 포함하는 Linux 컨테이너 이미지 빌드하기.

이러한 지침에 따라 빌드한 컨테이너 이미지에는 C++ 컴파일러 툴체인이 포함되지 않습니다. 따라서 이 컨테이너 이미지는 C++ 코드가 포함된 언리얼 엔진 프로젝트를 패키지로 만드는 데 사용될 수 없습니다. 이 컨테이너 이미지는 오직 블루프린트 스크립트만 포함된 프로젝트를 패키지로 만드는 데 사용될 수 있습니다.

사양

이 퀵스타트에 따라 Wine 컨테이너 이미지를 빌드하고 실행하려면 컴퓨터가 하드웨어 및 소프트웨어 사양 페이지의 Linux 컨테이너 섹션에 명시된 하드웨어 및 소프트웨어 사양을 충족해야 합니다.

추가로, 이 가이드를 따르려면 컴퓨터에 다음 소프트웨어가 필요합니다.

Docker Engine 버전 23.0.0 이상을 사용하는 Docker. 아래 Docker 설치하기를 확인하세요.
Python 버전 3.7 이상. Python.org로 가서 Python을 다운로드하고 설치합니다.

Docker 설치하기

Wine과 언리얼 엔진으로 컨테이너 이미지를 빌드 및 실행하는 데 권장되는 툴은 Docker입니다. Docker의 설치 단계는 사용하는 운영 체제마다 다릅니다. 아래 링크는 현재 이용 가능한 각 플랫폼에서 Docker를 설치하는 방법을 안내합니다.

Windows: Windows에 Docker Desktop 설치하기
macOS: Mac에 Docker Desktop 설치하기
Linux: 특정 Linux 배포판에 맞는 Docker Engine을 설치하려면 아래에서 적절한 지침을 따르세요.

Wine Resources 저장소 다운로드하기

컨테이너 이미지는 언리얼 엔진 워크로드를 위해 호환성을 개선하는 패치와 함께 Wine을 캡슐화하는데, 에픽게임즈는 이러한 컨테이너 이미지를 빌드하는 리소스를 제공합니다. 해당 리소스는 언리얼 엔진 사용자가 사용할 수 있도록 GitHub에 공개되어 있습니다.

github.com/EpicGamesExt/WineResources에서 컴퓨터로 Wine Resources 저장소를 다운로드하세요. Git을 설치했다면 간단히 저장소를 로컬 디렉터리에 복제하면 됩니다. 아니면 Code 드롭다운 메뉴에서 Download ZIP 을 선택하여 ZIP 아카이브를 다운로드해도 됩니다. 다운로드가 완료되면 파일을 로컬 디렉터리에 추출합니다.

Wine 베이스 이미지 빌드하기

명령 프롬프트(또는 터미널) 창을 열고 작업 디렉터리를 WineResources/build 로 변경합니다.

운영 체제에 맞는 적절한 래퍼 스크립트를 실행합니다.

Linux와 macOS에서는 ./build.sh 를 실행합니다.
Windows에서는 .\build.bat 를 실행합니다.

래퍼 스크립트는 빌드 스크립트가 의존하는 Python 패키지를 자동으로 설치한 다음, Python 빌드 스크립트 자체를 실행합니다. Python 빌드 스크립트는 Wine의 패치 버전을 포함하는 베이스 이미지를 빌드합니다. 빌드가 완성되면 epicgames/wine-patched:9.0.0 태그가 붙은 컨테이너 이미지를 사용할 수 있습니다.

베이스 이미지를 테스트하려면 Wine의 빌드 버전을 출력하는 컨테이너를 실행합니다.

docker run --rm "epicgames/wine-patched:9.0.0" wine --version

Wine 컨테이너 이미지에 언리얼 엔진 복사하기

이제 언리얼 엔진이 설치된 빌드(Installed Build)를 포함하는 이전 단계에서 만든 컨테이너 이미지를 토대로 새로운 컨테이너 이미지를 만들 준비가 되었습니다.

이 단계에서는 Windows용 언리얼 엔진 사본이 필요합니다. 필요한 파일을 얻으려면 공식 설치 지침에 따라 Windows 머신에서 에픽게임즈 런처를 사용하여 언리얼 엔진을 다운로드하는 방법을 추천해 드립니다.

언리얼 엔진의 루트 디렉터리(Engine/ 을 포함하는 경로)에 있는 콘텐츠를 WineResources/examples/quickstart/wrap-installed-build/context/UnrealEngine/ 디렉터리에 복사합니다.

Windows에서 설치된 빌드 파일을 복사할 때 대상 파일 경로가 하나라도 최대 경로 길이 제한을 초과하는 경우 오류가 발생할 수 있습니다. 이러한 오류를 피하려면 Wine Resources 저장소의 로컬 사본을 드라이브 루트에 저장하는 방식(예: C:\WineResources) 등 대상 디렉터리의 경로 길이를 짧게 설정하거나 Microsoft의 긴 경로를 사용하도록 설정하는 지침을 따라야 합니다.

명령 프롬프트(또는 터미널) 창을 열고 작업 디렉터리를 WineResources/examples/quickstart/wrap-installed-build/ 로 변경합니다. Wine과 언리얼 엔진을 모두 포함하는 새로운 컨테이너 이미지를 빌드하려면 운영 체제에 맞는 적절한 래퍼 스크립트를 실행합니다.

Linux와 macOS에서는 ./build.sh 를 실행합니다.
Windows에서는 .\build.bat 를 실행합니다.

래퍼 스크립트는 운영 체제에 맞는 명령어를 사용하여 Python 빌드 스크립트 자체를 실행합니다. Python 빌드 스크립트는 설치된 빌드 파일이 올바른 위치에 복사되었는지 확인한 다음, 파일이 나타내는 언리얼 엔진 버전을 자동으로 탐지합니다. 그런 다음 이 스크립트는 컨테이너 이미지를 빌드합니다.

빌드가 완성되면 epicgames/unreal-engine:dev-wine-blueprintonly-<VERSION> 태그가 붙은 컨테이너 이미지를 사용할 수 있습니다. 여기서 <VERSION> 은 컨테이너 이미지가 빌드된 언리얼 엔진 버전을 의미합니다.

설치된 빌드 파일을 컨테이너 이미지에 복사하는 Dockerfile 단계는 완료하는 데 오래 걸릴 수 있습니다. 즉, 대부분의 시스템에서 1시간 이상이 걸리고, Windows에서는 WSL2와 함께 Docker Desktop을 사용하는 경우 몇 시간이 걸릴 수도 있습니다. 복사 작업의 진행률을 나타내는 출력 정보가 없는 관계로, 컴퓨터의 작동이 멈춘 것처럼 보일 수도 있습니다. 하지만 당연히 멈춘 것은 아닙니다. 단순히 완료될 때까지 기다리면 됩니다.

Wine 지원 언리얼 엔진 컨테이너 이미지 사용하기

생성된 Wine 지원 언리얼 엔진 컨테이너 이미지로 이제 Windows용으로 언리얼 엔진 프로젝트의 패키지를 만들 수 있습니다. 앞서도 말했지만 컨테이너 이미지는 현재 C++ 코드를 포함하는 프로젝트를 패키지로 만드는 기능을 지원하지 않습니다. 따라서 컨테이너 이미지는 블루프린트 스크립트를 포함하는 프로젝트를 패키지로 만드는 데에만 사용될 수 있습니다.

아래 코드는 언리얼 엔진 5.5.0용으로 빌드된 Wine 이미지에서 언리얼 자동화 툴을 사용하여 프로젝트를 패키지로 만드는 방법을 보여줍니다.

패키지로 만들 언리얼 엔진 프로젝트가 포함된 디렉터리(.uproject 파일을 포함하는 디렉터리) 경로로 <PATH_TO_PROJECT> 를 대체합니다. <UPROJECT_FILE> 을 .uproject 파일의 이름으로 대체합니다.

운영 체제를 선택합니다.

Windows

macOS

Linux

docker run --rm -v "<PATH_TO_PROJECT>:/project" ^
"epicgames/unreal-engine:dev-wine-blueprintonly-5.5.0" ^
    /bin/sh -c "wine ^
    C:/UnrealEngine/Engine/Build/BatchFiles/RunUAT.bat ^
    BuildCookRun ^
    -noP4 -allmaps -build -cook -stage -pak ^
    -project='Z:/project/<UPROJECT_FILE>' ^
    -platform=Win64 ^
    -clientconfig=Development ^
    -archive -archivedirectory='Z:/project/archive'"

명령 프롬프트 창이 아닌 PowerShell 창에서 명령을 실행하는 경우, 각 명령줄의 끝에 있는 캐럿 이스케이프 캐릭터(^)를 백틱 이스케이프 캐릭터(`)로 대체해야 합니다.

docker run --rm -v "<PATH_TO_PROJECT>:/project" \
"epicgames/unreal-engine:dev-wine-blueprintonly-5.5.0" \
    /bin/sh -c "wine \
    C:/UnrealEngine/Engine/Build/BatchFiles/RunUAT.bat \
    BuildCookRun \
    -noP4 -allmaps -build -cook -stage -pak \
    -project='Z:/project/<UPROJECT_FILE>' \
    -platform=Win64 \
    -clientconfig=Development \
    -archive -archivedirectory='Z:/project/archive'"

docker run --rm -v "<PATH_TO_PROJECT>:/project" \
"epicgames/unreal-engine:dev-wine-blueprintonly-5.5.0" \
    /bin/sh -c "wine \
    C:/UnrealEngine/Engine/Build/BatchFiles/RunUAT.bat \
    BuildCookRun \
    -noP4 -allmaps -build -cook -stage -pak \
    -project='Z:/project/<UPROJECT_FILE>' \
    -platform=Win64 \
    -clientconfig=Development \
    -archive -archivedirectory='Z:/project/archive'"