Maven Site Plugin
  1. Maven Site Plugin
  2. MSITE-484

Support adding and overriding report plugins in new maven-site-plugin 3.x reportPlugins configuration format

    Details

    • Type: Bug Bug
    • Status: Open Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: 3.0-beta-1, 3.0-beta-2, 3.0-beta-3, 3.3
    • Fix Version/s: backlog
    • Component/s: inheritance, Maven 3
    • Labels:
      None
    • Environment:
      3.0-beta-1-SNAPSHOT
    • Number of attachments :
      3

      Description

      When using the new configuration format for reportPlugins, it appears that there's no way to:

      • Add a report plugin to a submodule
      • Override the configuration of a report plugin in a submodule

      Using the old <reporting> section, both of these use cases were supported. For large, multi-module builds, it is problematic having to respecify all reporting plugins in any submodule pom that needs to either add an additional reporting plugin or change the configuration of a reporting plugin.

      Attached is a sample project that has a parent POM configured with project-info-reports and javadoc plugin and a submodule configured with jxr plugin and javadoc plugin. The relevant output is here:

      [INFO] ------------------------------------------------------------------------
      [INFO] Building parent 1.0-SNAPSHOT
      [INFO] ------------------------------------------------------------------------
      [INFO] 
      [INFO] --- maven-clean-plugin:2.3:clean (default-clean) @ parent ---
      [INFO] Deleting file set: /Users/mpilquist/Downloads/site-parent-issue/target (included: [**], excluded: [])
      [INFO] 
      [INFO] --- maven-site-plugin:3.0-beta-1-SNAPSHOT:site (default-site) @ parent ---
      [INFO] configuring reportPlugin org.apache.maven.plugins:maven-project-info-reports-plugin:2.2
      [INFO] configuring reportPlugin org.apache.maven.plugins:maven-javadoc-plugin:2.6.1
      ...
      [INFO] ------------------------------------------------------------------------
      [INFO] Building parent-usage-test 1.0-SNAPSHOT
      [INFO] ------------------------------------------------------------------------
      [INFO] 
      [INFO] --- maven-clean-plugin:2.3:clean (default-clean) @ parent-usage-test ---
      [INFO] 
      [INFO] --- maven-site-plugin:3.0-beta-1-SNAPSHOT:site (default-site) @ parent-usage-test ---
      [INFO] configuring reportPlugin org.apache.maven.plugins:maven-jxr-plugin:2.1
      [INFO] configuring reportPlugin org.apache.maven.plugins:maven-javadoc-plugin:2.6.1
      

      Looking at the maven-site-plugin code, it appears the the reportPlugins parameter is just a regular array parameter. AFAIK, there's no way to merge list configuration items. Other plugins have worked around this by defining additional mojo parameters (e.g., maven-eclipse-plugin and buildCommands / additionalBuildCommands – http://maven.apache.org/plugins/maven-eclipse-plugin/eclipse-mojo.html). This isn't the most flexible option though as it only solves 1 level inheritance.

        Issue Links

          Activity

          Olivier Lamy made changes -
          Field Original Value New Value
          Assignee Olivier Lamy [ olamy ]
          Fix Version/s 3.0-beta-3 [ 16729 ]
          Olivier Lamy made changes -
          Link This issue depends upon MNG-4856 [ MNG-4856 ]
          Hide
          Olivier Lamy added a comment - - edited

          What you have to do is to add to indicate how to merge site plugin configuration when maven build the model
          in the child pom, you can change to ( attribute combine.children="append" )

          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>version</version>
            <configuration>
              <reportPlugins combine.children="append">
          

          btw this doesn't fix overriding configuration, with this trick some plugins can be executed more than one time

          Show
          Olivier Lamy added a comment - - edited What you have to do is to add to indicate how to merge site plugin configuration when maven build the model in the child pom, you can change to ( attribute combine.children="append" ) <plugin> <groupId> org.apache.maven.plugins </groupId> <artifactId> maven-site-plugin </artifactId> <version> version </version> <configuration> <reportPlugins combine.children= "append" > btw this doesn't fix overriding configuration, with this trick some plugins can be executed more than one time
          Olivier Lamy made changes -
          Fix Version/s 3.0-beta-4 [ 16829 ]
          Fix Version/s 3.0-beta-3 [ 16729 ]
          Affects Version/s 3.0-beta-2 [ 16693 ]
          Affects Version/s 3.0-beta-3 [ 16729 ]
          Hide
          Olivier Lamy added a comment -

          so this will probably need a hack in maven core for site plugin regarding plugin configuration inheritance.

          Show
          Olivier Lamy added a comment - so this will probably need a hack in maven core for site plugin regarding plugin configuration inheritance.
          Lukas Theussl made changes -
          Component/s Maven 3 [ 14610 ]
          Dennis Lundberg made changes -
          Fix Version/s 3.0.0 [ 16489 ]
          Fix Version/s 3.0-beta-4 [ 16829 ]
          Hide
          Herve Boutemy added a comment -

          yes, a new mecanism is to be defined in Maven core, since plugin configuration inheritance works at DOM level, without any interpretation of any content.

          Show
          Herve Boutemy added a comment - yes, a new mecanism is to be defined in Maven core, since plugin configuration inheritance works at DOM level, without any interpretation of any content.
          Lukas Theussl made changes -
          Link This issue is related to MSITE-596 [ MSITE-596 ]
          Hide
          Eric Dalquist added a comment -

          Just a note that this affects the 3.0 release of the plugin as well. Perhaps until the Maven core modifications are done the logic in the maven-site-plugin that handles the reportPlugins could be made configurable in the situation where the same reportPlugin groupId & artifactId exist.

          Perhaps something like:

          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>version</version>
            <configuration>
              <duplicatePluginPolicy>USE_LAST</duplicatePluginPolicy>
              <reportPlugins combine.children="append">
          

          The duplicatePluginPolicy option could be an enum with USE_FIRST, USE_LAST, USE_BOTH options, allowing the site plugin to know what to do if there are multiple plugins with the same groupId:artifactId in the list. This would at least allow for overrides of a single plugin without having to list every plugin the parent defines.

          Show
          Eric Dalquist added a comment - Just a note that this affects the 3.0 release of the plugin as well. Perhaps until the Maven core modifications are done the logic in the maven-site-plugin that handles the reportPlugins could be made configurable in the situation where the same reportPlugin groupId & artifactId exist. Perhaps something like: <plugin> <groupId> org.apache.maven.plugins </groupId> <artifactId> maven-site-plugin </artifactId> <version> version </version> <configuration> <duplicatePluginPolicy> USE_LAST </duplicatePluginPolicy> <reportPlugins combine.children= "append" > The duplicatePluginPolicy option could be an enum with USE_FIRST, USE_LAST, USE_BOTH options, allowing the site plugin to know what to do if there are multiple plugins with the same groupId:artifactId in the list. This would at least allow for overrides of a single plugin without having to list every plugin the parent defines.
          Hide
          Eric Dalquist added a comment - - edited

          This patch (against r1170684) provides robust support for merging PlexusConfiguration objects. I've included a unit test which demonstrates the functionality and have tested it locally with various plugin overlays with great success.

          For example if the parent pom's maven-site-plugin is:

          <plugin>
            <artifactId>maven-site-plugin</artifactId>
            <configuration>
              <reportPlugins>
                <plugin>
                  <artifactId>maven-javadoc-plugin</artifactId>
                  <version>2.8</version>
                  <configuration>
                    <links>
                      <link>http://java.sun.com/javase/6/docs/api/</link>
                      <link>http://java.sun.com/javaee/5/docs/api/</link>
                    </links>
                    <source>1.6</source>
                  </configuration>
                </plugin>
              </reportPlugins>
            </configuration>
          </plugin>
          

          And the child project pom's maven-site-plugin is:

          <plugin>
            <artifactId>maven-site-plugin</artifactId>
            <configuration>
              <defaultMergePolicy>MERGE</defaultMergePolicy>
              <reportPlugins combine.children="append">
                <plugin>
                  <artifactId>maven-javadoc-plugin</artifactId>
                  <configuration>
                    <links mergePolicy.children="BOTH" mergePolicy.removeDuplicates="true">
                      <link>http://static.springsource.org/spring/docs/3.0.x/api/</link>
                      <link>http://ehcache.org/apidocs/</link>
                      <link>http://aopalliance.sourceforge.net/doc/</link>
                      <link>http://java.sun.com/javase/6/docs/api/</link>
                    </links>
                    <maxmemory>768m</maxmemory>
                  </configuration>
                </plugin>
              </reportPlugins>
            </configuration>
          </plugin>
          

          The runtime effective result is:

          <plugin>
            <artifactId>maven-site-plugin</artifactId>
            <configuration>
              <defaultMergePolicy>MERGE</defaultMergePolicy>
              <reportPlugins combine.children="append">
                <plugin>
                  <artifactId>maven-javadoc-plugin</artifactId>
                  <configuration>
                    <links mergePolicy.children="BOTH" mergePolicy.removeDuplicates="true">
                      <link>http://static.springsource.org/spring/docs/3.0.x/api/</link>
                      <link>http://ehcache.org/apidocs/</link>
                      <link>http://aopalliance.sourceforge.net/doc/</link>
                      <link>http://java.sun.com/javase/6/docs/api/</link>
                      <link>http://java.sun.com/javaee/5/docs/api/</link>
                    </links>
                    <source>1.6</source>
                    <maxmemory>768m</maxmemory>
                  </configuration>
                </plugin>
              </reportPlugins>
            </configuration>
          </plugin>
          
          Show
          Eric Dalquist added a comment - - edited This patch (against r1170684) provides robust support for merging PlexusConfiguration objects. I've included a unit test which demonstrates the functionality and have tested it locally with various plugin overlays with great success. For example if the parent pom's maven-site-plugin is: <plugin> <artifactId> maven-site-plugin </artifactId> <configuration> <reportPlugins> <plugin> <artifactId> maven-javadoc-plugin </artifactId> <version> 2.8 </version> <configuration> <links> <link> http://java.sun.com/javase/6/docs/api/ </link> <link> http://java.sun.com/javaee/5/docs/api/ </link> </links> <source> 1.6 </source> </configuration> </plugin> </reportPlugins> </configuration> </plugin> And the child project pom's maven-site-plugin is: <plugin> <artifactId> maven-site-plugin </artifactId> <configuration> <defaultMergePolicy> MERGE </defaultMergePolicy> <reportPlugins combine.children= "append" > <plugin> <artifactId> maven-javadoc-plugin </artifactId> <configuration> <links mergePolicy.children= "BOTH" mergePolicy.removeDuplicates= "true" > <link> http://static.springsource.org/spring/docs/3.0.x/api/ </link> <link> http://ehcache.org/apidocs/ </link> <link> http://aopalliance.sourceforge.net/doc/ </link> <link> http://java.sun.com/javase/6/docs/api/ </link> </links> <maxmemory> 768m </maxmemory> </configuration> </plugin> </reportPlugins> </configuration> </plugin> The runtime effective result is: <plugin> <artifactId> maven-site-plugin </artifactId> <configuration> <defaultMergePolicy> MERGE </defaultMergePolicy> <reportPlugins combine.children= "append" > <plugin> <artifactId> maven-javadoc-plugin </artifactId> <configuration> <links mergePolicy.children= "BOTH" mergePolicy.removeDuplicates= "true" > <link> http://static.springsource.org/spring/docs/3.0.x/api/ </link> <link> http://ehcache.org/apidocs/ </link> <link> http://aopalliance.sourceforge.net/doc/ </link> <link> http://java.sun.com/javase/6/docs/api/ </link> <link> http://java.sun.com/javaee/5/docs/api/ </link> </links> <source> 1.6 </source> <maxmemory> 768m </maxmemory> </configuration> </plugin> </reportPlugins> </configuration> </plugin>
          Eric Dalquist made changes -
          Attachment MSITE-484.patch [ 57022 ]
          Hide
          Eric Dalquist added a comment -

          Note that I tried to implement this feature in a way such that it could be used by any plugin. It operates on the PlexusConfiguration interface and the merging logic has no direct ties to the maven-site-plugin

          Show
          Eric Dalquist added a comment - Note that I tried to implement this feature in a way such that it could be used by any plugin. It operates on the PlexusConfiguration interface and the merging logic has no direct ties to the maven-site-plugin
          Hide
          Olivier Lamy added a comment -

          looks interesting patch. Could you please fix license header and use correct ASF attribution (I see :"....Licensed to Jasig...." )

          Show
          Olivier Lamy added a comment - looks interesting patch. Could you please fix license header and use correct ASF attribution (I see :"....Licensed to Jasig...." )
          Hide
          Eric Dalquist added a comment -

          I just realized the patch is incomplete, I'll get the final version posted tomorrow.

          Show
          Eric Dalquist added a comment - I just realized the patch is incomplete, I'll get the final version posted tomorrow.
          Hide
          Andreas Sewe added a comment -

          FWIW, it would be great if the mergePolicy.children and mergePolicy.removeDuplicates attributes (and also combine.children) could finally become part of the POM's XML Schema: http://maven.apache.org/xsd/maven-4.0.0.xsd. It's quite annoying to see validation errors on elements like developers, which would benefit from this feature and are specified by the XSD (unlike, e.g., the plugins' configuration which is xsd:any), because these attributes are not part of the XSD.

          On a related note: Why not use XML Namespaces for mergePolicy.*? Verbosity can't be the only reason; after all, it's one xmlns declaration + a short prefix like mp vs. the longer mergePolicy on every attribute.

          Show
          Andreas Sewe added a comment - FWIW, it would be great if the mergePolicy.children and mergePolicy.removeDuplicates attributes (and also combine.children ) could finally become part of the POM's XML Schema: http://maven.apache.org/xsd/maven-4.0.0.xsd . It's quite annoying to see validation errors on elements like developers , which would benefit from this feature and are specified by the XSD (unlike, e.g., the plugins' configuration which is xsd:any ), because these attributes are not part of the XSD. On a related note: Why not use XML Namespaces for mergePolicy.* ? Verbosity can't be the only reason; after all, it's one xmlns declaration + a short prefix like mp vs. the longer mergePolicy on every attribute.
          Hide
          Eric Dalquist added a comment -

          Updated patch, replaces mergePolicy. prefix with merge: xml namespace. In my testing you can specify whatever you want for the namespace URI since I don't actually have an XSD to go with it, I used xmlns:merge="http://maven.apache.org/plugin-merge" in my test pom.

          This patch should be complete, all integration tests pass and the copyright headers are correct. I do have an Apache ICLA on file and am an active committer in the portals project: http://people.apache.org/committer-index.html

          I would love this to become a core feature of Maven itself for merging plugin configurations. I'm not sure where to go with getting that requested as a feature. I'm hoping that this this seems to affect the site plugin more than others it would be faster to get the fix in here so it could be used as soon as possible.

          Show
          Eric Dalquist added a comment - Updated patch, replaces mergePolicy. prefix with merge: xml namespace. In my testing you can specify whatever you want for the namespace URI since I don't actually have an XSD to go with it, I used xmlns:merge="http://maven.apache.org/plugin-merge" in my test pom. This patch should be complete, all integration tests pass and the copyright headers are correct. I do have an Apache ICLA on file and am an active committer in the portals project: http://people.apache.org/committer-index.html I would love this to become a core feature of Maven itself for merging plugin configurations. I'm not sure where to go with getting that requested as a feature. I'm hoping that this this seems to affect the site plugin more than others it would be faster to get the fix in here so it could be used as soon as possible.
          Eric Dalquist made changes -
          Attachment MSITE-484.patch [ 57028 ]
          Hide
          Herve Boutemy added a comment -

          I didn't have time to check for the moment, but yes, this seems interesting at Maven core level: there have already been discussion about having more flexible merge policy for some pom content
          see MNG-3124 and MNG-2807

          Show
          Herve Boutemy added a comment - I didn't have time to check for the moment, but yes, this seems interesting at Maven core level: there have already been discussion about having more flexible merge policy for some pom content see MNG-3124 and MNG-2807
          Dennis Lundberg made changes -
          Fix Version/s backlog [ 18457 ]
          Fix Version/s 3.1 [ 16489 ]
          Herve Boutemy made changes -
          Link This issue relates to MNG-4162 [ MNG-4162 ]
          Herve Boutemy made changes -
          Link This issue is duplicated by MSITE-653 [ MSITE-653 ]
          Herve Boutemy made changes -
          Affects Version/s 3.3 [ 18876 ]
          Herve Boutemy made changes -
          Link This issue is related to MNG-5477 [ MNG-5477 ]

            People

            • Assignee:
              Olivier Lamy
              Reporter:
              Michael Pilquist
            • Votes:
              41 Vote for this issue
              Watchers:
              39 Start watching this issue

              Dates

              • Created:
                Updated: