Local Maven Site in Multi-Module Project

Maven has a nice feature for generating project web sites. I like to use it especially for code coverage and static code analysis reports. For good explanation of setting it up is see an article at JavaWorld.

What might be surprising though is the way it is handled in multi-module project. When you run mvn site on such project, Maven will generate a site for each module independently. Unfortunately, links between module sites won’t work.

In order to make the links between modules work the site has to be deployed or staged. Most examples I’ve seen show how to deploy the site using SCP. I don’t work on any publicly available project so this is not what I wanted. In this post I’m going to explain few ways to create a local Maven site. I decided to post my findings because it was not immediately obvious for me how to do this from the documentation.

Site URL

In all options you have to add distribution management section in the top-level POM. The site URL will be different depending on the chosen option.

  <distributionManagement>
    <site>
      <id>site</id>
      <name>Project Site</name>
      <url>some URL</url>
    </site>
  </distributionManagement>

Stage

site:stage goal is intended to test the links between the modules before deploying the site. If you are going to use it only for local generation the URL doesn’t need to be valid so you can set it simply to “site”. Running the mvn site:stage from the root project directory should result in the site being created in target\staging\site with all links between the modules working correctly.

If you don’t want the site to be generated in the project-specific location use stagingDirectory parameter, for example mvn site:stage -DstagingDirectory=C:\project\site

Staging is relatively new option in Maven site plugin. It still has some issues and I was unable to use it in one of my projects. You can use the local deploy as a workaround.

Deploy

In addition to SCP you can also deploy the site using file protocol. In this case set the URL to something like file:///C:/project/site and run mvn site-deploy from the root project directory.

Creating the site in project-specific directory is a little bit more tricky using this technique. In order to make it work you can use ${user.dir} Java system property which points to current working directory and run mvn site-deploy from the root project directory. The URL may look like this: file:///${user.dir}/target/deployed-site. I also tried to use ${basedir} property but it didn’t work because its value was different for each module.

Additional comments

On several occasions I happened to see strange compilation errors during Maven site generation. I suspect that some reporting plugins retrieve project artifacts from the local repository under some circumstances. In order to ensure that they get the latest version I use install phase before running site. I also start with clean to ensure that the most recent version of compiled classes is used. The final command is either mvn clean install site:stage or mvn clean install site-deploy.