tycho
tycho copied to clipboard
eclipse-tycho
Javadoc generation fails when upgrading to Tycho 4.0.3
In 2023-12 we've had to update our project to use Tycho 4.0.3 for another reason (something to do with javax.annotation, if I remember correctly).
After the update, our Javadoc generation goal started to fail, and we found that we need to update the command from 'mvn clean javadoc:aggregate' to 'mvn compile javadoc:aggregate' to get further.
But we still encounter an issue that we cannot explain. It fails for one of our packages (org.eclipse.tracecompass.tmf.remote.core) that has dependencies on org.eclipse.remote.core. This bundle dependency is in our target file, taken from the CDT repository https://download.eclipse.org/tools/cdt/builds/11.4/cdt-11.4.0-rc1a/.
But the Javadoc generation cannot find classes from that bundle, for example: [ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.6.2:aggregate (default-cli) on project org.eclipse.tracecompass: An error has occurred in Javadoc report generation: [ERROR] Exit code: 1 [ERROR] /home/git/org.eclipse.tracecompass/tmf/org.eclipse.tracecompass.tmf.remote.core/src/org/eclipse/tracecompass/tmf/remote/core/proxy/RemoteSystemProxy.java:22: error: package org.eclipse.remote.core does not exist [ERROR] import org.eclipse.remote.core.IRemoteConnection; [ERROR] ^
During Javadoc generation, an options file is created in target/site/apidocs folder, that has a class-path with all our dependencies, but org.eclipse.remote.core is not added there. We don't understand why it's missing or why it's different than every other dependency.
If we revert back with Tycho version set to 2.7.5 as the only change in the pom.xml, then 'mvn compile javadoc:aggregation' starts to work successfully again. We are using maven-javadoc-plugin version 3.6.2.
In our latest code we have excluded our .remote. package from the javadoc goal, in order to have a successful build, but we would like to understand how to fix this error so that we can include it back again.
@cdietrich @PatrickTasse as mentiond in the linked issue
clean javadoc:aggregate-jar test deploy you can't call javadoc before other goal and expect it to "see" dependencies injected in later stage.
@PatrickTasse please make sure to not rely on reexported dependencies, they might cause issues.
About the issue on MWE, it looks like the same error we were getting when we first switched to Tycho 4.0.3, that made us change from 'mvn clean javadoc:aggregate' to 'mvn compile javadoc:aggregate'.
For the order of goals and dependency injection, I believe we have it correctly with 'compile' before 'javadoc:aggregate'?
About relying on reexported dependencies, I'm afraid I don't really understand that subject, I wouldn't know if we do that, and if we do, I wouldn't know how to not do it...
We don't know why this particular bundle is any different than all our other plug-in dependencies.
If we run mvn with debug enabled, we see at some point, a little bit before the failure errors:
[INFO] Configuration changed, re-generating javadoc. [DEBUG] Removed: '<...many entries...>:/home/.m2/repository/p2/osgi/bundle/org.eclipse.remote.core/4.2.0.202211062329/org.eclipse.remote.core-4.2.0.202211062329.jar:<...many more entries...>' [DEBUG] Added: '<...many entries but not org.eclipse.remote.core...>'
The javadoc is quite picky and do strange stuff, also it assumes all your dependencies are static (what is not true anymore with Tycho 3+) so you will need compile before javadoc. you should especially look for forked executions. Also you should check if you really need javadoc aggregate or if not one javadoc per bundle is more appropriate.
If you do not need advanced Tycho 4 features you can also try to enable eager target resolution: https://github.com/eclipse-tycho/tycho/blob/master/RELEASE_NOTES.md#new-delayed-target-platform-resolving
I tried to add requireEagerResolve set to true in the pom.xml, it did not help.
I tried to use 'mvn compile javadoc:javadoc' and it was successful!
The org.eclipse.tracecompass.tmf.remote.core plugin's javadoc is created successfully with javadoc:javadoc but fails with javadoc:aggregate. Does this point to a bug in maven-javadoc-plugin, or Tycho, or could it still be a problem on our side?
With javadoc:javadoc each plugin has its own Javadoc output folder, but there is no common index, is there a way to create one after the fact?