-
Notifications
You must be signed in to change notification settings - Fork 742
Commit
- Loading branch information
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -4,13 +4,13 @@ layout: documentation | |
--- | ||
|
||
Our goal is to make it simple to add Error Prone checks to your existing Java | ||
compilation. Please note that Error Prone must be run on JDK 8 or newer. It can be used to build Java 6 or 7 code by setting the appropriate `-source` / `-target` / `-bootclasspath` flags. | ||
|
||
Please join our [mailing | ||
list](http://groups.google.com/group/error-prone-announce) to know when a new | ||
version is released! | ||
|
||
compilation. Please note that Error Prone must be run on JDK 8 or newer. It can | ||
be used to build Java 6 or 7 code by setting the appropriate `-source` / | ||
`-target` / `-bootclasspath` flags. | ||
|
||
Please join our | ||
[mailing list](http://groups.google.com/group/error-prone-announce) to know when | ||
a new version is released! | ||
|
||
## Bazel | ||
|
||
|
@@ -41,37 +41,74 @@ INFO: Elapsed time: 1.989s, Critical Path: 1.69s | |
Edit your `pom.xml` file to add settings to the maven-compiler-plugin: | ||
|
||
```xml | ||
<build> | ||
<plugins> | ||
<plugin> | ||
<groupId>org.apache.maven.plugins</groupId> | ||
<artifactId>maven-compiler-plugin</artifactId> | ||
<version>3.3</version> | ||
<configuration> | ||
<compilerId>javac-with-errorprone</compilerId> | ||
<forceJavacCompilerUse>true</forceJavacCompilerUse> | ||
<!-- maven-compiler-plugin defaults to targeting Java 5, but our javac | ||
only supports >=6 --> | ||
<source>7</source> | ||
<target>7</target> | ||
</configuration> | ||
<dependencies> | ||
<dependency> | ||
<groupId>org.codehaus.plexus</groupId> | ||
<artifactId>plexus-compiler-javac-errorprone</artifactId> | ||
<version>2.8.3</version> | ||
</dependency> | ||
<!-- override plexus-compiler-javac-errorprone's dependency on | ||
Error Prone with the latest version --> | ||
<dependency> | ||
<groupId>com.google.errorprone</groupId> | ||
<artifactId>error_prone_core</artifactId> | ||
<version>2.3.1</version> | ||
</dependency> | ||
</dependencies> | ||
</plugin> | ||
</plugins> | ||
</build> | ||
<profiles> | ||
<profile> | ||
<id>jdk8</id> | ||
<activation> | ||
<jdk>1.8</jdk> | ||
</activation> | ||
<build> | ||
<plugins> | ||
<plugin> | ||
<groupId>org.apache.maven.plugins</groupId> | ||
<artifactId>maven-compiler-plugin</artifactId> | ||
<version>3.8.0</version> | ||
<configuration> | ||
<forceJavacCompilerUse>true</forceJavacCompilerUse> | ||
<fork>true</fork> | ||
<source>8</source> | ||
<target>8</target> | ||
<compilerArgs> | ||
<!-- Using github.com/google/error-prone-javac is required when running on JDK 8. --> | ||
<arg>-J-Xbootclasspath/p:${settings.localRepository}/com/google/errorprone/javac/${javac.version}/javac-${javac.version}.jar</arg> | ||
<arg>-XDcompilePolicy=simple</arg> | ||
<arg>-Xplugin:ErrorProne</arg> | ||
</compilerArgs> | ||
<annotationProcessorPaths> | ||
<path> | ||
<groupId>com.google.errorprone</groupId> | ||
<artifactId>error_prone_core</artifactId> | ||
<version>2.3.1</version> | ||
</path> | ||
</annotationProcessorPaths> | ||
</configuration> | ||
</plugin> | ||
</plugins> | ||
</build> | ||
</profile> | ||
<profile> | ||
<id>jdk9</id> | ||
<activation> | ||
<jdk>[9,)</jdk> | ||
</activation> | ||
<build> | ||
<plugins> | ||
<plugin> | ||
<groupId>org.apache.maven.plugins</groupId> | ||
<artifactId>maven-compiler-plugin</artifactId> | ||
<version>3.8.0</version> | ||
<configuration> | ||
<forceJavacCompilerUse>true</forceJavacCompilerUse> | ||
<fork>true</fork> | ||
<source>8</source> | ||
<target>8</target> | ||
<compilerArgs> | ||
<arg>-XDcompilePolicy=simple</arg> | ||
<arg>-Xplugin:ErrorProne</arg> | ||
</compilerArgs> | ||
<annotationProcessorPaths> | ||
<path> | ||
<groupId>com.google.errorprone</groupId> | ||
<artifactId>error_prone_core</artifactId> | ||
<version>2.3.1</version> | ||
</path> | ||
</annotationProcessorPaths> | ||
</configuration> | ||
</plugin> | ||
</plugins> | ||
</build> | ||
</profile> | ||
</profiles> | ||
``` | ||
|
||
See the | ||
|
@@ -80,8 +117,8 @@ directory for a working example: | |
|
||
``` | ||
../examples/maven/error_prone_should_flag$ mvn compile | ||
[INFO] Compiling 1 source file to .../examples/maven/error_prone_should_flag/target/classes | ||
.../examples/maven/error_prone_should_flag/src/main/java/Main.java:20: error: [DeadException] Exception created but not thrown | ||
[INFO] Compiling 1 source file to .../examples/maven/target/classes | ||
.../examples/maven/src/main/java/Main.java:20: error: [DeadException] Exception created but not thrown | ||
new Exception(); | ||
^ | ||
(see http://errorprone.info/bugpattern/DeadException) | ||
|
@@ -93,8 +130,9 @@ directory for a working example: | |
``` | ||
|
||
## Gradle | ||
|
||
The gradle plugin is an external contribution. The documentation and code is at | ||
[tbroyer/gradle-errorprone-plugin](https://github.com/tbroyer/gradle-errorprone-plugin). | ||
[tbroyer/gradle-errorprone-plugin](https://github.com/tbroyer/gradle-errorprone-javacplugin-plugin). | ||
|
||
See the | ||
[examples/gradle](https://github.com/google/error-prone/tree/master/examples/gradle) | ||
This comment has been minimized.
Sorry, something went wrong.
This comment has been minimized.
Sorry, something went wrong.
cushon
Author
Collaborator
|
||
|
@@ -115,29 +153,42 @@ FAILURE: Build failed with an exception. | |
|
||
## Ant | ||
|
||
Download the [latest release of Error Prone](https://repo1.maven.org/maven2/com/google/errorprone/error_prone_ant) | ||
from maven, and add the following javac task to your project's `build.xml` file. | ||
Download the following artifacts from maven: | ||
|
||
* [error_prone_core-2.3.1-with-dependencies.jar](https://repo1.maven.org/maven2/com/google/errorprone/error_prone_core/2.3.1/error_prone_core-2.3.1-with-dependencies.jar) | ||
* [jFormatString-3.0.0.jar](https://repo1.maven.org/maven2/com/google/code/findbugs/jFormatString/3.0.0/jFormatString-3.0.0.jar) | ||
* [javac-9+181-r4173-1.jar](https://repo1.maven.org/maven2/com/google/errorprone/javac/9+181-r4173-1/javac-9+181-r4173-1.jar) | ||
|
||
and add the following javac task to your project's `build.xml` file: | ||
|
||
```xml | ||
<javac destdir="build" | ||
compiler="com.google.errorprone.ErrorProneAntCompilerAdapter" | ||
encoding="UTF-8" debug="true" | ||
includeantruntime="false"> | ||
<src path="src"/> | ||
<compilerclasspath> | ||
<pathelement location="./path/to/error_prone_ant.jar"/> | ||
</compilerclasspath> | ||
</javac> | ||
<property name="error_prone_core.jar" location="error_prone_core-2.3.2-SNAPSHOT-with-dependencies.jar"/> | ||
<property name="jformatstring.jar" location="jFormatString-3.0.0.jar"/> | ||
<property name="javac.jar" location="javac-9+181-r4173-1.jar"/> | ||
|
||
<!-- using github.com/google/error-prone-javac is required when running on JDK 8 --> | ||
<condition property="patch.javac" value="-XDempty" else="-J-Xbootclasspath/p:${javac.jar}"> | ||
<javaversion atleast="9"/> | ||
</condition> | ||
|
||
<javac srcdir="src" destdir="build" fork="yes" includeantruntime="no"> | ||
<compilerarg value="${patch.javac}"/> | ||
<compilerarg line="-XDcompilePolicy=simple"/> | ||
<compilerarg line="-processorpath ${error_prone_core.jar}:${jformatstring.jar}"/> | ||
<compilerarg value="-Xplugin:ErrorProne -Xep:DeadException:ERROR" /> | ||
</javac> | ||
``` | ||
|
||
See [examples/ant](https://github.com/google/error-prone/tree/master/examples/ant) for alternate ant configurations. | ||
See | ||
[examples/ant](https://github.com/google/error-prone/tree/master/examples/ant) | ||
for a working example. | ||
|
||
``` | ||
examples/ant/compilerclasspath$ ant | ||
Buildfile: .../examples/ant/compilerclasspath/build.xml | ||
examples/ant$ ant | ||
Buildfile: .../examples/ant/build.xml | ||
compile: | ||
[javac] Compiling 1 source file to .../examples/ant/compilerclasspath/build | ||
[javac] Compiling 1 source file to .../examples/ant/build | ||
[javac] .../examples/ant/compilerclasspath/src/Main.java:20: error: [DeadException] Exception created but not thrown | ||
[javac] new IllegalArgumentException("Missing required argument"); | ||
[javac] ^ | ||
|
@@ -150,24 +201,33 @@ BUILD FAILED | |
|
||
## IntelliJ IDEA | ||
|
||
To add the plugin, start the IDE and find the Plugins dialog. Browse Repositories, choose Category: Build, and find the Error-prone plugin. Right-click and choose "Download and install". The IDE will restart after you've exited these dialogs. | ||
To add the plugin, start the IDE and find the Plugins dialog. Browse | ||
Repositories, choose Category: Build, and find the Error-prone plugin. | ||
Right-click and choose "Download and install". The IDE will restart after you've | ||
exited these dialogs. | ||
|
||
To enable Error Prone, choose `Settings | Compiler | Java Compiler | Use compiler: Javac with error-prone` and also make sure `Settings | Compiler | Use external build` is NOT selected. | ||
To enable Error Prone, choose `Settings | Compiler | Java Compiler | Use | ||
compiler: Javac with error-prone` and also make sure `Settings | Compiler | Use | ||
external build` is NOT selected. | ||
|
||
## Eclipse | ||
|
||
Ideally, you should find out about failed Error Prone checks as you code in eclipse, thanks to the continuous compilation by ECJ (eclipse compiler for Java). But this is an architectural challenge, as Error Prone currently relies heavily on the `com.sun.*` APIs for accessing the AST and symbol table. | ||
Ideally, you should find out about failed Error Prone checks as you code in | ||
eclipse, thanks to the continuous compilation by ECJ (eclipse compiler for | ||
Java). But this is an architectural challenge, as Error Prone currently relies | ||
heavily on the `com.sun.*` APIs for accessing the AST and symbol table. | ||
|
||
For now, Eclipse users should use the Findbugs eclipse plugin instead, as it catches many of the same issues. | ||
For now, Eclipse users should use the Findbugs eclipse plugin instead, as it | ||
catches many of the same issues. | ||
|
||
## Command Line | ||
|
||
### Java 9, 10, and 11 | ||
|
||
Error Prone supports the | ||
[`com.sun.source.util.Plugin`](https://docs.oracle.com/javase/8/docs/jdk/api/javac/tree/com/sun/source/util/Plugin.html) | ||
API, and can be used with JDK 9, 10 and 11 by adding Error Prone to the `-processorpath` | ||
and setting the `-Xplugin` flag. | ||
API, and can be used with JDK 9, 10 and 11 by adding Error Prone to the | ||
`-processorpath` and setting the `-Xplugin` flag. | ||
|
||
Example: | ||
|
||
|
@@ -177,7 +237,7 @@ javac \ | |
-XDcompilePolicy=simple \ | ||
-processorpath $ERROR_PRONE_JAR \ | ||
'-Xplugin:ErrorProne -XepDisableAllChecks -Xep:CollectionIncompatibleType:ERROR' \ | ||
ShortSet.java | ||
ShortSet.java | ||
``` | ||
|
||
``` | ||
|
@@ -204,17 +264,25 @@ class Test { void f() { f(); } } | |
(see http://errorprone.info/bugpattern/InfiniteRecursion) | ||
``` | ||
|
||
|
||
## My build system isn't listed here | ||
|
||
If you're an end-user of the build system, you can [file a bug to request integration](https://github.com/google/error-prone/issues). | ||
If you're an end-user of the build system, you can | ||
[file a bug to request integration](https://github.com/google/error-prone/issues). | ||
|
||
If you develop a build system, you should create an integration for your users! Here are some basics to get you started: | ||
If you develop a build system, you should create an integration for your users! | ||
Here are some basics to get you started: | ||
|
||
Error-prone is implemented as a compiler hook, using an internal mechanism in javac. To install our hook, we override the `main()` method in `com.sun.tools.javac.main.Main`. | ||
Error-prone is implemented as a compiler hook, using an internal mechanism in | ||
javac. To install our hook, we override the `main()` method in | ||
`com.sun.tools.javac.main.Main`. | ||
|
||
Find the spot in your build system where javac's main method is called. This is assuming you call javac in-process, rather than shell'ing out to the javac executable on the machine (which would be pretty lame since it's hard to know where that's located). | ||
Find the spot in your build system where javac's main method is called. This is | ||
assuming you call javac in-process, rather than shell'ing out to the javac | ||
executable on the machine (which would be pretty lame since it's hard to know | ||
where that's located). | ||
|
||
First, add Error Prone's core library to the right classpath. It will need to be visible to the classloader which currently locates the javac Main class. Then replace the call of `javac.main.Main.main()` with the Error Prone compiler: | ||
First, add Error Prone's core library to the right classpath. It will need to be | ||
visible to the classloader which currently locates the javac Main class. Then | ||
replace the call of `javac.main.Main.main()` with the Error Prone compiler: | ||
|
||
`return new ErrorProneCompiler.Builder().build().compile(args) == 0` |
@cushon I believe that the Gradle example pointed to by this link should be updated as well. :)