Gummy Bears

D8 sugar for all of your animal sniffing needs.

This project provides Animal Sniffer signatures for Android API levels 19 and above that account for additional APIs available via desugaring. Read the Background section below if none of this makes sense.

Background

Animal Sniffer

Animal Sniffer checks your project's binary compatibility with a specific version of a java library. At Toast, we use Animal Sniffer to ensure that libraries consumed by our Android apps do not use any APIs unavailable on our oldest supported devices.

Animal Sniffer works by introspecting your project's bytecode and matching it against a set of signatures. Conveniently, standard sets of signatures for all JDKs and Android SDKs are available on Maven Central. Standard signatures are generated by introspecting the classfiles (i.e. android.jar for Android SDK) and recording all public binary interfaces they expose.

Android

Let's look at Integer.hashCode(int). Per documentation, it was Added in API level 24. Yet it works perfectly fine on API 19. Moreover, when targeting 1.8 bytecode level, the Kotlin compiler will generate calls to this method to compute the hash code of Int fields in a data class.

When the APK is assembled, D8 (the Android Dexer) transforms java bytecode into Android (Dalvik/Art) bytecode. As part of that transformation, it rewrites (or desugars) some instructions and API calls. For example, lambdas are desuraged into anonymous classes, try-with-resources is desugared into a Dalvik-compatible set of instructions that matches the semantics of regular Java's try-with-resources, and Integer.hashCode(int) is rewritten into a call to a synthetic class which is then added to the APK by D8.

This article explains desugaring in detail.

Gummy Bears

The set of desugared methods is defined by the version of D8, which itself is defined by the android gradle plugin, as well as the minimum SDK level.

This project provides a safe and more accurate set of signatures for Android 4.4-10 + Android Gradle 3+. The additional sugary signatures are generated from hand-written stubs. The reference point for the stubs is the D8 source code.

This project also provides experimental sets of signatures for Android Gradle 4's core library desugaring, including java.time, ConcurrentHashMap, etc. The artifacts are tagged with the coreLib classifier and are available for Android 4.4-8.1.

How to use

Specify the latest version com.toasttab.android:gummy-bears-api-${api} as the set of signatures for Animal Sniffer.

Gradle

plugins {
    id 'ru.vyarus.animalsniffer' version '1.5.0'
}

dependencies {
    signature('com.toasttab.android:gummy-bears-api-24:0.3.0@signature')
}

With core library desugaring:

dependencies {
    signature('com.toasttab.android:gummy-bears-api-24:0.3.0:coreLib@signature')
}

Gradle Kotlin DSL

plugins {
    id("ru.vyarus.animalsniffer") version "1.5.0"
}

dependencies {
    add("signature", "com.toasttab.android:gummy-bears-api-24:0.3.0@signature")
}

Maven

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>animal-sniffer-maven-plugin</artifactId>
    <version>1.16</version>
    <configuration>
        <signature>
            <groupId>com.toasttab</groupId>
            <artifactId>gummy-bears-api-21</artifactId>
            <version>0.3.0</version>
        </signature>
    </configuration>
</plugin>

License

This project is licensed under the Apache 2 License - see the LICENSE file for details.

Acknowledgments

👍 to the authors of Animal Sniffer, gradle-animalsniffer-plugin, R8 and D8.