조직에서 사용할 턴키 구성 | 언리얼 엔진 5.0 문서

플랫폼 오너는 자신의 SDK를 케이스별로 조직에 배포합니다. 제공자로부터 SDK를 가져와야 한다는 점은 마찬가지지만, 조직의 공용 파일 소스 위치에 SDK를 둘 수 있습니다. 그러면 턴키는 이러한 파일에 액세스하여 개별 사용자의 디바이스에 SDK를 다운로드 및 설치할 수 있습니다.

턴키용 SDK 파일은 다음과 같은 세 가지 방법으로 호스팅할 수 있습니다.

조직의 Perforce 저장소
사용자의 로컬 머신
Google Drive의 공유 드라이브

그런 다음 턴키는 일련의 XML 파일을 연계하여 플랫폼별로 사용할 수 있는 SDK를 결정합니다. 이 프로세스는 언리얼 엔진의 설치 디렉터리에서 Engine/Build/Turnkey에 있는 TurnkeyManifest.xml 및 TurnkeyStudioSettings.xml 파일을 읽는 것부터 시작합니다.

TurnkeyManifest.xml은 사용 가능한 SDK에 대한 정보를 포함하거나 필요한 정보가 포함된 기타 매니페스트 파일을 가리키는 반면, TurnkeyStudioSettings.xml은 Google Drive 또는 서명된 인증서에 액세스하는 데 필요한 크리덴셜 같은 스튜디오 차원의 정보를 제공합니다. TurnkeyManifest.xml과 TurnkeyStudioSettings.xml은 모두 로컬 또는 원격 디렉터리에 있는 다른 .xml 파일을 가리키도록 연계할 수 있습니다.

이상적인 사용 사례는 버전 관리 시스템 내에서 언리얼 엔진 소스 파일과 함께 TurnkeyManifest.xml을 조직 내 모든 사용자에게 배포하는 것입니다. 이 기본 매니페스트는 변경되지 않으며, 대신 각 플랫폼별 SDK 파일과 함께 배치된 다른 매니페스트에 대한 레퍼런스를 포함합니다. 이 구성을 사용하면 언리얼 엔진 소스 파일을 변경하지 않고도 이러한 매니페스트를 빠르게 편집하고 업데이트할 수 있습니다.

매니페스트 파일 개요

턴키 매니페스트에는 다음과 같은 정보가 포함됩니다.

전체 매니페스트를 둘러싸는 TurnkeyManifest 태그
- AdditionalManifests 태그
  - 현재 매니페스트와 함께 포함할 다른 매니페스트를 가리키는 개별 Manifest 항목
- 다음과 같이 사용 가능한 SDK에 대한 정보를 포함하는 FileSource 항목:
  - Platform
  - Type
  - Version
  - Name
  - Source

예를 들어 Win64 및 Mac을 지원하는 유효한 TurnkeyManifest의 예시는 다음과 같습니다.

	<?xml version="1.0" encoding="utf-8" ?>
	<TurnkeyManifest>
		<AdditionalManifests>
			<Manifest>$(ThisManifestDir)/MyStudio_TurnkeyManifest.xml</Manifest>
			<Manifest>$(UE_STUDIO_TURNKEY_LOCATION)</Manifest>
		</AdditionalManifests>

		<FileSource>
			<Platform>Mac</Platform>
			<Type>Full</Type>
			<Version>$(ExpVersion)</Version>
			<Name>MacOS SDK v$(ExpVersion)</Name>
			<Source>fileexpansion:googledrive:/SdkInstallers/Mac/$[ExpVersion]/Installer.zip</Source>
		</FileSource>

		<FileSource>
			<Platform>Win64</Platform>
			<Type>Full</Type>
			<Version>1.00</Version>
			<Name>Win64 SDK V1.00</Name>
			<Source>googledrive:/SdkInstallers/Win64/1.00/Installer.zip</Source>
		</FileSource>

	</TurnkeyManifest>

추가 매니페스트 제공

AdditionalManifests 섹션에는 턴키가 파일을 스캔할 때 포함할 다른 XML 파일을 가리키는 개별 Manifest 항목을 포함합니다. Engine/Build/Turnkey 디렉터리의 기본 TurnkeyManifest.xml은 언제나 이 프로세스의 시작점이 되며, 원하는 횟수만큼 매니페스트를 연계시킬 수 있고 원하는 방식으로 구성할 수 있습니다.

