Add documentation about temporary compile outputs

asodja · asodja · commit 51db26085d1e · 2023-02-16T15:34:30.000+01:00
Backport from #23251 to 7.6.1
diff --git a/subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc b/subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc
@@ -509,6 +509,26 @@ To help you understand how incremental compilation works, the following provides
 * Having a source structure that does not match the package names, while legal for compilation, might end up causing trouble in the toolchain.
     Even more if annotation processing and <<build_cache.adoc#build_cache,caching>> are involved.
 
+Additionally, Gradle might temporarily change the output location while running incremental compilation.
+This might affect some annotation processors that inspect output locations or accept file paths as arguments (e.g., `-XepExcludedPaths` in Error Prone).
+There are two options:
+
+ - Disable `incremental after failure` by setting link:{javadocPath}/org/gradle/api/tasks/compile/CompileOptions.html#getIncrementalAfterFailure--[`options.incrementalAfterFailure`] to `false` on the JavaCompile task.
+-  Keep `incremental after failure` enabled by instead passing a temporary output value to the annotation processor as a parameter so that the annotation processor is aware of the temporary path. 
+
+In the case of Error Prone, `-XepExcludedPaths` must be set. Given an existing value of `-XepExcludedPaths=.\*/build/generated/.*`, the updated value would be
+`-XepExcludedPaths=.\*/(build/generated|compileJava/compileTransaction/annotation-output)/.*`.
+
+The following table shows the mapping from default output location to temporary output location:
+
+.Compiler output to temporary output location
+|===
+| JavaCompile location property | Default output location | Temporary output location
+| `destinationDirectory` | `build/classes/java/main` | `build/tmp/<task-name>/compileTransaction/compile-output`
+| `options.generatedSourceOutputDirectory` | `build/generated/sources/annotationProcessor/java/main` | `build/tmp/<task-name>/compileTransaction/annotation-output`
+| `options.headerOutputDirectory` | `build/generated/sources/headers/java/main` | `build/tmp/<task-name>/compileTransaction/header-output`
+|===
+
 [[sec:incremental_annotation_processing]]
 == Incremental annotation processing
 
diff --git a/subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc b/subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc
@@ -173,6 +173,13 @@ Use `implementation.bundle(libs.bundles.testing)` instead.
 
 For more information, see the updated <<jvm_test_suite_plugin.adoc#sec:declare_an_additional_test_suite, declare an additional test suite>> example in the JVM Test Suite Plugin section of the user guide and the link:{groovyDslPath}/org.gradle.api.artifacts.dsl.DependencyAdder.html[`DependencyAdder`] page in the DSL reference.
 
+==== Incremental compilation temporarily changes the output location
+
+Incremental Java and Groovy compilation may now change the compiler output location.
+This might affect some annotation processors that allow users to wire some action to file paths (e.g. `-XepExcludedPaths` in Error Prone).
+This behaviour can be disabled by setting `options.incrementalAfterFailure` to `false`.
+Please refer to the <<java_plugin#sec:incremental_compilation_known_issues, userguide section about known incremental compilation issues>> for more details.
+
 === Deprecations
 
 [[invalid_toolchain_specification_deprecation]]
