matrei opened a new issue, #36:
URL: https://github.com/apache/grails-gradle-publish/issues/36
Follow-on to #23. Since the plugin disables `javadoc` and packages the
groovydoc in its place, the javadoc jar no longer carries a *fresh* javadoc
overlay — but it still carries whatever an earlier build left in
`build/docs/javadoc/`, and when that directory exists the jar fails outright on
any consumer that uses `DuplicatesStrategy.FAIL`.
## What happens
`GrailsPublishGradlePlugin` (main,
`plugin/src/main/groovy/org/apache/grails/gradle/publish/GrailsPublishGradlePlugin.groovy`,
around lines 650–686) does three things for a project that has a `groovydoc`
task:
1. `withJavadocJar()` — Gradle registers `javadocJar` with `from(javadoc)`
2. `tasks.named('javadoc') { it.enabled = false }`
3. `tasks.named('javadocJar') {
jar.from(project.files(groovydoc.destinationDir)) }`
Step 2 stops the task from running, but `from(javadoc)` from step 1 stays on
the jar, and a disabled task never cleans its outputs. So the jar's sources are
still *both* directories; on a clean tree `build/docs/javadoc/` is empty and it
goes unnoticed, but as soon as that directory has content the stale javadoc is
packaged next to the groovydoc.
Content gets there easily: any build of the same checkout from before the
plugin was applied to the module (or from a branch where it is not), since a
plain `withJavadocJar()` runs `javadoc` into that exact directory. Switching
branches in a monorepo is enough. CI never sees it because it always starts
clean, so it only bites developers, and the failure points nowhere near the
cause.
## Reproduction
```
plugins {
id 'groovy'
id 'org.apache.grails.gradle.grails-publish' // 1.0.0-M2
}
tasks.named('javadocJar') { duplicatesStrategy = DuplicatesStrategy.FAIL }
```
```
mkdir -p build/docs/javadoc && echo stale > build/docs/javadoc/help-doc.html
./gradlew javadocJar
```
```
> Cannot copy file '.../build/docs/groovydoc/help-doc.html' to
'help-doc.html'
because file '.../build/docs/javadoc/help-doc.html' has already been
copied there.
```
With the default `DuplicatesStrategy` the jar builds, but it silently ships
the stale `help-doc.html` and any other stale javadoc page (the `help-doc.html`
clash is only the visible symptom; a stale `p/A.html` for a class that no
longer exists goes in without a word).
In apache/grails-core this is `./gradlew build` failing on
`:grails-gsp-spring-boot:javadocJar` for anyone who built that directory on
7.0.x before, since `grails-core` sets `DuplicatesStrategy.FAIL` on every jar —
see apache/grails-core#16371, which works around it in the framework's own
convention plugin.
## Suggested fix
A `javadoc` task that does not run has nothing to contribute, so keep its
destination directory out of the jar whenever it is disabled. The
`from(javadoc)` cannot be removed, but it can be excluded (this is the
workaround in apache/grails-core#16371, written to read both values lazily
because the task is disabled after the jar is configured):
```groovy
tasks.named('javadocJar', Jar).configure { Jar jar ->
Provider<Boolean> javadocRuns = project.provider {
javadocTask.get().enabled }
Provider<File> javadocDir = project.provider {
javadocTask.get().destinationDir }
jar.exclude { FileTreeElement element ->
!javadocRuns.get() && javadocDir.orNull != null &&
element.file.absoluteFile.toPath().startsWith(javadocDir.get().absoluteFile.toPath())
}
}
```
Doing it in the plugin lets `grails-core` drop its copy and covers every
other consumer, none of which will spot this until a stale directory turns up.
Also worth resolving #23 in the same change, since after this the jar is
groovydoc-only in practice as well as in intent.
Versions: grails-publish 1.0.0-M2 (same code on `main`), Gradle 9.7.1,
Groovy 5.1.3.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