이 목록의 Manifest 항목은 소스 파일의 파일 레퍼런스와 동일한 포맷 규칙을 따릅니다. 따라서 원격 저장소나 Google Drive 폴더를 비롯한 소스 파일이 있는 모든 위치에 매니페스트를 추가로 둘 수 있습니다. 디렉터리 스트링의 포맷 방식에 대해 자세한 내용은 포맷 규칙 섹션을 참고하세요.

FileSource 항목

FileSource 항목은 작성 방식에 따라서 조직에서 사용할 수 있는 특정 SDK 또는 그룹화된 SDK 항목을 나열합니다. FileSource 항목 내 각 파라미터의 규칙은 아래에 설명되어 있습니다.

Platform

SDK에 대해 지원되는 플랫폼의 이름입니다. 턴키는 이 정보를 사용하여 지정된 플랫폼에 대해 적절한 버전 관리 규칙을 자동으로 결정합니다.

플랫폼 이름은 언리얼 엔진에 내장된 플랫폼 이름 중 하나와 일치해야 합니다. 예를 들어 'Windows'가 아니라 'Win64'를, 'iPhone'이 아니라 'IOS'를 사용해야 합니다.

Type

Type 필드는 전체 SDK 설치를 나열하는지, 플래시 키트처럼 비교적 작은 SDK를 나열하는지 설명합니다. 유효한 SDK 유형은 다음과 같습니다.

유형	설명
Full	SDK 전체 설치로, 주로 개발자가 사용합니다.
AutoSDK	언리얼 엔진에서 필요한 대로 SDK 설치를 설정하는 데 사용할 수 있는 패키지입니다. 전체 SDK와 AutoSDK가 모두 있는 경우 턴키에서는 AutoSDK를 선택합니다.
Flash	개발 키트를 플래싱하는 데 필요한 컴포넌트를 갖춘 최소 설치입니다.

AutoSDK에 대한 자세한 내용은 언리얼 엔진 4 AutoSDK 레퍼런스를 참고하세요.

Version

Version 필드에는 SDK의 버전 번호가 포함됩니다. 모든 플랫폼은 제각기 다른 버전 포맷을 가지므로 이 정보를 정확하게 나열해야 합니다.

$[ExpVersion] 같은 캡처 변수를 사용하여 Source 섹션에서 버전 번호를 캡처한 후 이 섹션의 $(ExpVersion)을 대체 변수로 나열합니다. 자세한 내용은 파일 확장 및 캡처 변수를 참고하세요.

턴키에서 SDK를 스캔할 때 버전 번호는 정수로 변환됩니다. 턴키는 각 플랫폼별로 서로 다른 규칙을 사용하며, 전체 SDK와 플래시 SDK가 서로 다른 버전 포맷을 사용할 경우 이 부분도 고려합니다. 턴키는 SDK의 유효한 버전을 여러 개 비교할 때, 나열된 버전 중에서 가장 높은 변환 정수 값을 선호합니다.

각 플랫폼별로 요구되는 버전 번호 포맷에 대한 내용은 턴키 명령줄에서 Help 명령을 참고하세요.

Name

Name 필드에는 사람이 읽을 수 있는 SDK 표시명이 포함됩니다. 표시 용도로만 사용되므로 원하는 대로 설정할 수 있습니다.

Name 필드에는 FileSource의 다른 위치에서 사용한 캡처 변수에 해당하는 대체 변수도 사용할 수 있습니다. 예를 들어 $[ExpVersion]을 사용하여 버전 번호를 나타낸 경우, Name 필드에서 $(ExpVersion)을 사용하여 캡처 변수가 검색한 값을 대체할 수 있습니다. 캡처 및 대체 변수에 대한 자세한 내용은 파일 확장 및 캡처 변수 섹션을 참고하세요.

Source

Source 필드에는 SDK의 위치를 설명하는 스트링이 포함되어 있습니다. 이 스트링은 턴키에 파일 경로를 읽는 방법을 알려 주는 접두사 세트와 파일 경로 자체, 이렇게 두 부분으로 나뉩니다.

예를 들어 다음과 같은 Source 항목은 로컬 파일 시스템(file: 접두사 사용)에서 Win64 SDK를 찾고 Install.zip이라는 7zip 파일을 검색합니다.

	<Source>file:X:\SdkInstallers\Win64\1.10\Install.zip</Source>

fileexpansion: 접두사를 사용하여 캡처 변수 를 활성화함으로써 파일 제공자의 데이터로 여러 SDK를 반복작업할 수 있습니다. 예를 들어 다음과 같은 Source 항목은 Version 필드에 지정된 버전 번호를 사용합니다.

	<Source>fileexpansion:file:X:\SdkInstallers\Win64\$[ExpVersion]\Install.zip</Source>

