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:

1. In the Unity Editor, open the Build Settings window (menu: File > Build Settings…)
2. In the Platform list, select Android
3. 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:

1. 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.
2. 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.

By 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:

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