Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.maint.java > #9966 > unrolled thread

javadocs links with maven-debian-helper

Back to article view | Back to linux.debian.maint.java

Contents

  javadocs links with maven-debian-helper Carnë Draug <carandraug+dev@gmail.com> - 2017-08-31 18:10 +0200
    Re: javadocs links with maven-debian-helper Markus Koschany <apo@debian.org> - 2017-08-31 18:20 +0200
    Re: javadocs links with maven-debian-helper Emmanuel Bourg <ebourg@apache.org> - 2017-08-31 18:50 +0200
      Re: javadocs links with maven-debian-helper Carnë Draug <carandraug+dev@gmail.com> - 2017-08-31 19:00 +0200
        Re: javadocs links with maven-debian-helper Carnë Draug <carandraug+dev@gmail.com> - 2017-09-01 19:50 +0200
          Re: javadocs links with maven-debian-helper Carnë Draug <carandraug+dev@gmail.com> - 2017-09-08 17:10 +0200

#9966 — javadocs links with maven-debian-helper

Hi

I am packaging some java libraries with maven-debian-helper but having
problems setting the javadocs links properly.  I have done this for
ant based projects but I can't figure out how to do it for maven
projects.

I took a look on a few other *-java-doc packages that are maven only
projects (libjgoodies-looks-java-doc, libakuma-java, and
libmetadata-extractor-java-doc) hoping to find the answer.  However,
they all are linking do docs.oracle.com too instead of the local
javadocs.  libmetadata-extractor-java-doc on Stretch had the correct
javadoc links, back when upstream made use of ant and not maven.

I have  tried to set user  property links [1] in  the maven.properties
file as described in the javadoc plugin documentation but no avail.

How do I set the path for the javadocs of other java libraries when
using maven-debian-helper?

Thank you
Carnë

[toc] | [next] | [standalone]

#9967

[Multipart message — attachments visible in raw view] — view raw

Am 31.08.2017 um 18:03 schrieb Carnë Draug:
[...]
> How do I set the path for the javadocs of other java libraries when
> using maven-debian-helper?

I believe maven-debian-helper requires that you build-depend on related
-doc packages and in one of the final steps it tries to resolve those
cross-references.

But without them you will end up with something like that for
libmetadata-extractor-java-doc.

Analysing pom.xml...
Checking dependencies for documentation packages...
> dpkg --search /usr/share/doc/libxmpcore-java/api/index.html
dpkg failed to execute successfully
Offline mode. Give up looking for package containing
/usr/share/doc/libxmpcore-java/api/index.html

This step often takes too long and I have recently filed [1] because of it.

[1] https://bugs.debian.org/871669

[toc] | [prev] | [next] | [standalone]

#9968

Le 31/08/2017 à 18:03, Carnë Draug a écrit :

> How do I set the path for the javadocs of other java libraries when
> using maven-debian-helper?

Good question, I'm not even sure this is supported, which is interesting
because the *-java-doc package resolution occurring at the end of the
build takes a lot of time for basically no benefit since the
documentation isn't linked :D

My advice: Life is short, forget the javadoc ;)

Emmanuel Bourg

[toc] | [prev] | [next] | [standalone]

#9969

On 31 August 2017 at 17:15, Markus Koschany <apo@debian.org> wrote:
> Am 31.08.2017 um 18:03 schrieb Carnë Draug:
> [...]
>> How do I set the path for the javadocs of other java libraries when
>> using maven-debian-helper?
>
> I believe maven-debian-helper requires that you build-depend on related
> -doc packages and in one of the final steps it tries to resolve those
> cross-references.
>
> But without them you will end up with something like that for
> libmetadata-extractor-java-doc.
>
> Analysing pom.xml...
> Checking dependencies for documentation packages...
>> dpkg --search /usr/share/doc/libxmpcore-java/api/index.html
> dpkg failed to execute successfully
> Offline mode. Give up looking for package containing
> /usr/share/doc/libxmpcore-java/api/index.html
>

I do have all the docs dependencies listed as Build-Depends-Indep.  I
have tried to move them to Build-Depends but the issue remains.  The
build log does find them:

  Analysing pom.xml...
  Checking dependencies for documentation packages...
  > dpkg --search /usr/share/doc/libcommons-math3-java/api/index.html
  Found libcommons-math3-java-doc
      bash -c "rm -f target/apidocs/*.sh target/apidocs/options"

