About Android Plugin for Gradle 3.0.0

Known issue: If you have an existing Android Studio project that's using an alpha version of Android plugin 3.0.0 (such as 3.0.0-alpha9), you may get the following error when you migrate to Android plugin 3.0.0-beta1 and sync your project: Gradle project refresh failed.

Resolve this issue by selecting Build > Clean Project from the menu bar—you need to perform this action only once for each project. You can then sync your project files with Gradle by clicking Sync Project from the menu bar.

Android plugin 3.0.0-beta1 and higher include the following updates that help address bugs and performance issues of large Android projects:

  • Better parallelism for multi-module projects through fine grained task graph.
  • Variant aware dependency management.
  • Compilation avoidance:
    • New api, implementation, compileOnly and runtimeOnly configurations allow libraries to not always leak their dependencies to their consumers. To learn more, read Use the new dependency configurations.
    • Automatic detection of implementation-only changes (a feature of Gradle since version 3.4).
  • Faster incremental build speed due to per-class dexing. Each class is now compiled into separate DEX files, and only the classes that are modified are re-compiled. You should also expect improved build speeds for apps that set minSdkVersion to 20 or lower, and use legacy multi-dex.
  • Improved incremental resource processing using AAPT2, which is enabled by default. If you are experiencing issues while using AAPT2, you can disable it by setting android.enableAapt2=false in your gradle.properties file and restarting the Gradle daemon by running ./gradlew --stop from the command line.
  • Built-in support for using Java 8 libraries and certain Java 8 language features. Jack is no longer required, and you should first disable Jack to use the improved Java 8 support built into the default toolchain. For more information see how to use Java 8 language features.
  • Android Test Utility. You can now install another test helper APK before your instrumentation tests are run. This makes it easier to use popular testing tools like Test Butler. To have the helper APK installed before your instrumentation tests are run, use the androidTestUtil keyword, as shown in the following example:
    dependencies {
    androidTestUtil 'com.linkedin.testbutler:test-butler-app:1.3.0@apk'
    ...
    }
    
  • Support for the fonts as resources feature introduced in Android 8.0 (API level 26).
  • Support for language-specific APKs with Android Instant Apps SDK 1.1 and higher. For more information, see Set up your build for configuration APKs.

In order to bring about these improvements, there are some breaking changes in the plugin behavior, DSL, and APIs. These breaking changes impact both build files and Gradle plugins. There may also be more breaking changes before the stable release of the plugin, so you should keep checking this page.

For instructions on how to migrate your own project to use this plugin, go to Migrate to the new plugin.

What to expect from performance

The main focus of this version is to address the build performance issues of Android projects with a large number of modules. When using the new plugin with these projects, you should experience the following:

  • Faster configuration time (the times it take to configure all the gradle projects) due to delayed dependency resolution.
  • Dependency resolution only for the projects and variants you are building.
  • Simple changes to code or resources should result in faster incremental build times, especially for changes in modules deep in the dependency graph of an app.

This is a first step, with a strong focus on improving scalability and parallelism, and on improving tasks to be more incremental. You can expect more changes in later preview releases and down the line after the first stable release.

On a test skeleton project with ~130 modules and a large number of external dependencies, but no code/resources, we are seeing the following performance improvements:

Android plugin version + Gradle version Android plugin 2.2.0 + Gradle 2.14.1 Android plugin 2.3 RC1 + Gradle 3.3 Android plugin 3.0 preview + Gradle 4.0-milestone-1
Configuration (e.g. running help) ~2 mins ~9 s ~2.5 s
1-line Java change (implementation change) ~2 mins 15 s ~29 s ~6.4 s

To try the new plugin on your own projects. If you see less of a performance improvement than you expected, we are looking for feedback with build profiling. Please consider using the Gradle Profiler to provide us with more data. File a bug and include a Chrome trace of your build using the Gradle Profiler.

Known issues

  • Loading the Android plugin multiple times in a single build leads to a project sync error. This can occur when you have multiple subprojects that each include the Android plugin in their buildscript classpath. This is a limitation of Gradle’s new variant-aware dependency management, which cannot yet handle matching attributes from different classloaders. To resolve this issue for multi-module builds, make sure that you add the Android plugin to only the build classpath of your top-level build.gradle file, as shown below:

    // Additionally, make sure that you don't wrap this in a
    // subprojects block.
    buildscript {
    ...
    dependencies {
        classpath 'com.android.tools.build:gradle:3.0.0-beta7'
    }
    }
    
    To resolve this issue for composite builds, you additionally need to make sure that, for the main project and each included project that uses the Android plugin, the buildscript classpaths are identical. This also requires the order of the classpaths you add to the buildscript block to be identical. For example, the following results in a build error:
    // The top-level build.gradle file of the project you are building:
    buildscript {
    repositories {
       jcenter()
       google()
    }
    dependencies {
       classpath "com.android.tools.build:gradle:3.0.0-beta7"
       classpath "me.tatarka:gradle-retrolambda:3.7.0"
    }
    }
    
    // The build.gradle file of another project that your build includes:
    buildscript {
    repositories {
       jcenter()
       google()
    }
    dependencies {
      // Note that the order of plugins differs from that
      // of the main project's build.gradle file. This results
      // in a build error.
      classpath "me.tatarka:gradle-retrolambda:3.7.0"
      classpath "com.android.tools.build:gradle:3.0.0-beta7"
    }
    }
    
    Revisit this page to check if a new version of Gradle has fixed this issue.

  • If you're using Gradle's configuration on demand feature, you may get the following error when using Android plugin 3.0.0-alpha5:

    Error:Android Gradle plugin 3.0.0-alpha5 must not be applied to project since
    version 3.0.0-alpha5 was already applied to this project
    
    To get around this build error, update the plugin to 3.0.0-alpha6 or higher.

  • Firebase plugin version 1.1.0 can cause a mismatch in Guava dependencies when using Android plugin 3.0.0-alpha5, resulting in the following error:

    Error:Execution failed for task ':app:packageInstantRunResourcesDebug'.
    com.google.common.util.concurrent.MoreExecutors.directExecutor()Ljava/util/concurrent/Executor;
    

    To get around this build error, add the following to the dependencies block of your project-level build.gradle file:

    dependencies {
      classpath ('com.google.firebase:firebase-plugins:1.1.0') {
                  exclude group: 'com.google.guava', module: 'guava-jdk5'
      }
      ...
    }
    

    For more information, see issue #63180002.

  • While using this plugin with Android Studio, dependencies on local AAR files are not yet supported.

  • To use the Protobufs, you must upgrade the Protobuf plugin to version 0.8.2 or higher.

  • The third party android-apt plugin is no longer supported. You should switch to the built-in annotation processor support, which has been improved to handle resolving dependencies lazily.

  • JAR signing (v1 scheme) does not support file names containing Carriage Return (CR) characters. (See issue #63885809).