gradle-animalsniffer-plugin

DOCUMENTATION https://xvik.github.io/gradle-animalsniffer-plugin

About

Use AnimalSniffer signatures to check (JDK, android SDK or any library) API compatibility
for java (kotlin, scala, groovy etc.), android and kotlin multiplatform projects.

General tool: signatures could be created for any library to check api compatibility against older library versions.
Android community adopted it for android SDK compatibility verification.

Easy way to check android SDK compatibility for java library.

NOTE: Initially, animalsniffer was created for java compatibility checks, but java signatures
for JDK 9+ are not published due to module nature: use
—release flag
to check JDK 9+ backwards compatibility

compileJava {
  options.release = 11
}

Features:

Works with:
- Java (and related) plugins: java (java-library), kotlin, groovy (only with @CompileStatic), scala,
  or any other jvm language (which plugin use sourceSets)
- Android projects (library and application plugins)
- Kotlin multiplatform projects
Could create signatures for your or any
3rd party
library (to check compatibility against the older library version)
Special task to view signature file contents
Report errors to console (to simplify reaction), text file and CSV (for external tools)
Could merge existing signatures (e.g. for caching)
Compatible with gradle configuration cache (gradle 9+ requirement)
Debug tools to learn or check configuration

Used by:

Mockito for java and android compatibility checks
Okhttp for java and android compatibility checks (using kotlin multiplatform)
Open-telemetry
for android compatibility checks (with custom (gammy-bears based) signatures generation)

Summary

Configuration extensions:
- animalsniffer - check configuration
- animalsnifferSignature - signature build configuration (optional)
Tasks:
- animalsniffer[Target] - check “[target]” sources (source set, android variant or kotlin platform)
- animalsnifferSignature - build signature (active when animalsnifferSignature configuration declared)
- printAnimalsnifferTasks - print registered check tasks
- printAnimalsnifferSourceInfo - print defailed project sources and compile tasks info (for debug reports)
- type:BuildSignatureTask - custom signature build task may be used to merge signatures
- type:SignatureInfoTask - view signature “contents”
Dependencies configuration: signature - signatures for check

Setup

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'ru.vyarus:gradle-animalsniffer-plugin:2.0.0'
    }
}
apply plugin: 'ru.vyarus.animalsniffer'

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

Compatibility

Plugin only works with plugins:

Jvm languages: java-base plugin (activated by any java-related plugin like java, java-library, groovy, scala, org.jetbrains.kotlin.jvm, etc.).
Android: com.android.library or com.android.application plugins (required 7.4.0 or greater)
Kotlin Multiplatform: org.jetbrains.kotlin.multiplatform plugin (required 1.7 or greater).

The plugin is compiled for Java 8 and tested for compatibility with Java 11, 17 and 21.

Gradle	Version
7-8	2.0.0
5	1.7.2
4.x	1.4.6

Snapshots

Snapshots may be used through JitPack or GitHub packages

##### GitHub package

WARNING: Accessing GitHub package requires GitHub authorization!

Access token creation is described here

Add to settings.gradle (top most!) (exact commit hash might be used as version) :

groovy pluginManagement { repositories { gradlePluginPortal() maven { url = 'https://maven.pkg.github.com/xvik/gradle-animalsniffer-plugin' credentials { username = settings.ext.find('gpr.user') ?: System.getenv("USERNAME") password = settings.ext.find('gpr.key') ?: System.getenv("TOKEN") } } } } In global gradle file ~/.gradle/gradle.properties add

gpr.user=<your github user name>
  gpr.key=<your github password or classic token>

(or credentials must be declared in environment: USERNAME/TOKEN (more usable for CI))
Read personal access tokens creation guide
Note that token needs only “package/read” permission
Use plugin snapshot (see the latest published package version):

groovy plugins { id 'ru.vyarus.animalsniffer' version '2.0.1-SNAPSHOT' }

##### JitPack Add to settings.gradle (top most!) (exact commit hash might be used as version) :

groovy
  pluginManagement {
      resolutionStrategy {
          eachPlugin {
              if (requested.id.id == 'ru.vyarus.use-python') {
                  useModule('ru.vyarus:gradle-animalsniffer-plugin:master-SNAPSHOT')
              }
          }
      }
      repositories {
          gradlePluginPortal()      
          maven { url 'https://jitpack.io' }              
      }
  }

Note: this would use the latest snapshot. To use exact commit version, go to
JitPack project page
* Use plugin without declaring version:

groovy
  plugins {
      id 'ru.vyarus.animalsniffer'
  }

Usage

Read documentation

Example projects

Check:

Signature build:

Classes - signature from project classes
Jars - signature from project jars (configuration)
Signatures - signature from other signatures
Mixed - signature from different sources

Full android and multiplatform projects (created with android studio and kotlin init site):

Android - complete android project
Multiplatform: android only - 1 multiplatform target
Multiplatform: android, desktop, server - several multiplatform targets
Multiplatform: desktop, server - 2 targets, without android

Might also like

quality-plugin - java and groovy source quality checks
mkdocs-plugin - project documentation generator
pom-plugin - improves pom generation
java-lib-plugin - avoid boilerplate for java or groovy library project
github-info-plugin - pre-configure common plugins with github related info
java-library generator - java library project generator