| Summary: | javadoc-target fails when any OPTIONAL dependencies are missing | ||
|---|---|---|---|
| Product: | Ant | Reporter: | Mikhail T. <mi+apache> |
| Component: | Build Process | Assignee: | Ant Notifications List <notifications> |
| Status: | RESOLVED FIXED | ||
| Severity: | regression | CC: | chrischavez |
| Priority: | P4 | ||
| Version: | 1.10.2 | ||
| Target Milestone: | 1.10.8 | ||
| Hardware: | All | ||
| OS: | All | ||
| Attachments: | Build log - with javadocs enabled | ||
I was able to reproduce this. The javadoc tool seems to error out and exit with a non-zero exit code when it cannot resolve a "reference". You can, in fact, find 26 "reference not found" errors which match with the final "26 errors" summary message in that log you attached. These references are mostly of the form @throws JSchException, @see and such. It's understandable why those references aren't found. However, I'm unsure why the javadoc tools errors out in such cases and thus contradicting with what it says on it's documentation page[1] for Java 1.8 (the version you are using): "Reports warnings for bad references... ... Messages may be either warnings or errors, depending on their severity and the likelihood to cause an error if the generated documentation were run through a validator. For example, bad references or missing Javadoc comments do not cause the javadoc command to generate invalid HTML, so these issues are reported as warnings." I've asked for clarification about this on the openjdk javadoc-dev mailing list and will decide how we can proceed with this one, once we get clarity on the matter. [1] https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDCIBFC (In reply to Jaikiran Pai from comment #1) > However, I'm unsure why the javadoc tools errors out in such cases It errors out because of the explicit "failonerror=true" in the <javadoc> element :) The quick-dirty workaround is to simply flip the above setting to false -- as I'm already doing in my update to FreeBSD port devel/apache-ant (see https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=237913) The proper fix, I guess, is to painstakingly exclude the sources dependent on the missing optional dependencies from Javadoc as they are already excluded from compilation... Then the failonerror can be proudly set back to true again... What I meant in my previous reply was that, based on the documentation of the javadoc tool shipped in the JDK (the one which we use in that task), I don't expect that tool to fail with an error in first place for such references and thus the failonerror attribute of that task shouldn't play a role. I agree ultimately this might (and probably will) need a change to our build.xml file to either allow configuring the failonerror value for this target or make some kind of path exclusions or maybe even pass along a -Xdoclint option to that task to use something like "-Xdoclint:all,-reference". But beforing getting to any of that, I personally am interested in understanding why the JDK shipped javadoc tool is failing in first place. (In reply to Jaikiran Pai from comment #3) > But before getting to any of that Let's implement the fixes in parallel with -- rather than after -- figuring out, why JDK is the way it is... This has now been acknowledged[1] as a bug in the JDK's javadoc tool itself and is being tracked in the JDK bug tracker at [2]. [1] https://mail.openjdk.java.net/pipermail/javadoc-dev/2019-May/001068.html [2] https://bugs.openjdk.java.net/browse/JDK-8224266 https://bugs.openjdk.java.net/browse/JDK-8224266 has come to a resolution that this is NOT a bug in javadoc but intended and specified behavior. The issue in ant surfaced in 1.10.2 due to the removal of the `withDoclint` parameter and hence not passing `additionalparam="-Xdoclint:none"` to the javadoc target. Hence a fix is to revert that change and build without doclint by default. See also https://stackoverflow.com/questions/56750209/how-to-successfully-build-ant-source-code/59681717#59681717 Hello Alexander, thank you very much for the detail about the change that caused this regression. I hadn't previously looked at our build.xml history to figure this out. Thanks to your input, I've now undone that change and pushed a commit to master branch upstream and credited you for this fix. This issue also affects ant 1.9.16. Can the fix be backported? See https://github.com/apache/ant/pull/190 merged, thank you. Plese note that we haven't planned any 1.9.x release at the moment, so it may take some time until the fix becomes available. |
Created attachment 36587 [details] Build log - with javadocs enabled Although building the actual JARs works -- skipping the pieces requiring the optional dependencies (like bcel, log4j, xerces, etcætera), the "javadocs" target fails if any of these options aren't available at build-time. The work-around is to change "failonerror" attribute from "true" to "false" -- but the proper fix would exclude the same parts, that the JARs-creation excluded. Attached is the log of my attempts to build Ant from source on a FreeBSD system -- I'd appreciate a patch to build.xml... Thank you!