Add documentation about temporary compile outputs #23251

asodja · 2022-12-21T13:43:46Z

Documentation for #23066.

We might add improvements that remove the behaviour in 8.1.

wolfs · 2022-12-21T14:16:12Z

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc

@@ -515,6 +515,16 @@ 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 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:


❌ Can you do one line per sentence?

Should be fixed now

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc

subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc

wolfs · 2022-12-21T14:24:15Z

subprojects/docs/src/main/resources/header.html

@@ -225,6 +225,7 @@ <h3 id="authoring-gradle-builds-java">Authoring JVM Builds</h3>
            <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>


🤔 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 <wolf@gradle.com>

Co-authored-by: Stefan Wolf <wolf@gradle.com>

…emove added link to java plugin

wolfs

LGTM!

jvandort

Some suggestions and a question

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc

jvandort · 2022-12-21T17:33:15Z

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc

+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.


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?

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.🤞

let me whack it.

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

Co-authored-by: Justin Van Dort <jvandort@gradle.com>

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc

…er outputs Co-authored-by: Amanda L Martin <hythloda@gmail.com>

asodja · 2022-12-22T17:30:09Z

@jvandort @hythloda is this now good for a merge?

jvandort

Added some suggestions to avoid you and they.

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc

Co-authored-by: Justin Van Dort <jvandort@gradle.com>

asodja · 2022-12-23T09:37:41Z

@bot-gradle test BD

bot-gradle · 2022-12-23T09:37:45Z

I've triggered the following builds for you:

BuildDistributions build

wolfs · 2022-12-23T14:56:12Z

@bot-gradle test and merge

bot-gradle · 2022-12-23T14:56:20Z

Your PR is queued. See the queue page for details.

bot-gradle · 2022-12-23T15:54:33Z

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 <asodja@gradle.com>

Backport from #23251 to 7.6.1

…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 <asodja@gradle.com>

Add documentation about temporary compile outputs

eb2f6bd

asodja requested review from a team and hythloda as code owners December 21, 2022 13:43

asodja requested a review from jvandort December 21, 2022 13:43

bot-gradle added this to the 8.1 RC1 milestone Dec 21, 2022

asodja self-assigned this Dec 21, 2022

asodja changed the base branch from master to release December 21, 2022 13:43

asodja added @execution a:documentation Documentation content labels Dec 21, 2022

asodja modified the milestones: 8.1 RC1, 8.0 RC1 Dec 21, 2022

asodja linked an issue Dec 21, 2022 that may be closed by this pull request

Easier debugging of CompileTransaction path selection in incremental task execution #23066

Closed

Also add a problem to potential breaking changes

9c9f553

wolfs reviewed Dec 21, 2022

View reviewed changes

asodja and others added 3 commits December 21, 2022 15:32

Apply suggestions from code review for java_plugin.adoc and upgrading…

16a7b0b

…_version_7.adoc Co-authored-by: Stefan Wolf <wolf@gradle.com>

Apply additional suggestions to java_plugin.adoc

ba2684f

Co-authored-by: Stefan Wolf <wolf@gradle.com>

Use one line per sentence in java_plugin.adoc for new content, also r…

a76d4ef

…emove added link to java plugin

gradle deleted a comment from asodja Dec 21, 2022

wolfs approved these changes Dec 21, 2022

View reviewed changes

gradle deleted a comment from asodja Dec 21, 2022

jvandort reviewed Dec 21, 2022

View reviewed changes

Apply additional changes to docs for temporary compile outputs

bef48e5

Co-authored-by: Justin Van Dort <jvandort@gradle.com>

hythloda reviewed Dec 22, 2022

View reviewed changes

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc Outdated Show resolved Hide resolved

gradle deleted a comment from asodja Dec 22, 2022

Apply additional suggestions to java_plugin.adoc for temporary compil…

26d0048

…er outputs Co-authored-by: Amanda L Martin <hythloda@gmail.com>

