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'

OR

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) :

  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):

  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) :

  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:

  plugins {
      id 'ru.vyarus.animalsniffer'
  }

Usage

Read documentation

Example projects

Check:

• Java (including android signatures)
• Groovy
• Kotlin
• Scala
• Android library
• Android application
• Multiplatform
• Multiplatform + android

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

---