최신 Xcode 워크플로

언리얼 엔진(UE) 5.3 이상은 표준 Xcode 앱 프로젝트와의 일관성 향상을 위해 언리얼 엔진용 Xcode 프로젝트의 워크플로를 업데이트합니다. 새로운 프로젝트 셋업은 Xcode 개발자의 정리와 삶의 질을 향상시키고, 코드 서명 및 프로비저닝을 간소화하기 위해 다음을 포함한 Xcode 내의 여러 툴에 대한 액세스를 제공합니다.

• 자동 코드 서명

• 권한 관리

• .plist 파일 편집

• 표준 Xcode 프레임워크 처리

이 페이지에서는 구버전에서 UE 5.3 이상(5.3+)으로 전환하는 사용자를 위해 변경사항을 간략하게 설명합니다.

전제 조건

업데이트된 Xcode 워크플로 UE 5.3 이상에서 사용할 수 있으며 새 프로젝트에 대해 기본적으로 활성화됩니다. 그러나 수동으로 활성화해야 하는 경우 다음 단계를 따르세요.

1. 엔진의 설치 디렉터리를 연 다음 Engine/Config/BaseEngine.ini를 열고, 다음 환경설정 변수가 설정되어 있는지 확인합니다.

   Engine/Config/BaseEngine.ini

   C++

   [/Script/MacTargetPlatform.XcodeProjectSettings]
        bUseModernXcode=true

   Copy full snippet(2 lines long)

2. 엔진과 프로젝트 모두에 대한 Xcode 프로젝트 파일을 다시 생성합니다. UE의 소스 빌드를 사용하는 경우, 엔진 설치 디렉터리에서 GenerateProjectFiles.command 스크립트를 실행하여 UE 소스 코드용 프로젝트 파일을 다시 생성하세요. 프로젝트 디렉터리에 다음 세 개의 Xcode 워크스페이스 파일이 있어야 합니다.

   • UE5 (Mac).xcworkspace

   • UE5 (TVOS).xcworkspace

   • UE5 (IOS).xcworkspace

이제 새로운 Xcode 구성을 사용할 준비가 되었습니다. 다음 섹션에서는 이전 프로젝트 구성과 비교하여 새로운 기능을 설명합니다.

프로젝트, 스키마 및 빌드 환경설정

이전 UE Xcode 프로젝트는 스키마(Schemes) 아래에 타깃(targets)과 빌드 환경설정(build configurations)을 결합했습니다. 예를 들어, 단일 프로젝트(MyProject)에서 사용자는 에디터 타깃의 개발 빌드를 제작하는 "개발 에디터(Development Editor)" 스키마가 있었습니다.

UE 5.3+는 각 타깃 타입에 대해 별도의 Xcode 프로젝트(동일한 Xcode 워크스페이스 내)를 제공합니다. 예를 들어 'MyProject'라는 프로젝트의 Xcode 워크스페이스에는 MyProjectEditor, MyProjectGame, MyProjectClient, MyProjectServer에 각각 별도의 프로젝트가 있습니다.

각 타깃에는 지원하는 빌드 환경설정만 있습니다. 예를 들어 대부분의 에디터는 테스트 또는 배포 환경설정을 지원하지 않으므로 에디터 프로젝트에서 사용할 수 없습니다.

업데이트된 워크스페이스에는 많은 스키마가 있습니다. 스키마를 살펴볼 때 필요에 따라 필터(Filter) 및 최근(Recent) 섹션을 사용하여 목록의 범위를 좁히세요.

플랫폼별 워크스페이스

이전에는 UE가 프로젝트 파일을 생성할 때 각 Apple 플랫폼의 타깃을 포함하는 하나의 모놀리식 워크스페이스를 생성했습니다.

UE 5.3+에서는 UE가 프로젝트 파일을 생성할 때 각 Apple 플랫폼에 대해 별도의 워크스페이스를 생성합니다.

