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.

• The onVariants, onProperties and onVariantProperties blocks are removed in version 4.2 beta.
• These APIs are replaced with beforeVariants and onVariants in the new androidComponents block. Both beforeVariants and onVariants can optionally use a VariantSelector to reduce the number of variants the callback will run on, based on build type, name or flavor by using withBuildType, withName and withFlavor accordingly. The lambda onVariants and beforeVariants receives is executed after AGP computes variant combinations in afterEvaluate. Nesting properties inside onVariants is removed.
• Similar APIs are added to androidComponents to allow separate blocks for UnitTests (beforeUnitTest and unitTest) and AndroidTests (beforeAndroidTest and androidTest) instead of nesting tests inside variants.
• Two classes used by both the old and new way of registering actions for variants were renamed. Variant is now VariantBuilder, and it is used in the beforeVariants phase. VariantProperties is now Variant and it is passed to the new onVariants block.

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.