Support Java 9, 10, and beyond (parent issue)

[msgilligan]

There are 2 phases of implementation for supporting Java 9 and later.

1. Run under Java 9 and later (but build using Java 7/8) -- this was completed and released as AsciiDoclet 1.5.6.

• Fix stylesheet frame issue - Asciidoclet confuses HTML frame formating with Java 9 #72
• Fix stylesheet warning - Fix stylesheet warning with Java 9 #73

2. Build under Java 9/10/11 (presumably using the new Doclet API)

• Port to new Doclet API - Migrate to jdk.javadoc.doclet API for Java 9 and later #71 -- PR Support for Java 11 #96
• Get Asciidoctor/JRuby that is module-safe - Asciidoclet/Asciidoctor/JRuby performs "Illegal reflective access" on Java 9 #80
• Other issues?

Note: We had previously considered an implementation phase of "Run under Java 10 and later (but build using Java 7/8)", but we have decided to directly move to the new Doclet API instead.

[johncarl81]

Yes!

[LightGuard]

At this point, I think it would be good to make a cut. Version 1.5.x should be runnable under JDK 8 and lower. Anything new at this point should be using the new Docklet API and require at least JDK 9.

[msgilligan]

At this point, I think it would be good to make a cut. Version 1.5.x should be runnable under JDK 8 and lower. Anything new at this point should be using the new Docklet API and require at least JDK 9.

A year later this is more obviously true. JDK 11 is out with growing adoptions and compiles back to JDK 7 (back to JDK 6 with a deprecation warning.)

I think the first step is to create a new branch, rebase PR #96 to that branch, and merge it.

We can also either rename this issue to "Create a 2.0 release" or create a new issue and link it to this one.

I have a certain amount of time available, but I'm not sure it's enough to finish this by myself. I'm hoping others will help and I also don't have the ability to make a new release.

It looks like @chrisvest is still willing to help with his PR.

@johncarl81 @mojavelinux @LightGuard Do any of you have time to help with this?

[johncarl81]

I have a little time and would like to be part of the process for sure. I like that the fork has been used for some time. I know that Java 11 compiles back to 7, bit isn't the real issue is the different javadoclet API?

…

On Fri, Jul 10, 2020, 7:08 PM Sean Gilligan ***@***.***> wrote: At this point, I think it would be good to make a cut. Version 1.5.x should be runnable under JDK 8 and lower. Anything new at this point should be using the new Docklet API and require at least JDK 9. A year later this is more obviously true. JDK 11 is out with growing adoptions and compiles back to JDK 7 (back to JDK 6 with a deprecation warning.) I think the first step is to create a new branch, rebase PR #96 <#96> to that branch, and merge it. We can also either rename this issue to "Create a 2.0 release" or create a new issue and link it to this one. I have a certain amount of time available, but I'm not sure it's enough to finish this by myself. I'm hoping others will help and I also don't have the ability to make a new release. It looks like @chrisvest <https://github.com/chrisvest> is still willing to help with his PR. @johncarl81 <https://github.com/johncarl81> @mojavelinux <https://github.com/mojavelinux> @LightGuard <https://github.com/LightGuard> Do any of you have time to help with this? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#76 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABIZKLGQH5U5HU7DRPI7DDR263SBANCNFSM4FCDR2RA> .

[msgilligan]

I know that Java 11 compiles back to 7, bit isn't the real issue is the different javadoclet API?

Right, so, so I'm saying we create AsciiDoclet 2.0 and have it use only the new API and require Java 9, 10, or 11 as a minimum and focus all new development on that version. It will allow people to compile code targeting all thew way back to Java 7 (or 6 with warnings) and with 11 having LTS and decent adoption, I don' think it's entirely unreasonable to require Java 11 as a minimum. Java 9 as a minimum would be ideal, but that might be harder to develop/maintain. I'm not sure if PR #96 will run under JDK 9 or 10. (I'm not going to have the bandwidth to back port PR #96 to earlier JDKs if it doesn't work there already, but I'd prefer a release that works with JDK 9 if someone steps forward that is willing to do whatever work is needed.)

@chrisvest Do you know what is required to make PR #96 run on JDK 9?

[chrisvest]

The PR relies on some utility methods that are not available in Java 9 or 10.

More importantly, #96 is not really a clean port to the new javadoc APIs. It is still relying on extending the standard doclet, which is not supported because it’s hidden by JPMS, and it’s still relying on APIs that are deprecated for removal.

[msgilligan]

The PR relies on some utility methods that are not available in Java 9 or 10.

That sounds relatively easy to fix. Would you agree?

More importantly, #96 is not really a clean port to the new javadoc APIs. It is still relying on extending the standard doclet, which is not supported because it’s hidden by JPMS, and it’s still relying on APIs that are deprecated for removal.

Do you (or anyone else) have any ideas for a longer-term approach that might be a cleaner port to the new API?

[chrisvest]

Do you (or anyone else) have any ideas for a longer-term approach that might be a cleaner port to the new API?

The new API is kind of limited. And there are only bad ways to modify the behaviour of the official standard doclet, which means the "proper" way involves rebuilding all the functionality provided by the standard doclet.

One approach around this, could be to copy or shade the standard doclet from OpenJDK. It's GPL-2.0, so this may require asciidoclet to be relicensed.

[xenoterracide]

well... I was going to raise an issue, this is unfortunate. I guess this is a dead project.

> Task :test-app:javadoc FAILED
Exception in thread "main" java.lang.NoClassDefFoundError: com/sun/javadoc/Doclet
        at java.base/java.lang.ClassLoader.defineClass1(Native Method)
        at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1027)
        at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150)
        at java.base/java.net.URLClassLoader.defineClass(URLClassLoader.java:524)
        at java.base/java.net.URLClassLoader$1.run(URLClassLoader.java:427)
        at java.base/java.net.URLClassLoader$1.run(URLClassLoader.java:421)
        at java.base/java.security.AccessController.doPrivileged(AccessController.java:714)
        at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:420)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:593)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:526)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.loadDocletClass(Start.java:800)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.preprocess(Start.java:771)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:376)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:347)
        at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:57)
        at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:46)

[xenoterracide]

Oh, and openjdk isn't really GPL 2, that's kind of a lie due to the classpath exception. Although if you shade it, I'm not entirely certain. I would speculate (I am not a copyright specialist lawyer) that if you aren't modifying those classes outside of the packagename transformation, then it really shouldn't matter. At worst that would constitute fair use (see google v oracle).

On another hand, you should probably make like the unsafe people and tell them what you need, maybe a new public api could be made available.