Android용 Gradle
Gradle은 다양한 빌드 프로세스를 자동화하고 일반적인 빌드 오류를 방지하는 Android 빌드 시스템입니다. Unity에서 Gradle은 DEX(Dalvik Executable 포맷) 파일의 메서드 참조 횟수를 줄여줍니다. 즉 DEX 제한 문제가 발생할 가능성이 감소합니다.
Unity는 모든 Android 빌드에 Gradle을 사용합니다. Unity에서 출력 패키지(.apk, .aab)를 빌드하거나, Unity에서 Gradle 프로젝트를 익스포트한 후 Android Studio와 같은 외부 툴로 빌드할 수 있습니다.
| Unity 버전 | Gradle 버전 |
|---|---|
| 2017.1, 2017.2 | 2.14 |
| 2017.4 - 2017.4.16 | 4.0.1 |
| 2017.(2017.4.17부터) | 4.6 |
| 2018.1 | 4.0.1 |
| 2018.2 | 4.2.1 |
| 2018.3, 2018.4 - 2018.4.3f1, 2019.1 - 2019.1.6f1 | 4.6 |
| 2018.4(2018.4.4f1부터), 2019.1(2019.1.7f1부터), 2019.2, 2019.3 | 5.1.1 |
자세한 내용은 다음을 참조하십시오.
- Gradle 사용 방법은 Gradle 사용자 매뉴얼을 참조하십시오.
- 출력 패키지(.apk)를 빌드하는 방법은 빌드 설정에 대한 Android 개발자 문서를 참조하십시오.
- 출력 패키지(.aab)를 빌드하는 방법은 Android 앱 번들에 대한 Android 개발자 문서를 참조하십시오.
Gradle 프로젝트 빌드 또는 익스포트
Gradle 프로젝트를 빌드하려면 다음 절차를 따르십시오.
- Unity 에디터에서 프로젝트에 대한 빌드 설정(메뉴: File > Build Settings)을 엽니다
- Platform 리스트에서 Android가 빌드 타겟으로 선택되었는지 확인합니다. 현재 Android가 빌드 타겟이 아닌 경우 Platform 리스트에서 선택한 후 Switch Platform 버튼을 선택합니다.
다음 버튼을 선택하십시오.
- Build 버튼으로 .apk 파일을 생성합니다.
- Build and Run 버튼으로 .apk 파일을 생성하고, 연결된 기기에 배포한 후 실행합니다.
Unity 프로젝트를 Gradle 프로젝트로 익스포트하려면 Export Project 설정을 활성화한 후 Export 버튼을 선택하십시오. 이렇게 하면 Unity가 지정한 폴더에 Gradle 프로젝트를 생성하고 .apk 파일을 빌드하지 않습니다. 이 프로젝트를 Android Studio 또는 다른 외부 툴로 임포트하여 추가 변경을 수행하거나 해당 툴에서 빌드할 수 있습니다.
익스포트한 Gradle 프로젝트 구조
Unity 2019.3 이상 버전은 다음의 두 가지 모듈이 포함된 Gradle 프로젝트를 만듭니다.
- UnityLibrary 모듈: Unity 런타임 및 프로젝트 데이터가 들어 있습니다. 이 모듈은 다른 Gradle 프로젝트에 통합할 수 있는 라이브러리입니다. 기존 Android 애플리케이션에 Unity를 포함할 때 사용할 수 있습니다.
- Launcher 모듈: 애플리케이션 이름과 모든 아이콘이 들어 있습니다. Unity를 시작하는 간단한 Android 애플리케이션 모듈이며, 자체 애플리케이션으로 대체할 수 있습니다.
build.gradle 템플릿
Gradle 템플릿은 Gradle을 사용하여 Android 앱을 빌드하는 방법을 설명하고 구성합니다. 각 Gradle 템플릿은 하나의 singleGradle 프로젝트를 나타냅니다. Gradle 프로젝트는 다른 Gradle 프로젝트를 포함하거나 사용할 수 있습니다.
Gradle 템플릿은 다음의 파일로 구성됩니다.
| File | 위치 | 포함 |
|---|---|---|
| baseProjectTemplate.gradle | 익스포트한 프로젝트의 root/build.gradle 폴더 | 다른 모든 템플릿/Gradle 프로젝트(저장소 및 Android Gradle 플러그인에 대한 종속성) 간에 공유되는 설정이 들어 있습니다. |
| launcherTemplate.gradle | 익스포트한 프로젝트의 root/launcher/build.gradle 폴더 | Android 애플리케이션을 빌드하는 방법(번들 생성, 서명, APK 분할)에 대한 지침이 들어 있습니다. unityLibrary 프로젝트에 기반하고 .apk 파일 또는 앱 번들을 출력합니다. |
| mainTemplate.gradle | 익스포트한 프로젝트의 root/unityLibrary/build.gradle 폴더 | ‘Unity as a Library’ 기능을 빌드하는 방법에 대한 지침이 들어 있습니다. .aar 파일을 출력합니다. Unity 에디터에서 Unity 템플릿을 커스텀 템플릿으로 덮어쓸 수 있습니다. 자세한 내용은 이 페이지의 커스텀 Gradle 빌드 템플릿 제공 섹션을 참조하십시오. |
| libTemplate.gradle | 다양함 | Unity 프로젝트에 Android 라이브러리 프로젝트가 플러그인으로 포함된 경우에 사용됩니다. |
Gradle 빌드 커스터마이즈
커스텀 Gradle 빌드 템플릿을 제공하고 플레이어 설정 창의 Publishing Settings 섹션에서 축소 옵션을 선택할 수 있습니다.
커스텀 Gradle 빌드 템플릿 제공
Unity에서 APK를 빌드할 때 unityLibrary 모듈에 커스텀 build.gradle 파일을 사용할 수 있습니다. 이 파일에는 템플릿 변수에 지정된 특정 빌드 지침이 들어 있습니다. 템플릿 변수 리스트는 다음 섹션을 참조하십시오.
unityLibrary 모듈에 대한 자체 build.gradle 파일을 사용하려면 다음 절차를 따르십시오.
- Unity 에디터에서 Player 설정(메뉴: Edit > Project Settings > Player)을 열고 Android를 선택합니다.
- Publishing Settings 섹션에서 Custom Gradle Template 설정을 활성화합니다.
그러면 Unity는 프로젝트의 Assets/Plugins/Android/ 폴더에 기본 mainTemplate.gradle 파일을 생성합니다. 또한 플레이어 설정의 Custom Gradle Template 옵션 아래에 새 파일에 대한 경로가 나타납니다. 프로젝트 뷰에서 mainTemplate.gradle 파일을 두 번 클릭하여 외부 텍스트 에디터로 엽니다.
또한 고유한 settings.gradle 파일을 만들 수도 있습니다. 이렇게 하려면 프로젝트의 Assets/Plugins/Android/ 폴더에 settingsTemplate.gradle 파일을 수동으로 만들어야 합니다. Unity는 라이브러리 프로젝트를 포함할 때 이 파일을 사용합니다. 이 프로세스를 오버라이드하지 않으려면 파일에 다음 줄을 포함하십시오.
INCLUDES
Unity는 이 줄을 모든 프로젝트 라이브러리에 대한 include 지시문으로 교체합니다.
IPostGenerateGradleAndroidProject
IPostGenerateGradleAndroidProject은 unityLibrary 모듈에 대한 경로를 반환합니다. 이렇게 하면 모든 요소가 Unity 2019.3 이전 버전과 유사하게 유지되므로 추가 변경이 필요하지 않습니다. 즉 Unity는 여러 버전에서 일관된 방식으로 앱의 매니페스트와 리소스에 도달할 수 있습니다.
템플릿 변수
mainTemplate.gradle 파일은 다음 변수를 포함할 수 있습니다.
| 변수: | 설명: |
|---|---|
| DEPS | 프로젝트 종속성 리스트, 즉 프로젝트가 사용하는 라이브러리입니다. |
| APIVERSION | 빌드할 API 버전입니다(예: 25). |
| MINSDKVERSION | 최소 API 버전입니다(예: 25). |
| BUILDTOOLS | 사용되는 SDK 빌드 툴입니다(예: 25.0.1). |
| TARGETSDKVERSION | 대상으로 할 API 버전입니다(예: 25). |
| APPLICATIONID | Android 애플리케이션 ID(예: com.mycompany.myapp)입니다. |
| MINIFY_DEBUG | 디버그 빌드의 축소를 활성화합니다(true 또는 false). |
| PROGUARD_DEBUG | 디버그 빌드의 축소에 ProGuard를 사용합니다(true 또는 false). |
| MINIFY_RELEASE | 릴리스 빌드의 축소를 활성화합니다(true 또는 false). |
| PROGUARD_RELEASE | 릴리스 빌드의 축소에 ProGuard를 사용합니다(true 또는 false). |
| USER_PROGUARD | 커스텀 사용자 ProGuard 파일(예: proguard-user.txt)입니다. |
| SIGN | 이 빌드가 서명되어 있으면 signingConfigs 섹션을 완성합니다. |
| SIGNCONFIG | 이 빌드가 서명되어 있으면 signingConfig signingConfig.release로 설정됩니다. |
| DIR_GRADLEPROJECT | Unity가 Gradle 프로젝트를 만드는 디렉토리입니다. |
| DIR_UNITYPROJECT | Unity 프로젝트의 디렉토리입니다. |
축소
ProGuard 축소를 사용하여 앱 크기를 줄이고 앱을 최적화합니다. 이 옵션을 활성화하려면 다음 절차를 따르십시오.
- Player 설정(메뉴: Edit > Project Settings > Player)을 열고 Android를 선택합니다.
- Publishing Settings 섹션의 Minify에서 릴리스 빌드, 디버그 빌드 또는 둘 다에 대해 Proguard를 선택합니다.
참고: ProGuard가 앱에 필요한 중요한 코드를 삭제할 수도 있으므로 이 옵션은 신중하게 사용해야 합니다.
커스텀 proguard.txt 파일을 생성하려면 플레이어 설정의 Publishing Settings 섹션에서 User Proguard File 설정을 활성화하십시오. 그러면 프로젝트의 Assets/Plugins/Android/ 폴더에 proguard.txt 파일이 즉시 생성됩니다.
ProGuard에 대한 자세한 내용은 ProGuard 매뉴얼을 참조하십시오.
Gradle로 빌드할 때 발생하는 오류
Gradle을 사용하여 Android용 앱을 빌드할 때 오류가 발생하면 Unity는 오류 다이얼로그를 표시합니다. Troubleshoot 버튼을 선택하여 Gradle 문제 해결 Unity 문서를 시스템 브라우저에서 여십시오.
- 2019.3에서 Android용 ‘Unity as a Library’ 기능 추가됨NewIn20193