Generating and Attaching of Scaladocs are broken with Scala3 #604
Comments
|
I have updated the test project to use the currently promoted version 4.6.2 within the build profile scala3-failure. Your latest commits have been integrated into the fork of your plugin. The branches scaladoc3 and classloader-issue are producing the version 4.6.3-EXPERIMENTAL now. Again, these version is referenced by the other build profiles of the reproducer. |
|
@chr78rm Thanks for reporting.
I'll only be able to review if you can provide a PR that fixes the above points (all the more as I personally use neither Scala 3 nor Scaladoc). |
|
Thank you for your answer. I didn't want to put too much effort into this beforehand. Please don't read too much into some of the commits on the branches. I needed to research your code and hence I had included some tracing statements at some time. After I understood the inner workings of the plugin well enough I had removed them again. Besides, I had updated the master branch of the forked repo to your latest commit (eac2c9b). After that, I integrated your latest commits including the fix for issue #600 into the scaladoc3 branch by working on the output of I have attached a file with the full diffs to this comment but you might want to use an IDE for a better visual experience. Additionally, I will replay the relevant diffs into a new branch rooted at your latest commit. I haven't looked into how you are organizing your integration tests yet. I'm using the mentioned test project as reference at this stage. E.g. the test project contains a build profile scala2 which can be used to verify that everything works in Scala2 as before. Another build profile works with Scala3. Of course I can provide a pull request for this in due course. |
|
Is there a way to disable arguments that are used to execute the scaladoc? Under the hood the Scala-maven-plugin scaladoc execution is running a command like: The problem I seem to hit is that the temp file (e.g. -doc-format:html
-doc-title
"scommons 0.0.4_3 API"These flags are are no longer appropriate for scaladoc 3 and when included produce the following: When I manually edit those out of the args file and rerun the command above, it works fine. So being able to strip those out of the args file might resolve this issue. |
|
Code that produces the bad flag is here |
|
The flags are old and deprecated but they shouldn't break anything according to scala/scala3#11907. The problem seems to be the newline that gets generated between -doc-title and the module name itself. If the offending lines in the file become as follows, we get warnings but it doesn't fail anymore: This would seem like a reasonably quick workaround to do. |
|
Hi all, just hit this in 4.9.1. Is there any user-level workarounds? edit: from what I've found so far, it seems in Scala 3 the plugin should be using a different class edit2: getting a little further with: configuration:
scaladocClassName: dotty.tools.scaladoc.Main
dependencies:
- groupId: org.scala-lang
artifactId: scaladoc_3
version: 3.3.3forgive the yaml syntax (trying out polyglot) I get the following with edit3: adding edit4: working configuration for scala 3.3.3 - id: attach-javadocs
goals: ['doc-jar'] # on package
configuration:
args: ['-nobootcp'] # avoid NPE from getClass.getClassLoader
scaladocClassName: dotty.tools.scaladoc.Main # scala3 class
sourceDir: '${project.build.outputDirectory}' # use compiled classes
includes: ['**/*.tasty'] # only tasty
dependencies:
- groupId: org.scala-lang
artifactId: scaladoc_3
version: 3.3.3 |
|
I can confirm that the configuration above does the trick for now. But it seems unreliable at best because it depends on an unsupported option (-nobootcp). Indeed I am getting the output: "bad option '-nobootcp' was ignored", but it wasn't actually ignored since removing the option causes the ClassLoader bug again. The Compiler Options Lookup Table notes this option as not yet available in Scala 3.3.x and you cannot find this option within the ScalaDoc Settings at all. The same applies when listing the available options via I had submitted a pull request (#611) two years ago which would have fixed this issue but the maintainers had chosen to ignore it. The ScalaDoc generation additionally suffers from this bug at present: Scaladoc generates broken local links. |
@chr78rm This is both not correct and offending. Please understand that I have some professional interest in maven + Scala 2 but have none for maven + Scala 3 and never will. |
|
Please, calm down @slandelle . I have simply stated the fact that you chose to ignore the pull request, speak: to not integrate it - for whatever reasonable or unreasonable grounds you might have had. I really don't know how this comes as offending. Bye, Bye. |
|
I haven't chosen to ignore it. I've requested you to perform some changes before I could review it, which you haven't. |
|
I'm having the very same problem as we speak. I can't release my open-source project (rest-assured) because of this :( Will try the workarounds by @jam01 . |
|
@johanhaleby IMHO, if you want to provide modules for Scala 3, you should build and release them with sbt. |
|
@slandelle Yeah that might be so, but it would complicate my build process even further and I've not used sbt in 10+ years so I'm very rusty. I have other scala modules as well that use Scala 2, and I can generate javadoc there without any issues. |
|
It compiles and builds just fine btw, it's just javadoc generation that I struggle with. And I can't publish to maven central because of that. |
|
Thank you for your work @slandelle . I gave sbt a try and wow ... Literally every project I've seen is configured differently. Basically my decision with my project was, if Maven can do it I'll use Maven, if not I'll figure out sbt. Thankfully I was able to figure it out through this project. Additionally, the upcoming Maven 4 features should really leave little to be missed between Maven and other build tools (other than the official support from the Scala team). Right now the only thing I'm missing is the ability to test Scala.js code in a JS environment (which sbt supports). But I can live with that. (Also someone figured it out in Gradle so I might venture a PR at some point if I really needed it). |
|
To reproduce my problems:
It'll end this error: |
|
I've also tried porting @jam01's workaround to maven like this: <groupId>net.alchim31.maven</groupId>
<artifactId>scala-maven-plugin</artifactId>
<version>4.9.2</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>doc-jar</goal>
</goals>
<configuration>
<scaladocClassName>dotty.tools.scaladoc.Main</scaladocClassName>
<sourceDir>${project.build.outputDirectory}</sourceDir>
<args>-nobootcp</args>
<includes>
<include>**/*.scala</include>
</includes>
<additionalDependencies>
<dependency>
<groupId>org.scala-lang</groupId>
<artifactId>scaladoc_3</artifactId>
<version>3.4.2</version>
</dependency>
</additionalDependencies>
</configuration>
</execution>
</executions>But now it fails with: |
|
Let me say things bluntly (my opinion only). This project is currently understaffed and the current's staff interests don't align with yours. We are currently 2 persons:
I will never ever have an interest in using this plugin for scaladoc, Scala 3, Scala.js, Scala native or Spark. This code is open-source, if you don't want this plugin to die, I see 2 solutions:
|
|
That's fair, this is the nature of open source. I appreciate your disclaimer. Scala 3, Scala.js (minus tests in JS) and scaladoc (with my overriding config) are already supported out of the box. The only reason I didn't submit a PR is because I found my config to be pretty simple to merit the PR work for me at this point (again the nature of open source). Perhaps you'd consider closing this issue since there's a workaround. |
|
@johanhaleby I tried to give your project a shot, but based on an error I got at compilation I think it requires Java 8 which I don't have locally. That |
|
@slandelle I'm the first one to respect this, I know how difficult it can be to maintain an open-source project ❤️ |
|
@jam01 Yeah it's still using Java 8. But the code in the module is a |
|
@johanhaleby oh I think your issue is you're using the wrong "dependencies" element, it shoud be Yes, you should still use tasty. |
|
@jam01 Nice find, thank you! I changed to this: <execution>
<id>attach-javadocs</id>
<goals>
<goal>doc-jar</goal>
</goals>
<configuration>
<scaladocClassName>dotty.tools.scaladoc.Main</scaladocClassName>
<sourceDir>${project.build.outputDirectory}</sourceDir>
<args>-nobootcp</args>
<includes>
<include>**/*.tasty</include>
</includes>
<dependencies>
<dependency>
<groupId>org.scala-lang</groupId>
<artifactId>scaladoc_3</artifactId>
<version>3.4.2</version>
</dependency>
</dependencies>
</configuration>
</execution>but now it fails with: 😢 |
|
My bad! I had a different version of scaladoc_3 than the scala compiler. Now it freaking works!!! Thanks A LOT!!! You definitely made my day. |
|
Hello @jam01 can you please elaborate further on Scala.js support out of the box?
If scala-maven-plugin can compile and package Scala.js can you provide / point to a sample POM file or any useful reference? |
|
See if this helps https://github.com/jam01/json-schema/blob/0.1.0/js/pom.yaml Also, consider opening a new issue as to not pollute this one that's about docs. |
The production of Scaladoc APIs are broken when using Scala3, e.g. with Scala 3.1.2:
This gives
The issue can be reproduced with the build profile scala3-failure of the test project. The test project can be cloned by
The mentioned profile uses the currently promoted version (4.6.1) of the plugin and tries to attach scaladocs as depicted on the project site. I have investigated this a bit further. One reason why this cannot work is the wrong qualified class name given by the the method apidocMainClassName(). The correct qualified class name would be dotty.tools.scaladoc.Main. Using Scala3 this class is even separated from the scala compiler, that is an additional dependency (scaladoc_3) is needed to resolve this class. Unfortunately a potential fix in accordance with the outline of the given program structure of the plugin runs into classloader issues. scaladoc_3 uses the java.lang.ClassLoader.getResourceAsStream(String) method but it seems that the invocations prepared by e.g. JavaMainCallerByFork don't provide a class loader when calling getClassLoader(). I am not an expert in classloader issues but it might well be that this issue is inevitable when using the currently provided invocations within the scala_maven_executions package.
Nevertheless, I have prepared a possible fix within the forked repo
of your plugin. Checkout the branch scaladoc3. The prepared fix uses the ProcessBuilder of the JDK to invoke a forked process and reflects as far as possible the given outline of the plugin code structure. The mentioned classloader issue can be triggered by checking out the branch classloader-issue. Both mentioned branches of the fork produce an artifact of the plugin with version 4.6.2-EXPERIMENTAL. This version is used by the other build profiles of the test project.
The text was updated successfully, but these errors were encountered: