Gradle AnimalSniffer plugin for Java or groovy projects. AnimalSniffer used to check compatibility with lower java version (when compiling with newer java) or android (sdk version).
Implemented the same way as core gradle quality plugins (checkstyle, pmd etc):
task registered for each source set (animalsnifferMain, animalsnifferTest) and attached to check
task
IMPORTANT
- Plugin will use animalsniffer 1.16 by default, which is not compatible with java 9
- Use version 1.17 (
toolVersion=1.17
) if you need to run on java 9, but note that 1.17 can't be used on java 8 (and that's why it is not set by default)
Advanced features:
- Signature build task
- Check task classpath caching to speed-up consequent checks (useful when check runs often without clean)
- Merging check signatures (when small 3rd party lib signatures used)
- Viewing signature content task
- Configuration extensions:
animalsniffer
- check configurationanimalsnifferSignature
- signature build configuration (optional)
- Tasks:
check[Main]
- check source set taskanimalsnifferSignature
- build signature (active whenanimalsnifferSignature
configuration declared)type:BuildSignatureTask
- custom signature build task may be used to merge signaturestype:SignatureInfoTask
- view signature "contents"
- Dependencies configuration:
signature
- signatures for check
Releases are published to bintray jcenter, maven central and gradle plugins portal.
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'ru.vyarus:gradle-animalsniffer-plugin:1.5.0'
}
}
apply plugin: 'ru.vyarus.animalsniffer'
OR
plugins {
id 'ru.vyarus.animalsniffer' version '1.5.0'
}
IMPORTANT: plugin must be declared after java
or groovy
plugin, otherwise nothing will be registered.
Starting from version 1.5.0 gradle >= 5 is required. For older gradle use version 1.4.6.
Additional tasks will be assigned to check
task. So animalsniffer checks will be executed during:
$ gradlew check
AnimalSniffer requires signature file to check against. To define signature (or multiple signatures) use
signature
configuration.
Check java version compatibility:
repositories { mavenCentral() }
dependencies {
signature 'org.codehaus.mojo.signature:java16:1.1@signature'
}
Check android compatibility:
repositories { mavenCentral() }
dependencies {
signature 'net.sf.androidscents.signature:android-api-level-14:4.0_r4@signature'
}
Check both java version and android compatibility:
dependencies {
signature 'org.codehaus.mojo.signature:java16:1.1@signature'
signature 'net.sf.androidscents.signature:android-api-level-14:4.0_r4@signature'
}
In the last case animalsniffer will run 2 times for each signature. You may see the same errors two times if class/method is absent in both signatures. Each error message in log (and file) will also contain signature name to avoid confusion.
When no signatures defined animalsniffer tasks will always pass.
You can also use custom libraries signatures to check version compatibility.
All project dependencies are excluded from analysis: only classes from your source set are checked.
By default, all source sets are checked. To check only main sources:
animalsniffer {
sourceSets = [sourceSets.main]
}
Violations are always printed to console. Example output:
2 AnimalSniffer violations were found in 1 files. See the report at: file:///myproject/build/reports/animalsniffer/main.text
[Undefined reference] invalid.(Sample.java:9)
>> int Boolean.compare(boolean, boolean)
[Undefined reference] invalid.(Sample.java:14)
>> java.nio.file.Path java.nio.file.Paths.get(String, String[])
NOTE: text report file will contain simplified report (error per line):
invalid.Sample:9 Undefined reference: int Boolean.compare(boolean, boolean)
invalid.Sample:14 Undefined reference: java.nio.file.Path java.nio.file.Paths.get(String, String[])
NOTE: when multiple signatures used, output will contain signature name in the error message to void confusion.
Annotation could be used to suppress violations: examples
Add dependency on annotation:
compile "org.codehaus.mojo:animal-sniffer-annotations:1.16"
Use provided
scope if you can.
Annotation is configured by default, so you can simply use annotation to suppress violation:
@IgnoreJRERequirement
private Optional param;
You can define your own annotation:
package com.mycompany
@Retention(RetentionPolicy.CLASS)
@Documented
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.TYPE})
public @interface SuppressSignatureCheck {}
Configure annotation:
animalsniffer {
annotation = 'com.mycompany.SuppressSignatureCheck'
}
Now check will skip blocks annotated with your annotation:
@SuppressSignatureCheck
private Optional param;
Project could target multiple java versions and so reference classes, not present in signature.
For example, implementation could try to use java 7 Paths
and if class is not available, fall back
to java 6 implementation. In this case Paths
could be added to ignored classes:
animalsniffer {
ignore 'java.nio.file.Paths'
}
Now usages of Paths
will not cause warnings.
Multiple ignored classes could be defined:
animalsniffer {
ignore 'java.nio.file.Paths', 'some.other.Class'
}
Or
animalsniffer {
ignore 'java.nio.file.Paths'
ignore 'some.other.Class'
}
Or by directly assigning collection:
animalsniffer {
ignore = ['java.nio.file.Paths', 'some.other.Class']
}
Entire packages could be ignored using asterisk:
animalsniffer {
ignore 'some.pkg.*'
}
See more info in documentation.
Configuration example:
animalsniffer {
toolVersion = '1.16'
sourceSets = [sourceSets.main]
ignoreFailures = true
reportsDir = file("$project.buildDir/animalsnifferReports")
annotation = 'com.mypackage.MyAnnotation'
ignore = ['java.nio.file.Paths']
}
There are no required configurations - plugin will generate defaults for all of them.
Property | Description | Default value |
---|---|---|
toolVersion | AnimalSniffer version | 1.16 |
sourceSets | Source sets to check | all source sets |
ignoreFailures | False to stop build when violations found, true to continue | false |
reportsDir | Reports directory | file("$project.buildDir/reports/animalsniffer") |
annotation | Annotation class to avoid check under annotated block | |
ignore | Ignore usage of classes, not mentioned in signature | |
signatures | Signatures to use for check | configurations.signature |
excludeJars | Patterns to exclude jar names from classpath. Required for library signatures usage | |
cache | Cache configuration | By default, cache disabled |
NOTE: ignore
does not exclude your classes from check, it allows you using classes not mentioned in signature.
See more details above.
Animalsniffer task is registered for each source set:
animalsnifferMain
- run AnimalAniffer for compiled main classesanimalsnifferTest
- run AnimalSniffer for compiled test classesanimalsnifferSourceSet
- run AnimalSniffer for compiled SourceSet classes
check
task will depend only on tasks from configured in animalsniffer.sourceSets
source sets.
Tasks support text report, enabled by default.
To disable reports for task:
animalsnifferMain.reports.text.enabled = false
or for all tasks:
tasks.withType(AnimalSniffer) {
reports.text.enabled = false
}
Animalsniffer task is a SourceTask and may be configured to include/exclude classes from check.
NOTE: task operate on compiled classes and not sources! Be careful when defining patterns.
For example, to exclude classes in 'invalid' subpackage from check:
animalsnifferMain {
exclude('**/invalid/*')
}
Read wiki for advanced features:
- Build your project signature
- Optimize often check task calls to speed-up consequent checks (useful when check runs often without clean)
- Merging library signatures (when small 3rd party lib signatures used)
- View signature content
- 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