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
andonVariantProperties
blocks are removed in version 4.2 beta. - These APIs are replaced with
beforeVariants
andonVariants
in the newandroidComponents
block. BothbeforeVariants
andonVariants
can optionally use aVariantSelector
to reduce the number of variants the callback will run on, based on build type, name or flavor by usingwithBuildType
,withName
andwithFlavor
accordingly. The lambdaonVariants
andbeforeVariants
receives is executed after AGP computes variant combinations inafterEvaluate
. Nesting properties insideonVariants
is removed. - Similar APIs are added to androidComponents to allow separate blocks for UnitTests (
beforeUnitTest
andunitTest
) and AndroidTests (beforeAndroidTest
andandroidTest
) 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 nowVariantBuilder
, and it is used in thebeforeVariants
phase.VariantProperties
is nowVariant
and it is passed to the newonVariants
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.