이 경우, 특정 파일 경로 하나가 아니라 이 포맷과 일치하는 파일 경로를 모두 검색합니다.

Source 파라미터는 Perforce 저장소를 사용하는 경우 CopyOverride 지정자를 선택적으로 사용하여 턴키에서 검색할 디렉터리를 제한할 수 있습니다. 이 지정자를 사용하는 FileSource 블록에 대해서는 아래 예시를 참고하세요.

소스 스트링과 함께 사용할 수 있는 전체 접두사 및 캡처 변수 목록은 아래 포맷 레퍼런스를 참고하세요.

기타 파라미터

위에 나와 있는 파라미터가 가장 일반적으로 사용되기는 하지만 이외에 특별한 경우에 사용되는 파라미터도 있습니다.

AllowedFlashDeviceTypes

AllowedFlashDeviceTypes 값은 플래시 유형의 SDK에 대해서만 사용됩니다. 이러한 스트링의 값은 타깃 플랫폼에만 의미를 갖습니다. 가능한 값은 지정된 플랫폼의 정보에 나열된 턴키 명령줄의 Help 섹션에서 찾을 수 있습니다. 턴키에서 디바이스 정보를 받을 때 디바이스 유형과 설치된 소프트웨어 버전도 함께 파악합니다. 그런 다음 이러한 정보를 사용하여 최신 여부를 파악하고 설치할 플래시 FileSource를 선택합니다.

예시

다음은 Perforce 저장소에서 AutoSDK 파일을 검색하는 'FileSource' 항목의 예시입니다. 이 예시에서는 Setup.bat 및 Setup.sh 파일을 검색하여 SDK 버전 및 플랫폼별로 FileSource를 하나씩 확장하며, 사용자가 이 SDK 중 하나를 명시적으로 선택하지 않은 한 CopyOverride를 사용하여 턴키가 반복적으로 확장되는 것을 제한합니다. 이를 통해 턴키가 너무 많은 Perforce 파일에서 불필요하게 확장되지 않습니다. 이 같은 행동은 Perforce에서만 적용되는데, 이는 디렉터리가 아닌 파일에서만 작동할 수 있기 때문입니다.

	<FileSource>
	<Platform>listexpansion:ExpPlatform=$(AutoSDKPlatforms)</Platform>
	<Version>$(ExpVersion)</Version>
	<Name>$(ExpPlatform) AutoSdk version $(ExpVersion)</Name>
	<Type>AutoSdk</Type>
	<Source CopyOverride="perforce://depot/CarefullyRedist/Host$(HOST_PLATFORM_NAME)/$(ExpPlatform)/$(Version)/...">
	fileexpansion:perforce://depot/CarefullyRedist/Host$(HOST_PLATFORM_NAME)/$(ExpPlatform)/$[ExpVersion]/Setup.*
	</Source>
	</FileSource>

스트링 포맷 레퍼런스

턴키 매니페스트의 스트링은 몇 가지 접두사를 사용하여 지정된 파일 경로를 읽을 방법을 결정합니다. 사용하는 접두사에 따라, 파일 경로는 읽는 시점에 추가 정보로 확장할 커스텀 변수를 통합할 수 있습니다. 따라서 특정 파일의 파일 경로를 명시적으로 나열하는 것이 아니라 파일 경로의 예상되는 포맷을 지정할 수 있으며, 턴키는 해당 포맷과 일치하는 파일을 모두 검색합니다.

사본 제공자

사본 제공자 접두사는 턴키가 뒤에 붙는 파일 경로를 파싱할 때 검색해야 할 위치 유형을 결정합니다. 턴키는 세 가지 유형의 위치를 인식하며, 각 위치 유형의 접두사는 예상되는 파일 경로 유형의 규칙을 갖습니다.

