Add documentation about temporary compile outputs #23251
Conversation
| * 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 temporary change the output location while running incremental compilation. This might affect some annotation processors that inspect output locations and which allow users to wire some action to file paths (e.g. `-XepExcludedPaths` in Error Prone). You can disable this Gradle behaviour by setting link:{javadocPath}/org/gradle/api/tasks/compile/CompileOptions.html#getIncrementalAfterFailure--[`options.incrementalAfterFailure`] to `false` on the JavaCompile task. Alternatively you can try specify temporary output path to annotation processor. Output location mapping to temporary output locations is listed in the next table: |
There was a problem hiding this comment.
❌ Can you do one line per sentence?
subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc
Outdated
Show resolved
Hide resolved
| <li><a href="../userguide/dependency_management_for_java_projects.html">Managing Dependencies</a></li> | ||
| <li><a class="nav-dropdown" data-toggle="collapse" href="#jvm-plugins" aria-expanded="false" aria-controls="jvm-plugins">JVM Plugins</a> | ||
| <ul id="jvm-plugins"> | ||
| <li><a href="../userguide/java_plugin.html">Java Plugin</a></li> |
There was a problem hiding this comment.
🤔 I wouldn't include this change in the PR. I wonder if there is a reason not to include the Java plugin in this section. For example, you shouldn't apply the java plugin any more, you should only apply the more specialized plugins (I think).
…_version_7.adoc Co-authored-by: Stefan Wolf <[email protected]>
Co-authored-by: Stefan Wolf <[email protected]>
…emove added link to java plugin
| Additionally, Gradle might temporary change the output location while running incremental compilation. | ||
| This might affect some annotation processors that inspect output locations and which allow users to wire some action to file paths (e.g. `-XepExcludedPaths` in Error Prone). | ||
| You can disable this Gradle behaviour by setting link:{javadocPath}/org/gradle/api/tasks/compile/CompileOptions.html#getIncrementalAfterFailure--[`options.incrementalAfterFailure`] to `false` on the JavaCompile task. | ||
| Alternatively, you can try to specify a temporary output path to the annotation processor. |
There was a problem hiding this comment.
I'm not sure I understand this sentence properly. Is there some mechanism for users to configure what the temporary output path is? Or is this a more general comment for annotation processors which themselves can be configured with custom file paths?
There was a problem hiding this comment.
Thanks for the review, I believe this might not be clear to a lot of users.
Users can't change that temporary output, but they can make annotation aware of it.
So basically what I want to say here is:
The user has two options:
1.) They can just disable incremental after failure, done.
2.) Or if they want to keep incremental after failure working they can try to pass a temporary output value to the annotation processor as a parameter, so the annotation processor is aware of that path. In case of Error Prone they can pass a value to -XepExcludedPaths. Example:
Before they had: -XepExcludedPaths=.*/build/generated/.*". With the new behavior they might need to do
-XepExcludedPaths=.*/(build/generated|compileJava/compileTransaction/annotation-output)/.*".
Do you have any suggestions on how I can rephrase the paragraph to be more clear?
Somehow related note: I hope we remove these temporary paths in 8.1 with #23226.🤞
There was a problem hiding this comment.
Perhaps:
This might affect some annotation processors that inspect output locations or
accept file paths as arguments. For example, Error Prone's `-XepExcludedPaths`
parameter can be updated to `.*/(build/generated|compileJava/compileTransaction/annotation-output)/.*`
in order to make the processor aware of the new temporary directory.
subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc
Outdated
Show resolved
Hide resolved
Co-authored-by: Justin Van Dort <[email protected]>
…er outputs Co-authored-by: Amanda L Martin <[email protected]>
9ca3b84 to
26d0048
Compare
Co-authored-by: Justin Van Dort <[email protected]>
|
@bot-gradle test BD |
|
I've triggered the following builds for you: |
|
@bot-gradle test and merge |
|
Your PR is queued. See the queue page for details. |
|
I've triggered a build for you. |
This removes text added in #23251, since we changed the behaviour of Java and Groovy compilation in #23226. Co-authored-by: Anže Sodja <[email protected]>
…modules" to 7.6.1 Backport from #23119 to 7.6.1. Also backport from #23251 to 7.6.1 Fixes #23224 Co-authored-by: Anže Sodja <[email protected]>
Documentation for #23066.
We might add improvements that remove the behaviour in 8.1.