이는 워크스페이스와 프로젝트를 간소화하며, Xcode는 여러 워크스페이스를 열 수 있으므로 Command + `(백틱)을 눌러 플랫폼 간에 전환할 수 있습니다.

각 워크스페이스에는 해당 플랫폼을 지원하는 타깃만 있으므로 iOS와 tvOS에서는 사용 가능한 스키마가 더 적습니다. UnrealEditor 타깃이 있지만 성공적으로 빌드할 수 없습니다. 대신 이러한 타깃은 소스 코드를 검색에 사용할 수 있도록 하기 위해 존재합니다.

독립형 앱

이전에 UE는 iOS, iPadOS, tvOS 앱을 실행하는 데 필요한 모든 데이터를 각각의 .app 파일로 번들화하여 독립형으로 만들었습니다. 그러나 macOS 프로젝트는 .app, Saved/Cooked/Mac 디렉터리, 엔진 및 프로젝트 디렉터리의 다른 위치 간에 데이터를 분할합니다.

UE 5.3+에서는 모든 Mac 플랫폼이 동일한 워크플로를 사용합니다. 즉, 필요한 데이터를 한 위치에 모아 수동으로 또는 Xcode로 실행할 수 있는 .app으로 묶습니다. 이렇게 하려면 쿠킹 프로세스에서 스테이지(Stage) 단계를 사용해야 합니다.

패키지 및 배포

macOS 및 iOS/tvOS/iPadOS의 패키징 프로세스는 이제 완전히 일치합니다.

배포

배포 모드는 더 이상 배포 인증서를 사용하여 코드 서명을 하지 않습니다. 대신, App Store나 팀과 같은 다양한 대상에 .app을 배포하는 데 사용할 수 있는 표준 Xcode 아카이브(.xcarchive )를 생성합니다. 배포 빌드를 만들 때 Xcode는 Xcode 아카이브에 넣을 .dSYM 파일도 생성합니다. 이는 크래시 디버깅에 유용하며 라이브 크래시 디버깅을 위해 Apple로 보낼 수 있습니다. 제출을 위해 Apple에 앱을 업로드할 때 앱과 함께 .dysm을 제출합니다.

일반적으로 패키징하려면 언리얼 에디터에서 플랫폼(Platforms) > 프로젝트 패키지(Package Project)를 클릭하거나 BuildCookRun 명령줄에 -package -clientconfig=Shipping을 추가하세요.

배포용으로 패키징하려면 프로젝트 세팅(Project Settings)에서 배포(Distribution) 체크 박스를 선택하거나 BuildCookRun 명령줄에 -package -clientconfig=Shipping -distribution을 추가하세요.

또는 Xcode에서 제품(Product) > 아카이브(Archive)를 클릭해도 됩니다.

Xcode는 .xcarchive를 생성할 때 스테이징된(Staged) 디렉터리 및 코드 서명 프레임워크 가져오기 등의 표준 워크플로를 사용합니다. 스키마를 개발(Development)로 설정한 경우에도 배포(Shipping) 환경설정을 사용합니다.

Xcode에서 아카이브를 사용하면 자동으로 아카이브(Archives) 창이 열리고 새 아카이브가 선택됩니다. 다른 UE 메서드를 사용하여 생성하는 경우 창(Window) > 오거나이저(Organizer)를 클릭하여 창을 수동으로 연 다음 좌측 상단에서 프로젝트와 아카이브를 선택해야 합니다.

아카이브(Archives) 창 오른쪽에 있는 버튼을 사용하여 앱을 유효성 검사(Validate)하거나 배포(Distribute)하세요. 이를 사용하여 각 옵션의 프롬프트에 따라 내부용 iOS .ipa 파일을 생성할 수 있습니다. App Store 유효성 검사/배포를 위해서는 appstoreconnect.apple.com에서 앱(App) 항목을 작성해야 합니다.

앱을 배포하거나 유효성을 검사하라는 메시지에서는 배포 인증서를 선택하거나 다른 프로비저닝 단계를 따라야 할 수도 있습니다. 자세한 내용은 Apple 문서를 참고하세요.

Xcode의 아카이브는 배포(Shipping)를 사용합니다. 이는 UE가 생성하는 스키마의 아카이브 작업에 대한 디폴트 환경설정이기 때문입니다. 또한 -package -distribution은 build 작업 대신 백그라운드에서 archive Xcode 작업을 사용합니다.

테스트에 필요한 경우 스키마에서 이를 변경할 수 있지만 배포 빌드만 배포하는 것이 좋습니다.

MacOS에서 앱의 표시명 환경설정

앱의 표시명(Display Name)은 아카이브된 빌드를 만들 때 Mac .app의 이름입니다. 배포용 패키지를 만들 때나 Xcode에서 아카이브 메뉴를 사용할 때 표시명이 .app의 이름이 되며, 사용자가 파인더(Finder)를 사용할 때 표시되는 이름입니다. 설정하지 않으면 .app의 이름이 .uproject 파일의 이름과 같아집니다. UE 5.3.2 이상에서 표시명을 변경하려면, MacEngine.ini 파일을 열고 다음과 같이 ApplicationDisplayName 환경설정 변수를 설정하세요.

MacEngine.ini

[Xcode]
	ApplicationDisplayName="Friendly Application Name"

콘텐츠/블루프린트 전용 프로젝트

콘텐츠 전용(또는 블루프린트 전용) 프로젝트에는 Xcode 프로젝트나 빌드 타깃 소스 파일이 없기 때문에 프로젝트별 데이터와 결합된 엔진의 일반 UnrealGame 타깃을 재사용하여 빌드를 생성합니다.

표준 Xcode 사례

업데이트된 Xcode 워크플로는 Xcode를 사용하여 다음을 포함한 표준 Xcode 워크플로에 따라 가능한 한 많은 컴포넌트를 처리합니다.

• 코드 서명.

• .plist 파일.

• 권한 파일.

• 프레임워크.

코드 서명

이전에는 iOS/iPadOS/tvOS에만 코드 서명이 필요했습니다. 2023년부터 Apple은 macOS에도 코드 서명을 요구합니다. 업데이트된 워크플로는 기본적으로 모든 플랫폼에 Xcode의 자동 코드 서명(Automatic Codesigning)을 사용합니다.

자동 코드 서명을 사용하려면 다음 단계를 따르세요.

1. Xcode에서 Apple 개발자 계정에 로그인합니다.

2. 프로젝트 세팅(Project Settings)을 열고 플랫폼(Platforms) > Xcode 프로젝트(Xcode Projects)를 찾아 다음 프로퍼티를 설정합니다.

   

팀 ID 찾기

최신 서명 팀(Modern Signing Team) 세팅을 위해 팀 ID를 찾으려면 Apple 개발자 페이지를 열고 계정에 로그인한 후 멤버십 디테일(Membership Details)을 클릭하세요. 팀 ID가 표시됩니다.

.plist 파일

모든 앱에는 임베드된 .plist 파일이 포함되어야 합니다. 최종 .plist 파일은 일반적으로 Xcode가 Xcode 프로젝트 세팅에 따라 수정하는 부분(템플릿)으로 만들어집니다. UE가 Xcode 프로젝트를 생성하기 때문에 이는 복잡한 프로세스가 될 수 있습니다.

업데이트된 Xcode 워크플로는 .plist 파일을 처리하는 높은 수준의 제어 기능을 제공합니다. 또한 이제 Xcode에서 .plist 세팅 편집이 지원됩니다.

템플릿과 사전 생성 비교

Xcode에서는 UE에서 생성한 Xcode 프로젝트의 세팅을 사용하여 앱에서 .plist를 마무리하는 것이 좋습니다. 하지만 UE는 Xcode가 수정하지 않는 사전 생성한 .plist 파일도 지원합니다. 이는 고급 기능이므로 Xcode 프로젝트 세팅(Project Setting)에 노출되지 않으며 환경설정 파일을 편집해야 합니다. 지침은 아래의 사전 생성 .plist 사용하기를 참조하세요.

프로젝트 세팅의 .plist 세팅(Mac Target Info.plist 및 IOS Target Info.plist 항목)은 디폴트 .plist 템플릿 또는 커스텀 .plist 템플릿을 지정할 수 있는 방법을 제공합니다.

Template.plist 파일의 디폴트 위치는 프로젝트의 Build/IOS 디렉터리입니다. UE가 프로젝트에 대한 Xcode 프로젝트 파일을 생성할 때 프로젝트에 .plist 템플릿 파일이 있는지 확인하고, 없으면 엔진에서 프로젝트 폴더로 .plist를 복사합니다.

UnrealEditor 타깃에는 고유한 .plist가 있습니다. .app은 모든 프로젝트에 공유됩니다. 대부분 사용자는 사용할 일이 없습니다.

사전 생성 .plist 사용

사전 생성 .plist를 사용하려면 DefaultEngine.ini 파일을 수정하고 사용하려는 파일의 경로와 함께 다음 세팅 중 하나 또는 둘 모두를 설정하세요.

DefaultEngine.ini

[/Script/MacTargetPlatform.XcodeProjectSettings]
	PremadeMacPlist=(FilePath="/Game/Build/Mac/Resources/MyGameMac.plist")
	PremadeIOSPlist=(FilePath="/Game/Build/IOS/Resources/MyGameIOS.plist")

.plist를 디폴트로 복원

Info.plist를 디폴트로 복원(Restore Info.plist to default) 버튼을 사용하여 엔진 디렉터리의 Mac 디폴트 .plist 템플릿 파일을 프로젝트에 다시 복사하고 값을 적절하게 설정할 수도 있습니다. 이는 향후 UE 버전에서 업데이트된 디폴트 .plist 파일을 사용하려는 경우 유용할 수 있습니다.

생성된 앱에서 .plist 파일을 가져와 사전 생성 .plist의 소스로 사용할 수 있습니다.

프라이버시 매니페스트

Xcode는 프라이버시 매니페스트(Privacy Manifests)를 사용하여 앱이 사용자에게서 어떤 종류의 데이터를 수집하는지, 그 이유는 무엇인지를 선언하도록 요구합니다. 여기에는 자체 코드로 수집하는 데이터와 사용 중인 타사 SDK가 수집하는 데이터가 포함됩니다. 앱을 배포할 때 Xcode는 SDK와 앱의 프라이버시 매니페스트를 하나의 개인정보 보호 보고서로 합하여 사용자에게 앱의 개인정보 보호 관행에 대한 투명한 정보를 손쉽게 제공할 수 있습니다.

UE의 기본 프라이버시 매니페스트는 아래에 위치합니다.

• MacOS: Engine/Build/Mac/Resources/UEMetadata/PrivacyInfo.xcprivacy

• iOS, tvOS, iPadOS: Engine/Build/iOS/Resources/UEMetadata/PrivacyInfo.xcprivacy

추가적인 개인정보 보호 기능을 사용하는 프로젝트는 UE 프로젝트 세팅에서 지정한 위치에 추가 PrivacyInfo.xcprivacy 파일을 제공해야 합니다. 해당 위치는 기본적으로 다음과 같습니다.

• MacOS: /Game/Build/Mac/Resources/PrivacyInfo.xcprivacy

• iOS, tvOS, iPadOS: /Game/Build/IOS/Resources/PrivacyInfo.xcprivacy

자세한 내용은 Apple의 프라이버시 매니페스트에 대한 문서를 참고하세요.

MacOS와 iOS 비교

새로운 Xcode 워크플로에서 .plist 파일 작업은 macOS와 iOS 간에 다릅니다. UBT에는 깊이 임베드된 iOS .plist 파일 생성 로직이 있기 때문입니다. 해당 로직을 프로젝트 제네레이터/Xcode로 가져오는 것은 불가능했습니다.

UBT의 디폴트 세팅을 살펴보면 /Game/Build/IOS/UBTGenerated/Info.Template.plst****를 가리키는 것을 볼 수 있는데, 이는 UBT가 실행될 때마다 iOS .plist의 콘텐츠를 변경할 가능성이 있음을 나타냅니다.

그러나 템플릿(또는 사전 생성) .plist 파일을 사용하도록 프로젝트 설정을 변경할 수 있습니다. 그러면 UBT가 생성하는 내용이 무시됩니다. 그렇게 하면 Xcode를 사용하여 .plist 파일을 편집할 수 있습니다.

다음은 Mac과 iOS .plist 파일의 차이점에 대한 개요입니다.

권한

모든 앱은 코드 서명의 일부로 권한(Entitlements)을 지정합니다. 권한은 GameCenter 지원이나 Mac 보안 샌드박스에서의 실행과 같이 Apple에서 만든 일부 기능이나 제한 사항을 제어합니다.

UE의 Xcode 프로젝트 생성은 위의 (Mac) .plist 파일과 유사하게 권한을 처리합니다. UE는 Xcode 프로젝트를 생성하고, 프로젝트의 디폴트 위치에 권한(Entitlements) 파일이 없는 경우 기본적으로 Engine 디렉터리에서 복사됩니다. 그런 다음 Xcode (또는 텍스트 에디터)를 사용하여 프로젝트의 빌드/Mac/권한(Build/Mac/Entitlements) 또는 빌드/IOS/권한(Build/IOS/Entitlements) 아래에 있는 권한을 수정할 수 있습니다.

샌드박스 제한 사항이 다르거나 최종 사용자에게 배포하는 사항에 차이가 있는 경우 배포(Shipping)와 개발(Development)에 별도의 권한을 설정할 수 있습니다. 별도의 기능이 필요하지 않은 경우 동일한 파일을 가리켜야 합니다.

다음은 macOS 및 iOS에 대한 디폴트 권한 세팅입니다.

프레임워크

프레임워크(Frameworks)는 헤더, 라이브러리 및 콘텐츠를 수집하기 위한 Xcode 시스템입니다. 이제 새로운 Xcode 워크플로는 이전 워크플로와 같이 수동으로 복사하고 코드 서명하는 대신 표준 Xcode 메서드를 사용하여 프레임워크를 처리합니다. UE는 Xcode 프로젝트를 생성할 때 빌드 시스템을 사용하여 다양한 빌드 소스 파일에서 레퍼런스된 프레임워크 세트를 찾습니다. 그런 다음, 다이내믹 라이브러리와 콘텐츠를 앱 번들에 복사하고 필요에 따라 코드 서명하도록 Xcode 프로젝트를 설정합니다.

액세스 로그

로그 파일은 샌드박스 세팅과 애플리케이션 실행 방식에 따라 다른 위치에 표시될 수 있습니다.

• 샌드박스가 활성화된 경우:

  • xcode를 통해 실행: ~/Library/Logs/[프로젝트 이름]

  • 더블클릭하거나 터미널을 사용하여 실행: ~/Library/Containers/[앱의 번들 ID]/Data/Library/Logs

• 샌드박스를 비활성화한 경우:

  • ~/Library/Logs/[프로젝트 이름]