[BUILD-238] Cannot build main (5.3) on Java 6 Created: 07/Jul/16  Updated: 10/Nov/17  Resolved: 19/May/17

Status: Closed
Project: Build
Component/s: Poms
Affects Version/s: POMs 31
Fix Version/s: POMs 34

Type: Bug Priority: Neutral
Reporter: Mikaël Geljić Assignee: Mikaël Geljić
Resolution: Fixed Votes: 0
Labels: javadoc, maven, pom
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

OS X


Issue Links:
causality
caused by BUILD-200 Introduce asciidoc for Javadoc Closed
Template:
Acceptance criteria:
Empty
Sprint: Saigon 95, Saigon 96
Story Points: 2

 Description   

Since POMs 31 & BUILD-200, any module specifying a custom doclet will fail to build on Java 6, on OS X.

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.3:javadoc (default-cli) on project custom-doclet-module-jdk6: An error has occurred in JavaDocs report generation: Unable to resolve artifact:groupId = 'org.asciidoctor'
[ERROR] artifactId = 'asciidoclet'
[ERROR] version = '1.5.2': Missing:
[ERROR] ----------
[ERROR] 1) com.sun.tools:tools:jar:1.6.0_65

Multiple factors combined, trying to summarize:

  1. parent POMs 31 configure the asciidoclet docletArtifact (singular)—this is only used by the javadoc plugin when the doclet is not empty. Empty means "use the standard doclet".
  2. Magnolia Templating JSP specifies a custom doclet (non-empty) for TLD doc generation. This one however configures multiple artifacts, using docletArtifacts (plural)—thus not overriding the asciidoclet single docletArtifact. As a result, any module not overriding the singular docletArtifact will fetch the asciidoclet artifacts (even if it doesn't intend to use it).
  3. asciidoclet has a dependency to the com.sun tools jar (with a systemPath relative to java.home). Some say this is unnecessary with Maven anyways.
  4. Works everywhere except on Apple JDK 6, where the tools jar is concatenated into the classes jar (as hinted from the spring guys here)

Soooo, all in all we have made zero move towards Asciidoclet in the past months, and I would personally favor the Markdown-based alternative (Pegdown Doclet).

A. Either we find a profile/property configuration to selectively request the asciidoclet artifact for a module which wants to use it (and we can do the similar thing for pegdown).
B. Or we acknowledge it's too early to generalize this config on parent pom level, and leave it down to modules to configure the javadoc plugin. We may still integrate back to parent POMs if adoption comes.



 Comments   
Comment by Mikaël Geljić [ 07/Jul/16 ]

Sooo, same chicken & egg hurdles Greg was facing with profiles & properties: Profiles conditions are evaluated before POM properties (unlike plugin configurations), so option A. is out.

Option C. use the plural form <docletArtifacts> in super pom for asciidoc config; thus letting Templating JSP override it.
(alternatively, it might be possible to workaround it on poms 31 by emptying the singular one).

Still, on the B-side, I would definitely not mass-apply a new doclet to old branches, so that would rule out doing it in the parent POMs (in their current shape).
That plus the fact that I'm less and less convinced by Asciidoc (rendering quirks, impossible warning-less @see tags for web links...)

BTW did I mention Pegdown-doclet was a pre-processor still delegating to the standard doclet? Yes, it means we wouldn't need mass-conversion of standard HTML javadoc throughout a whole module/repo

Comment by Mikaël Geljić [ 05/May/17 ]

After so long... I had the change locally for a while, and forgot that I had even filed this, so why not... targeting poms 34 though.

Generated at Sun Feb 11 23:40:04 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.