If this step is what should find the right javadoc links, it seems
like it's not searching for the javadoc links for default-jdk-doc.
The links to String are still to docs.oracle.com.

On 31 August 2017 at 17:25, Emmanuel Bourg <ebourg@apache.org> wrote:
> Le 31/08/2017 à 18:03, Carnë Draug a écrit :
>
>> How do I set the path for the javadocs of other java libraries when
>> using maven-debian-helper?
>
> Good question, I'm not even sure this is supported, which is interesting
> because the *-java-doc package resolution occurring at the end of the
> build takes a lot of time for basically no benefit since the
> documentation isn't linked :D

When building upstream directly with maven, this works fine:

  mvn -Dlinks=/usr/share/doc/default-jdk-doc/api package

However, setting links on maven.properties file has no effect.  Do you
have any idea why?

Thank you
Carnë

[toc] | [prev] | [next] | [standalone]

#9974

On 31 August 2017 at 17:57, Carnë Draug <carandraug+dev@gmail.com> wrote:
> On 31 August 2017 at 17:25, Emmanuel Bourg <ebourg@apache.org> wrote:
>> Le 31/08/2017 à 18:03, Carnë Draug a écrit :
>>
>>> How do I set the path for the javadocs of other java libraries when
>>> using maven-debian-helper?
>>
>> Good question, I'm not even sure this is supported, which is interesting
>> because the *-java-doc package resolution occurring at the end of the
>> build takes a lot of time for basically no benefit since the
>> documentation isn't linked :D
>
> When building upstream directly with maven, this works fine:
>
>   mvn -Dlinks=/usr/share/doc/default-jdk-doc/api package
>
> However, setting links on maven.properties file has no effect.  Do you
> have any idea why?
>

I found out that the reason why -Dlinks is ignored is that maven's
javadoc plugin will ignore the links option in offline mode.  It's own
documentation states "only used if isOffline is set to false" [1].

It seems that the right option is to set offlineLinks [2].  In the
pom.xml file, this would be:

  <offlineLinks>
    <offlineLink>
      <url>file:///usr/share/doc/default-jdk-doc/api/</url>
      <location>file:///usr/share/doc/default-jdk-doc/api/</location>
    </offlineLink>
  </offlineLinks>

but I don't know how I would set this on a properties file.  All the
documentation says is that the user property is named offlineLinks.
Could anyone with actual maven experience give me a hand?

Carnë

[1] https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#links
[2] https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#offlineLinks

[toc] | [prev] | [next] | [standalone]

#9987

On 31 August 2017 at 17:03, Carnë Draug <carandraug+dev@gmail.com> wrote:
> Hi
>
> I am packaging some java libraries with maven-debian-helper but having
> problems setting the javadocs links properly.  I have done this for
> ant based projects but I can't figure out how to do it for maven
> projects.
>
> I took a look on a few other *-java-doc packages that are maven only
> projects (libjgoodies-looks-java-doc, libakuma-java, and
> libmetadata-extractor-java-doc) hoping to find the answer.  However,
> they all are linking do docs.oracle.com too instead of the local
> javadocs.  libmetadata-extractor-java-doc on Stretch had the correct
> javadoc links, back when upstream made use of ant and not maven.
>
> I have  tried to set user  property links [1] in  the maven.properties
> file as described in the javadoc plugin documentation but no avail.
>
> How do I set the path for the javadocs of other java libraries when
> using maven-debian-helper?
>
> Thank you
> Carnë
>
> [1] https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#links

Hi

I solved this problem.  The solution is to pass the -link command line
options directly to the javadoc program via the additionalparam
property on the debian.properties file.  Like so [2]:

    additionalparam = -link /usr/share/doc/default-jdk-doc/api/ \
                      -link /usr/share/doc/libcommons-math3-java/api/

This whole problem exists because maven's javadoc plugin, which is
being used to generate the javadocs, ignores the links property when
in offline mode.  This would work fine if using javadoc directly but
the maven plugin adds extra incompatible logic to it.  In addition,
the offlineLinks option seems to only work when extdocURL really is an
external url.  I'm unsure if the problem with offlineLink is a maven
javadoc plugin issue or the javadoc program.

Because the maven plugin is ignore the links option, we have to pass
the flags directly to javadoc with additionalparam.  However, it seems
that additionalparam is deprecated but I see no other alternative to
pass options directly.

Carnë

[2] https://github.com/carandraug/debian-libjlargearrays-java/commit/777a5805082216a86d50cd98bc517ddab1035433

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.maint.java

csiph-web