asodja force-pushed the asodja/document-compile-outs branch from 9ca3b84 to 26d0048 Compare December 22, 2022 17:18

jvandort reviewed Dec 23, 2022

View reviewed changes

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc Outdated Show resolved Hide resolved

subprojects/docs/src/docs/userguide/jvm/java_plugin.adoc Outdated Show resolved Hide resolved

Apply suggestions from code review to java_plugin.adoc

512b881

Co-authored-by: Justin Van Dort <jvandort@gradle.com>

gradle deleted a comment from asodja Dec 23, 2022

asodja requested a review from jvandort December 23, 2022 14:36

hythloda self-requested a review December 23, 2022 14:41

hythloda approved these changes Dec 23, 2022

View reviewed changes

gradle deleted a comment from asodja Dec 23, 2022

bot-gradle merged commit 4dfa1b0 into release Dec 23, 2022

bot-gradle deleted the asodja/document-compile-outs branch December 23, 2022 16:26

asodja mentioned this pull request Dec 24, 2022

Easier debugging of CompileTransaction path selection in incremental task execution #23066

Closed

asodja mentioned this pull request Jan 26, 2023

Remove mentioning temporary compile outputs #23661

Merged

asodja mentioned this pull request Feb 15, 2023

Backport "Fix incremental compilation with modules" to 7.6.1 #23913

Merged

asodja added a commit that referenced this pull request Feb 16, 2023

Add documentation about temporary compile outputs

51db260

Backport from #23251 to 7.6.1

lptr mentioned this pull request Feb 20, 2023

Backport "Use Compiler API data for incremental compilation after a failure" to 7.x #23922

Closed

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation about temporary compile outputs #23251

Add documentation about temporary compile outputs #23251

asodja commented Dec 21, 2022 •

edited

Loading

wolfs Dec 21, 2022

asodja Dec 21, 2022

wolfs Dec 21, 2022 •

edited

Loading

asodja Dec 21, 2022

wolfs left a comment

jvandort left a comment

jvandort Dec 21, 2022

asodja Dec 22, 2022 •

edited

Loading

hythloda Dec 22, 2022 •

edited

Loading

jvandort Dec 22, 2022

asodja commented Dec 22, 2022 •

edited

Loading

jvandort left a comment

asodja commented Dec 23, 2022

bot-gradle commented Dec 23, 2022

wolfs commented Dec 23, 2022

bot-gradle commented Dec 23, 2022

bot-gradle commented Dec 23, 2022

Add documentation about temporary compile outputs #23251

Add documentation about temporary compile outputs #23251

Conversation

asodja commented Dec 21, 2022 • edited Loading

wolfs Dec 21, 2022

Choose a reason for hiding this comment

asodja Dec 21, 2022

Choose a reason for hiding this comment

wolfs Dec 21, 2022 • edited Loading

Choose a reason for hiding this comment

asodja Dec 21, 2022

Choose a reason for hiding this comment

wolfs left a comment

Choose a reason for hiding this comment

jvandort left a comment

Choose a reason for hiding this comment

jvandort Dec 21, 2022

Choose a reason for hiding this comment

asodja Dec 22, 2022 • edited Loading

Choose a reason for hiding this comment

hythloda Dec 22, 2022 • edited Loading

Choose a reason for hiding this comment

jvandort Dec 22, 2022

Choose a reason for hiding this comment

asodja commented Dec 22, 2022 • edited Loading

jvandort left a comment

Choose a reason for hiding this comment

asodja commented Dec 23, 2022

bot-gradle commented Dec 23, 2022

wolfs commented Dec 23, 2022

bot-gradle commented Dec 23, 2022

bot-gradle commented Dec 23, 2022

asodja commented Dec 21, 2022 •

edited

Loading

wolfs Dec 21, 2022 •

edited

Loading

asodja Dec 22, 2022 •

edited

Loading

hythloda Dec 22, 2022 •

edited

Loading

asodja commented Dec 22, 2022 •

edited

Loading