search

eclipse / microprofile

Repository for important documentation - the index to the project / community
Apache License 2.0
668 stars 115 forks source link

Can't build 7.0 aggregated Javadoc #443

Closed Azquelt closed 1 day ago

Azquelt commented 4 days ago

When I try updating the pom.xml with the RC versions of the MP 7.0 features (to test eclipse/microprofile-telemetry#209) the build output has this error and no javadoc is built:

[INFO] --- javadoc:3.7.0:aggregate-jar (aggregate-javadoc) @ microprofile ---
[ERROR] no reactor project: org.eclipse.microprofile.config:microprofile-config-api:3.1
[ERROR] no reactor project: org.eclipse.microprofile.fault-tolerance:microprofile-fault-tolerance-api:4.1-RC1
[ERROR] no reactor project: org.eclipse.microprofile.health:microprofile-health-api:4.0.1
[ERROR] no reactor project: org.eclipse.microprofile.metrics:microprofile-metrics-api:5.1.0
[ERROR] no reactor project: org.eclipse.microprofile.jwt:microprofile-jwt-auth-api:2.1
[ERROR] no reactor project: org.eclipse.microprofile.openapi:microprofile-openapi-api:4.0-RC3
[ERROR] no reactor project: org.eclipse.microprofile.rest.client:microprofile-rest-client-api:4.0-RC1
[INFO] No previous run data found, generating javadoc.
[ERROR] MavenReportException: Error while generating Javadoc: 
Exit code: 1
/home/andrew/git/microprofile/target/distro-javadoc-sources/microprofile-openapi-api-4.0-RC3-sources/module-info.java:54: error: module not found: osgi.annotation
    requires static osgi.annotation;
                        ^
1 error
Command line was: /home/andrew/dev/java/openj9/jdk-17.0.7+7/bin/javadoc @options @packages @argfile

Refer to the generated Javadoc files in '/home/andrew/git/microprofile/target/apidocs' dir.

org.apache.maven.reporting.MavenReportException: 
Exit code: 1
/home/andrew/git/microprofile/target/distro-javadoc-sources/microprofile-openapi-api-4.0-RC3-sources/module-info.java:54: error: module not found: osgi.annotation
    requires static osgi.annotation;
                        ^
1 error
Command line was: /home/andrew/dev/java/openj9/jdk-17.0.7+7/bin/javadoc @options @packages @argfile

Refer to the generated Javadoc files in '/home/andrew/git/microprofile/target/apidocs' dir.

    at org.apache.maven.plugins.javadoc.AbstractJavadocMojo.doExecuteJavadocCommandLine (AbstractJavadocMojo.java:5197)
    at org.apache.maven.plugins.javadoc.AbstractJavadocMojo.executeJavadocCommandLine (AbstractJavadocMojo.java:5070)
    at org.apache.maven.plugins.javadoc.AbstractJavadocMojo.executeReport (AbstractJavadocMojo.java:2029)
    at org.apache.maven.plugins.javadoc.JavadocJar.doExecute (JavadocJar.java:181)
    at org.apache.maven.plugins.javadoc.AbstractJavadocMojo.execute (AbstractJavadocMojo.java:1825)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:126)
    at org.apache.maven.lifecycle.internal.MojoExecutor.doExecute2 (MojoExecutor.java:328)
    at org.apache.maven.lifecycle.internal.MojoExecutor.doExecute (MojoExecutor.java:316)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:212)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:174)
    at org.apache.maven.lifecycle.internal.MojoExecutor.access$000 (MojoExecutor.java:75)
    at org.apache.maven.lifecycle.internal.MojoExecutor$1.run (MojoExecutor.java:162)
    at org.apache.maven.plugin.DefaultMojosExecutionStrategy.execute (DefaultMojosExecutionStrategy.java:39)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute (MojoExecutor.java:159)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:105)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject (LifecycleModuleBuilder.java:73)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build (SingleThreadedBuilder.java:53)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute (LifecycleStarter.java:118)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:261)
    at org.apache.maven.DefaultMaven.doExecute (DefaultMaven.java:173)
    at org.apache.maven.DefaultMaven.execute (DefaultMaven.java:101)
    at org.apache.maven.cli.MavenCli.execute (MavenCli.java:903)
    at org.apache.maven.cli.MavenCli.doMain (MavenCli.java:280)
    at org.apache.maven.cli.MavenCli.main (MavenCli.java:203)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke0 (Native Method)
    at jdk.internal.reflect.NativeMethodAccessorImpl.invoke (NativeMethodAccessorImpl.java:77)
    at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:568)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced (Launcher.java:255)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch (Launcher.java:201)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode (Launcher.java:361)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:314)
[INFO] Building jar: /home/andrew/git/microprofile/target/microprofile-7.0-SNAPSHOT-javadoc.jar

I note that MicroProfile OpenAPI 4.0 has added a module-info.java but I'm not sure why that project builds ok but we get issues building the aggregated Javadoc.

Azquelt commented 3 days ago

It looks like we are adding the osgi.annotation jar as an extra dependency when building the Javadoc: https://github.com/eclipse/microprofile/blob/730e56d96757c0aa2c9eb14f21f09dba9c7baf6d/pom.xml#L142-L150

I'm not sure why this isn't sufficient - it may be because osgi.annotation isn't an explicit module and doesn't have an Automatic-Module-Name header?

Azquelt commented 2 days ago

For the moment, we can set the javadoc plugin to assume the source code is Java 8:

<configuration>
    <source>8</source>
</configuration>

This then builds non-modular Javadoc including all the packages.

Future work

I think this only works because all of the API source files aren't using classes or features from Java 11, even where the spec is targeting Java 11, so in the longer term I think we'll need a different solution.

Javadoc seems to be unable to generate an aggregated Javadoc for a mix of java modules and non-modules, so I think we either have to make all our specs modular (which could be done with multi-release jars), or manually modify the source of each modular API jar to remove the module-info before it's used to generate the Javadoc.

I did also run into issues where additional dependencies were put on the classpath and not the module path and so were not detected as modules which could be used to satisfy module dependencies. I imagine that at some point we'll want to build aggregated modular Javadoc so this is a problem we'll have to tackle eventually.

I also took a look to see how other projects generate their Javadoc which wasn't very inspiring, Jakarta use a whole bunch of ant to extract each spec's source, make modifications and run javadoc. JUnit 5 uses gradle to aggregate and then fixup the javadoc.