Gradle error-prone plugin

This plugin configures JavaCompile tasks to use the error-prone compiler.

Requirements

This plugin depends on Gradle internal APIs, and is only guaranteed to work with the Gradle version it's been tested against. It also depends on Javac internal APIs, directly exposed by error-prone.

Gradle error-prone plugin version	Supported Gradle versions	Supported error-prone version	Supported javac version
0.0.1, 0.0.2	1.8 - 1.11	1.+	7
0.0.3	1.8 - 1.12	1.+	7
0.0.4	2.1	1.+	7
0.0.5	2.2 - 2.3	1.+	7
0.0.6	2.2 - 2.3	1.+¹, 2.+	7, 8
0.0.7, 0.0.7.1	2.4 - 2.5	1.+¹, 2.+	7, 8
0.0.8	2.6 - 3.4	1.+¹, 2.+	7, 8
0.0.9	2.6 - 3.4	1.+¹, 2.+	7, 8
0.0.10	2.6 - 4.7	1.+¹, 2.+	7, 8
0.0.11	2.6 - 4.7	1.+¹, 2.+	7, 8
0.0.12	2.6 - 4.7	2.+	8
0.0.13	2.6 - 4.7	2.+	8, 9
master	2.6 - 4.7	2.+	8, 9

¹: error-prone 1.x is only supported with JDK 7

Note: Gradle 2.0 is not supported; it lacks APIs to manipulate the actual compiler being used. Similarly, Gradle 3.5-rc-1 removed APIs this plugin uses, they've been reintroduced in 3.5-rc-2.

Usage

To use the error-prone plugin, first add it to your project following the instructions from the Gradle Plugin Portal¹, then make sure you have a repository configured that contains the com.google.errorprone:error_prone_core dependency; for example:

repositories {
  mavenCentral()
}

¹: For older versions of the plugins, please read the according version of this README

When applied, the net.ltgt.errorprone plugin automatically changes all JavaCompile tasks in the project to use the error-prone compiler. (Note: earlier versions used errorprone as the plugin identifier instead of net.ltgt.errorprone.)

You can configure the error-prone compiler using the JavaCompile's options.compilerArgs, for example:

tasks.withType(JavaCompile) {
  options.compilerArgs += [ '-Xep:DeadException:WARN', '-Xep:GuardedByValidator:OFF' ]
}

The plugin adds an errorprone configuration that automatically uses the latest release of error-prone. You can override it to use a specific version with:

dependencies {
  errorprone 'com.google.errorprone:error_prone_core:2.0.21'
}

or, for versions of the plugin before (and including) 0.0.8:

configurations.errorprone {
  // 2.0.5 is the last version compatible with JDK 7
  resolutionStrategy.force 'com.google.errorprone:error_prone_core:2.0.5'
}

If you forked error-prone and changed the groupId, use:

dependencies {
  // Use my.company fork of error-prone
  errorprone "my.company.errorprone:error_prone_core:latest.release"
}

or, for versions of the plugin before (and including) 0.0.8:

// Use my.company fork of error-prone
configurations.errorprone {
  resolutionStrategy.eachDependency { DependencyResolveDetails details ->
    if (details.requested.group == 'com.google.errorprone') {
      details.useTarget "my.company.errorprone:${details.requested.name}:latest.release"
    }
  }
}

Advanced usage

If you want more control as to which task to change, you can apply the net.ltgt.errorprone-base plugin instead, which doesn't reconfigure any task. You'll then configure each task as follows (using the compileJava task as an example):

import net.ltgt.gradle.errorprone.ErrorProneToolChain

compileJava {
  toolChain ErrorProneToolChain.create(project)
}

You can go further and provide a configuration containing the com.google.errorprone:error_prone_core dependency (defaults to configurations.errorprone). The above configuration is thus equivalent to:

import net.ltgt.gradle.errorprone.ErrorProneToolChain

compileJava {
  toolChain new ErrorProneToolChain(configurations.errorprone)
}

Troubleshooting

If your build fails with a compiler error, before opening an issue here, first make sure you're not suffering from a dependency misconfiguration, or hitting an Error Prone bug.

Dependency configuration issue

Run gradle dependencies --configuration errorprone and check that your build doesn't mistakenly override any dependency version.

This could be the case if you're using the Spring Dependency management plugin, or the Nebula Resolution Rules Plugin, Nebula Dependency Recommender, or Nebula Blacklist Plugin.

Error Prone bug

Re-run your Gradle build with --debug and locate the compiler arguments in the outputs.
The plugin should output a line with Compiling with error-prone compiler; you can also search for -sourcepath in the output.
Download the standalone Error Prone compiler (make sure you use the same version), and run it with those arguments.
You might have to add an empty-string argument after -sourcepath (rendering of the arguments in Gradle output might omit the quotes for that empty string)

If those steps reproduce the issue, then it's an ErrorProne bug (in which case please report the issue to the Error Prone project); otherwise it might be a gradle-errorprone-plugin bug (and then I'd need a repro case to debug what's happening).

You can also try using different versions of Error Prone. If that fixes your problem, then again it likely is not a gradle-errorprone-plugin bug.

artem-zinnatullin / gradle-errorprone-plugin Goto Github PK