접두사	설명	파일 경로 예시
`file:`	턴키는 SDK 인스톨러에서 사용하는 로컬 파일 시스템을 검색합니다. 이 접두사는 파일이 위치한 드라이브를 포함하는 표준 파일 경로를 예상하며, 공유 네트워크 드라이브를 포함할 수 있습니다. MacOS의 경우에는 SMB 공유를 마운트할 `smb:` 접두사가 추가로 필요합니다.	`file:X":\SdkInstallers\$[ExpPlatform]\$[ExpVersion].Install.zip` `file:smb:X":\SdkInstallers\$[ExpPlatform\$[ExpVersion].Install.zip`
`perforce:`	턴키는 Perforce 스트림에 연결하여 SDK 인스톨러를 검색합니다. 이 접두사는 항상 특정 파일 컴포넌트를 포함하고 파일 확장명으로 끝나는 표준 Perforce 파일 사양을 필요로 합니다. 또한 이 변수를 처음 사용하는 경우에는 턴키에서 Perforce 클라이언트의 위치를 파악할 수 있도록 허용하기 위해 클라이언트 사양을 제공해 달라는 알림이 표시될 수 있습니다.	`file:X":\SdkInstallers\$[ExpPlatform]\$[ExpVersion].Install.zip` `file:smb:X":\SdkInstallers\$[ExpPlatform\$[ExpVersion].Install.zip`
`googledrive:`	턴키는 Google Drive에 연결하여 SDK 인스톨러를 검색합니다. 파일 경로의 첫 번째 부분은 살펴볼 공유 드라이브 이름을 나타내며, 나머지 모든 경로 부분은 해당 드라이브의 하위 폴더 이름을 나타냅니다.	`googledrive:/SdkInstallers/$[ExpPlatform]/$[ExpVersion].Install.zip`

로컬 파일을 사용하면 사용자의 머신에 있는 SDK 인스톨러를 사용할 수 있기 때문에 추가 구성 작업이 제일 적습니다. 하지만 이 구성에는 대부분 추가 유지보수가 필요하기 때문에 각 사용자는 반드시 SDK 인스톨러가 위치한 로컬 폴더를 일관되게 유지해야 합니다. 사용자 머신의 로컬 드라이브 대신 공유 네트워크 드라이브를 사용할 수도 있지만 공유 드라이브의 속도에 따라 다소 느릴 수 있습니다.

Google Drive를 사용하면 추가 구성 작업을 가장 많이 수행해야 하는데, 이는 Google Drive API를 사용하는 계정을 구성하여 엔진 파일과 함께 사용자에게 OAuth 2.0 크리덴셜을 제공해야 하기 때문입니다. 하지만 일단 구성을 마친 후에는 조직 관리자가 수행해야 하는 유지관리 작업은 단순해집니다. 자세한 내용은 언리얼 턴키용 Google Drive 구성을 참고하세요.

Perforce 스트림을 사용할 경우 조직에서 SDK 파일을 저장할 중앙 위치를 생성하게 되므로 두 방식 간에 균형 잡힌 솔루션이 될 수 있지만, 조직에서 Perforce 스트림을 구성하고 사용자가 여기에 액세스할 수 있는 크리덴셜도 제공해야 합니다.

이외의 소스 컨트롤 옵션에 대한 지원을 턴키에 추가해야 하는 경우에는 엔진 소스 코드를 변경하여 새로운 유형의 사본 제공자를 추가할 수 있습니다. GoogleCopyProvider, PerforceCopyProvider, 및 NullCopyProvider를 예시로 참고하세요.

파일 확장 및 캡처 변수

fileexpansion: 접두사를 사용하면 턴키에서 특정 SDK에 대한 경로가 아닌 일반 포맷과 일치하는 경로를 검색할 수 있습니다. 따라서 다운로드하지 않아도 되는 SDK의 서버 호출 수를 줄이고 모든 SDK 항목을 개별적으로 작성하지 않고도 SDK를 폭넓게 트래킹할 수 있습니다. 예를 들어 새 인스톨러를 서버에 업로드할 수 있으며, 해당 디렉터리 구조가 FileSource 항목에 나열된 예상 포맷과 일치하는 한 매니페스트를 수정하지 않고도 파일 확장을 통해 이 인스톨러를 검색할 수 있습니다.

fileexpansion: 접두사를 사용할 때는 파일 확장이 사본 제공자의 정보에 의존하기 때문에 반드시 file: 또는 googledrive:등의 사본 제공자 접두사를 뒤에 붙여야 합니다.

경로에 fileexpansion:을 추가한 다음에는 캡처 변수 로 해당 경로를 대체할 수 있습니다. 이러한 변수는 $[xyz] 포맷을 사용하며, 여기서 xyz는 사용자가 정의한 임의의 스트링으로 대체됩니다. 턴키에서 매니페스트를 읽으면 사용자와 파일 제공자가 제공한 정보를 통해 이를 확장합니다.

다음과 같은 소스 스트링을 사용하는 예시를 들 수 있습니다.

	fileexpansion:file:X:\Installers\$[ExpPlatform]\$[ExpVersion]\Install.bat

