Move module-info back to the main root?

[cpovirk]

Currently, it's under the 9+ section of the mrjar. That's fine, but I wonder if we'd be better off getting modular-style Javadoc output, as we might if we moved it to the root? (Such output might either help or hurt people who are trying to link to us. Maybe it is part of the story with maxcellent/javadoc.io#182, but I haven't tried to understand that....)

[cpovirk]

If the only reason to care is Javadoc, we might also be able to just run Javadoc differently.

My feeling has been that this isn't too important. But if it changes the URLs of our Javadoc output, then we might want to do it sooner rather than later (or decide to never do it, which may or may not be swimming upstream). Or we could insert our own redirects from the old locations to the new at any point.

[cpovirk]

I have discovered an extremely trivial reason to put module-info in the root: It makes --describe-module slightly easier to use (but kudos to it for the helpful error message!):

$ jar --describe-module --file j2objc-annotations-3.0.0.jar
releases: 9

No root module descriptor, specify --release

$ jar --describe-module --file j2objc-annotations-3.0.0.jar --release 9
releases: 9

com.google.j2objc.annotations@3.0.0 jar:file:///tmp/jobjc_release.SF8NzIp/j2objc/annotations/target/j2objc-annotations-3.0.0.jar/!META-INF/versions/9/module-info.class open
exports com.google.j2objc.annotations
requires java.base

Presumably the original command would Just Work if the module-info were in the root.

Anyway, I don't think that should have much effect on a decision here. I'm still not sure if either way is significantly better than the other.

[cpovirk]

I just came across #245 (comment) again, which suggests that the Gradle "release" setting might not fully behavior like javac's --release flag, at least when the APIs differ across versions? We concluded there that we should just make the APIs not differ across versions. So the question now would be whether putting module-info under the Java 9 mrjar root counts as an "API difference" for that purpose. (Or we could still flip the question around and ask why not to put the module-info under the main root. If we're concerned about Javadoc (as discussed above), we can always run Javadoc ourselves when we want to, as discussed in #527 (comment).)

[agentgt]

@cpovirk @kevinb9n Since you guys are talking about module-info and placement another consideration besides META-INF/releases is that module-info has the version of javac used to compile it (at least with maven)! When I say version I mean including patch version.

So if you compile a module-info with javac 17.0.11 the module-info will have 17.0.11 embedded init.

jvm-repo-rebuild/reproducible-central#113

I'm not sure if Gradle has fixed that but I believe it is a problem even with the JDK but has been fixed in 22 and I believe Maven.

To fix it for my case I force the build to use an exact version of javac for reproducibility. The other option is to strip the info of which I'm not sure what tools are out there that do that especially gradle wise.

Anyway sorry if I wasted time if you guys already know this.

[odenix]

My JPMS module uses JSpecify.
I get the following warning every time I build my Javadoc (which links to JSpecify's Javadoc):

warning: The code being documented uses modules but the packages defined in https://jspecify.dev/docs/api/ are in the unnamed module.

[cpovirk]

Interesting, thanks. Are you able to link to the project or share a smaller project that reproduces the warning? Alternatively, have you been able to confirm that moving the module info resolves the warning?

[odenix]

Reproducer:

git clone https://github.com/translatenix/minipack.git
cd minipack
./gradlew javadoc

(In case you wondered, I just open-sourced this project.)

[cpovirk]

Thanks!

I hacked up a local JSpecify build to put module-info in the root, and I pointed minipack at that, but I still see the warning.

I wonder if it could be caused by something about the way that Gradle is running the Javadoc tool. Unfortunately, that's far outside the areas of my expertise :(

[odenix]

Did you change minipack's javadoc task to point to your locally built javadoc?

https://github.com/translatenix/minipack/blob/main/minipack-core/build.gradle.kts#L56

[cpovirk]

Nope, sorry about that! Let me see....