AGP 7.0: Next major release for the Android Gradle plugin

DEC 01, 2020

Posted by Murat Yener, Developer Advocate

Today marks the release of the first Canary version of Android Studio Arctic Fox (2020.3.1), together with Android Gradle plugin (AGP) version 7.0.0-alpha01. With this release we are adjusting the version numbering for our Gradle plugin and decoupling it from the Android Studio versioning scheme. In this blog post we'll explain the reasons for the change, as well as give a preview of some important changes we're making to our new, incubating Android Gradle plugin APIs and DSL.

New versioning scheme

With AGP 7.0.0 we are adopting the principles of semantic versioning. What this means is that only major version changes will break API compatibility. We intend to release one major version each year, right after Gradle introduces its own yearly major release.

Moreover, in the case of a breaking change, we will ensure that the removed API is marked with @Deprecated about a year in advance and that its replacement is available at the same time. This will give developers roughly a year to migrate and test their plugins with the new API before the old API is removed.

Alignment with Gradle's version is also why we're skipping versions 5 and 6, and moving directly to AGP 7.0.0. This alignment indicates that AGP 7.x is meant to work with Gradle 7.x APIs. While it may also run on Gradle 8.x, this is not guaranteed and will depend on whether 8.x removes APIs that AGP relies on.

With this change, the AGP version number will be decoupled from the Android Studio version number. However we will keep releasing Android Studio and Android Gradle plugin together for the foreseeable future.

Compatibility between Android Studio and Android Gradle plugin remains unchanged. As a general rule, projects that use stable versions of AGP can be opened with newer versions of Android Studio.

Java 11 requirement

You can still use Java programming language version 8 with AGP 7.0.0-alpha01 but we are changing the minimum required Java programming language version to Java 11, starting with AGP 7.0.0-alpha02. We are announcing this early in the Canary schedule and many months ahead of the stable release to allow developers time to get ready.

Incubating APIs and important API changes

This release of AGP also introduces some API changes. As a reminder, a number of APIs that were introduced in AGP 4.1 were marked as incubating and were subject to change. In fact, in AGP 4.2 some of these APIs have changed. The APIs that are currently incubating do not follow the deprecation cycle that we explain above.

Here is a summary of some important API changes.

Let’s take a look at some of these changes. Here is a sample onVariants block which targets the release build. The onVariants block Is changed to beforeVariants and uses a variant selector in the following example.

```
      android {
      …
      //onVariants.withName("release") {
      // ...
      //}
      …
      }
      androidComponents {
      val release = selector().withBuildType("release")
      beforeVariants(release) { variant ->
      ...
      }
      }

      ```

Similarly onVariantProperties block is changed to onVariants.

```
      android {
      ...
      //onVariantProperties {
      // ...
      //}
      …
      }

      androidComponents.onVariants { variant ->
      ...
      }

      ```

Note, this customization is typically done in a plugin and should not be located in build.gradle. We are moving away from using functions with receivers which suited the DSL syntax but are not necessary in the plugin code.

We are planning to make these APIs stable with AGP 7.0.0 and all plugin authors must migrate to the new androidComponents. If you want to avoid dealing with such changes, make sure your plugins only use stable APIs and do not depend on APIs marked as incubating.

If you want to learn more about other changes coming with this release, make sure to take a look at the release notes.

Java is a registered trademark of Oracle and/or its affiliates.