Re: javadocs links with maven-debian-helper

[Carnë Draug]

On 31 August 2017 at 17:03, Carnë Draug  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

Re: javadocs links with maven-debian-helper

[Carnë Draug]

On 31 August 2017 at 17:57, Carnë Draug  wrote:
> On 31 August 2017 at 17:25, Emmanuel Bourg  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:

  

  file:///usr/share/doc/default-jdk-doc/api/
  file:///usr/share/doc/default-jdk-doc/api/

  

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

Re: javadocs links with maven-debian-helper

[Carnë Draug]

On 31 August 2017 at 17:15, Markus Koschany  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  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ë

Re: javadocs links with maven-debian-helper

[Emmanuel Bourg]

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

Re: javadocs links with maven-debian-helper

[Markus Koschany]

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



signature.asc
Description: OpenPGP digital signature