Gradle for Android
Gradle is an Android build system which automates a number of build processes. This automation means that many common build errors are less likely to occur. Most notably in Unity, it reduces the method reference count in DEX (Dalvik Executable format) files, meaning that you are less likely to come across DEX limit problems. However, due to the differences between Gradle and the default Unity Android build system, some existing projects may be hard to convert to Gradle.
You can either build the output package (APK) using the Gradle build system in Unity, or export the Gradle project and build it in an external tool (such as Android Studio).
To learn more, see Gradle’s resources on Getting Started with Gradle for Android Build.
Building with Gradle for Android
To build your Android build with Gradle in Unity:
- In the Unity Editor, open the Build Settings window (menu: File > Build Settings…)
- In the Platform list, select Android
- Set the Build System drop-down to Gradle (new), then click BuildThe process of compiling your Project into a format that is ready to run on a specific platform or platforms. More info
See in Glossary
Exporting the Gradle project
To export a Gradle project, follow the instructions above, but tick the Export Project option in the Build window before you click Build. When you click Build Unity generates a Gradle project in the specified directory rather than building the APKThe Android Package format output by Unity. An APK is automatically deployed to your device when you select File > Build & Run. More info
See in Glossary. Import this project into Android Studio to make additional modifications or to get full control of the build process.
See Android Studio’s documentation on configuring your build for more information about building an output package (APK).
Providing a custom Gradle build template
You can use a custom build.gradle file for the unityLibrary module when you build the APK from Unity. This file contains specific build instructions specified in template variables. For a list of template variables, see the next section.
To use your own build.gradle file for the unityLibrary module, follow these steps:
- In the Unity Editor, open the Player SettingsSettings that let you set various player-specific options for the final game built by Unity. More info
See in Glossary window (menu: Edit > Project Settings > Player), and select Android. - In the Publishing Settings section, enable the Custom Gradle Template setting.
Unity then generates a default mainTemplate.gradle file in your Project’s Assets/Plugins/Android/ folder. The path to the new file also appears under the Custom Gradle Template option in the Player Settings. Double-click the mainTemplate.gradle file in the Project viewA view that shows the contents of your Assets folder (Project tab) More info
See in Glossary to open it in an external text editor.
mainTemplate.gradle file in the Project view for the unityLibrary moduleBy default, Unity uses the settingsTemplate.gradle file from the Unity install directory to create the settings.gradle file for your build. The settings.gradle file contains project components which are involved in the build process. Unity creates the following components by default, which should always be included in the settings.gradle file:
- launcher
- unityLibrary
Additionally, if you add Android library plugins to your project, Unity automatically includes them in the settings file by replacing the **INCLUDES** entry.
If you want to add additional components to the settings.gradle file that Unity doesn’t include by default, create a settingsTemplate.gradle file in your project’s Assets/Plugins/Android/ folder. This overrides the default template.
If you use your own settingsTemplate.gradle file, it must contain the following lines:
include ':launcher', ':unityLibrary'
**INCLUDES**
which will be replaced by include directives to all your libraries.
Template Variables
These variables can be used in the mainTemplate.gradle file:
| Variable: | Description: |
|---|---|
| DEPS | List of project dependencies See in Glossary; ie the libraries used. |
| API VERSION | API version to build for (eg 25). |
| BUILDTOOLS | SDK Build tools used (eg 25.0.1). |
| TARGETSDKVERSION | API version to taget (eg 25). |
| APPLICATIONID | Android Application ID (eg com.mycompany.mygame). |
| MINIFY_DEBUG | Minify for debug builds enabled (true or false). |
| PROGUARD_DEBUG | Use proguard for minification (true or false.) |
| MINIFY_RELEASE | Minify for release builds enabled (true or false). |
| PROGUARD_RELEASE | Use proguard for minification (true or false). |
| USER_PROGUARD | Custom user proguard file (ie progard-user.txt). |
| SIGN | Complete signingConfigs section if build is to be signed. |
| SIGN_CONFIG | Set to ‘signingConfig signingConfig.release’ if build is signed. |
| DIR_GRADLEPROJECT | Directory where the gradle project is created. |
| DIR_UNITYPROJECT | Directory of your Unity project. |
| MINSDKVERSION | Minimum API version (for example, 25). |
Minification
You can activate Proguard Minification under the Minify setting on the Player window.
Note that proguard can easily strip out code that is actually needed, so often this process needs to be configured carefully. You can generate a custom proguard.txt file by enabling the User Proguard File setting under the same settings as a starting point.
See the ProGuard manual for more information on Proguard.
Errors when building with Gradle
If an error occurs during building for Android using Gradle, Unity displays an error dialog box. Click Troubleshoot to open the Gradle troubleshooting Unity documentation in your system’s browser.
2017–10–02 Page published
Expanded custom build.gradle template section.
New feature in 5.5