Running JavaDoc in Maven 2 post-build step

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Running JavaDoc in Maven 2 post-build step

McManus,Alexander

There are some oddities in the behaviour of the Maven 2 JavaDoc plugin when it aggregates JavaDoc across multiple modules. To cut a long story short, I found that if I was working from a clean local repository, I had to run an “install” and let that complete, before running “javadoc:javadoc” as a separate command. When I ran the two combined, it complained about not finding artifacts from the sub-modules – I think this is actually a limitation in Maven aggregation behaviour rather than a problem with the JavaDoc plugin itself.

 

My solution was to run the “javadoc:javadoc” command in a post-build step. Unfortunately, the output from this doesn’t seem to get picked up by Hudson and pulled into the build results.

I’ve seen this thread which suggests the post-build steps should be working as I’d hoped: http://www.nabble.com/post-build-actions-in-maven-2-project-td12101138.html.

 

Have I missed something here, or should I raise a bug or an enhancement request?

 

Thanks in advance, Alex.

Reply | Threaded
Open this post in threaded view
|

Re: Running JavaDoc in Maven 2 post-build step

Kohsuke Kawaguchi
Administrator

McManus,Alexander wrote:
> There are some oddities in the behaviour of the Maven 2 JavaDoc plugin
> when it aggregates JavaDoc across multiple modules. To cut a long story
> short, I found that if I was working from a clean local repository, I
> had to run an "install" and let that complete, before running
> "javadoc:javadoc" as a separate command. When I ran the two combined, it
> complained about not finding artifacts from the sub-modules - I think
> this is actually a limitation in Maven aggregation behaviour rather than
> a problem with the JavaDoc plugin itself.

Not sure, but it sounds like a Maven issue, not a Hudson issue.

Are you saying "mvn install javadoc:javadoc" doesn't work? Not that I've
seen really a lot, but I've never seen that mode of failure.

> My solution was to run the "javadoc:javadoc" command in a post-build
> step. Unfortunately, the output from this doesn't seem to get picked up
> by Hudson and pulled into the build results.
>
> I've seen this thread which suggests the post-build steps should be
> working as I'd hoped:
> http://www.nabble.com/post-build-actions-in-maven-2-project-td12101138.h
> tml.
>
> Have I missed something here, or should I raise a bug or an enhancement
> request?
I don't think it makes sense to run Maven in the main build as well as
in the post-build. If anything I suppose the RFE could be to let you run
two separate Maven reactor sessions (the equivalent of "mvn install; mvn
javadoc:javadoc"), although modeling wise it raises a lot of questions
--- e.g., if both produces artifacts, which one do we pick up?

--
Kohsuke Kawaguchi
Sun Microsystems                   http://weblogs.java.net/blog/kohsuke/

smime.p7s (4K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

RE: Re: Running JavaDoc in Maven 2 post-build step

McManus,Alexander
Hi Kohsuke,

Thanks for your response.

I'm using Maven 2.09 and yes, "mvn install javadoc:javadoc" doesn't work
on a multi-module build. Or at least, it doesn't work if you are
aggregating JavaDoc over the multi-module build, and your local
repository is empty. It's definitely a Maven issue rather than a Hudson
one.

Here's what appears to be happening, given a project structure like
this:

/my-project
    /sub-module1
    /sub-module2

When you run "mvn install javadoc:javadoc", it runs:

        /my-project install
        /my-project javadoc:javadoc
        /sub-module1 install
        /sub-module1 javadoc:javadoc
        /sub-module2 install
        /sub-module2 javadoc:javadoc

When it runs the /my-project javadoc:javadoc, it seems to look for
sub-module1 and sub-module2 artifacts in the local repository, doesn't
find them and fails (because install hasn't been run on the sub-modules
yet). This is why my solution was to separate the two, so that all of
the installs run first, then followed by the javadoc:javadoc (and I also
use the -N (non-recursive) flag for the JavaDoc so that it just runs on
the top-level project).

If you've already installed the project once, then the following times
the "mvn install javadoc:javadoc" works OK because there are artifacts
in the local repository. However, it's clearly working against artifacts
from the previous build rather than the current one, which could lead to
problems if, for example, there's been major refactoring.

> I don't think it makes sense to run Maven in the main build as well as
> in the post-build. If anything I suppose the RFE could be to let you
run
> two separate Maven reactor sessions (the equivalent of "mvn install;
mvn
> javadoc:javadoc"), although modeling wise it raises a lot of questions
> --- e.g., if both produces artifacts, which one do we pick up?

Ahh, are you saying that the artifacts would be picked up from a Maven
post-build step if the main build wasn't also Maven?

I'd be happy with a solution based on multiple reactor sessions also.
I'd suggest you pick up artifacts from all sessions, and have a simple
rule for handling the same artifact being generated from multiple
sessions - e.g. take the last one generated. It would be useful if each
reactor session could have its own parameters (e.g. so that I could use
the -N flag for one of them).

Do you have any other ideas for workarounds? Should I add this as a RFE?

Thanks again, Alex.


-----Original Message-----
From: Kohsuke Kawaguchi [mailto:[hidden email]]
Sent: 26 June 2009 23:58
To: [hidden email]
Subject: Re: Running JavaDoc in Maven 2 post-build step


McManus,Alexander wrote:
> There are some oddities in the behaviour of the Maven 2 JavaDoc plugin
> when it aggregates JavaDoc across multiple modules. To cut a long
story
> short, I found that if I was working from a clean local repository, I
> had to run an "install" and let that complete, before running
> "javadoc:javadoc" as a separate command. When I ran the two combined,
it
> complained about not finding artifacts from the sub-modules - I think
> this is actually a limitation in Maven aggregation behaviour rather
than
> a problem with the JavaDoc plugin itself.

Not sure, but it sounds like a Maven issue, not a Hudson issue.

Are you saying "mvn install javadoc:javadoc" doesn't work? Not that I've
seen really a lot, but I've never seen that mode of failure.

> My solution was to run the "javadoc:javadoc" command in a post-build
> step. Unfortunately, the output from this doesn't seem to get picked
up
> by Hudson and pulled into the build results.
>
> I've seen this thread which suggests the post-build steps should be
> working as I'd hoped:
>
http://www.nabble.com/post-build-actions-in-maven-2-project-td12101138.h
> tml.
>
> Have I missed something here, or should I raise a bug or an
enhancement
> request?

I don't think it makes sense to run Maven in the main build as well as
in the post-build. If anything I suppose the RFE could be to let you run
two separate Maven reactor sessions (the equivalent of "mvn install; mvn
javadoc:javadoc"), although modeling wise it raises a lot of questions
--- e.g., if both produces artifacts, which one do we pick up?

--
Kohsuke Kawaguchi
Sun Microsystems                   http://weblogs.java.net/blog/kohsuke/


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]