이 경우, 턴키는 $[ExpPlatform] 및 $[ExpVersion] 캡처 변수를 와일드카드 값(* 문자)으로 변환합니다. 그런 다음 fileexpansion: 접두사 뒤에 사용되는 사본 제공자, 즉 이 경우에는 로컬 파일 시스템에 값을 전달합니다. 그러면 제공자는 사용 가능한 파일과 폴더를 반복작업하여 각 캡처 변수별로 캡처된 값과 함께 제공된 포맷과 일치하는 결과 목록을 반환합니다.

	X:\Installers\Win64\1.00\Install.bat [ $(ExpPlatform) = Win64, $(ExpVersion=1.00)]
	X:\Installers\Win64\2.00\Install.bat [ $(ExpPlatform) = Win64, $(ExpVersion=2.00)]
	X:\Installers\Android\10.1a\Install.bat [ $(ExpPlatform) = Android, $(ExpVersion=10.1a)]

턴키는 이러한 각 항목에 대해 C# 형식의 FileSource 오브젝트를 생성하며, 이는 SDK 인스톨러 다운로드 소스로 검색됩니다. 캡처 변수에 의해 확장된 파일 경로 부분은 FileSource 오브젝트가 다른 필드에서 참조할 수 있는 $(xyz) 형식의대체 변수 로 변환됩니다. 예를 들어 $[ExpVersion]을 소스 경로에서 사용하는 경우 Version 필드에서 $(ExpVersion)을 사용할 수 있습니다.

캡처 변수는 파일 경로의 파일명, 디렉터리, 심지어 이름의 일부까지 모든 부분을 나타낼 수 있습니다.

	fileexpansion:file:X:\Installers\$[ExpPlatform]\Installer_$[ExpVersion].zip

예를 들어 위 항목은 인스톨러가 해당 플랫폼 폴더에 존재하며, .zip 파일에 Installer_1.00.zip이나 Installer_2.00.zip 같은 이름으로 포함되어 있을 것이라고 예상합니다.

목록 확장

listexpansion: 접두사는 서버에 쿼리하지 않아도 되는 값 목록을 가진 변수를 정의합니다. listexpansion으로 변수를 정의하면 FileSource의 다른 항목에서도 사용할 수 있습니다.

예를 들어 다음 텍스트는 Platform 항목에서 listexpansion을 정의하고 Name 항목에서 해당 목록을 참조합니다.

	<Platform>
	listexpansion:ExpPlatform=Windows,Android,IOS
	</Platform>
	<Name>$(ExpPlatform) Installer</Name>

턴키에서는 이 텍스트를 읽고 Windows, Android, iOS의 FileSource 오브젝트를 개별적으로 생성한 후 각각에 대해 $(ExpPlatform)을 적절히 대체합니다. 이 기능은 listexpansion에서 제공하는 목록을 사용하기 때문에 턴키에서 서버에 쿼리하지 않아도 됩니다. 따라서 SDK가 포함된 플랫폼 목록이 목록 확장에서 생성된 경우 턴키의 초기 시작 속도가 빨라질 수 있습니다.

또한 목록 항목을 직접 나열하지 않고 XML 변수를 사용하여 저장할 수도 있습니다.

	<SavedSetting hostplatform="Win64">

		<Variable>AllowedPlatforms</Variable>

		<Value>Windows,Android</Value>

	</SavedSetting>

	...

	<Platform>listexpansion:ExpPlatform=$(AllowedPlatforms)</Platform>

내장 변수

턴키에서는 사용자 정의 캡처 및 대체 변수와 함께 파일 경로를 정의하는 내장 변수를 몇 가지 지원합니다.

변수	설명
`$(ThisManifestDir)`	현재 처리 중인 `TurnkeyManifest.xml` 파일의 디렉터리로 확장합니다. 여기에는 매니페스트의 현재 위치에 대한 제공자 접두사가 포함되어 있으므로 Perforce 디렉터리에서 검색된 경우 직접 정의할 필요 없이 `perforce:` 접두사를 자동으로 포함하게 됩니다. 이 변수를 사용하면 매니페스트와 관련된 각 디렉터리의 위치가 일관적인 경우에 한해 디렉터리 구조 전체를 재배치할 수도 있습니다.
`$(EngineDir)`	언리얼 엔진 설치 루트 폴더입니다. 소스 컨트롤에 체크인된 파일을 사용하고 있는 경우 유용한 레퍼런스 위치입니다.
`$(HOST_PLATFORM_NAME)`	호스트 플랫폼의 이름입니다. 보통 Win64, Mac 또는 Linux가 됩니다.
`$(UE_STUDIO_TURNKEY_LOCATION)`	스튜디오 차원의 턴키 디렉터리 위치로 설정할 수 있는 환경 변수입니다.