| ------ |
| Using maven-site-plugin with Maven 3 |
| ------ |
| Olivier Lamy |
| ------ |
| 2011-07-22 |
| ------ |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ~~ NOTE: For help with the syntax of this file, see: |
| ~~ http://maven.apache.org/doxia/references/apt-format.html |
| |
| |
| Using maven-site-plugin with Maven 3 |
| |
| A major aim of the refactoring in Maven 3 was to decouple the Maven core from {{{/doxia/}Doxia}} |
| and to allow arbitrary reporting systems to be developed. For this reason, all reporting |
| related code has been removed from the core of Maven 3 |
| ({{{https://issues.apache.org/jira/browse/MNG-4162}MNG-4162}}). |
| |
| As a result, the 2.x versions of the Maven Site Plugin will not work with Maven 3. |
| Using such versions of Maven Site Plugin with Maven 3 won't generate any reports from reporting plugins, |
| only hand-written Doxia documents (apt, xdoc, ...) will be rendered. |
| |
| You need to use version 3.x of the Site Plugin, in order for it to work with Maven 3. |
| |
| %{toc|section=1|fromDepth=2|toDepth=3} |
| |
| * Plugins Compatibility Matrix for Maven 3 |
| |
| ** Plugins Maintained by the Apache Maven Community |
| |
| Tests have been made on the reporting profile of the Maven parent POM which enables some reports. |
| You will need to update some of these plugins for them to work with Maven 3. Below you will find the minimum version |
| required for these plugins to work in Maven 3. |
| |
| *-----------------------------------+-----------+ |
| | <<Plugin>> |<<Version>>| |
| *-----------------------------------+-----------+ |
| | maven-changelog-plugin | 2.1 | |
| *-----------------------------------+-----------+ |
| | maven-changes-plugin | 2.1 | |
| *-----------------------------------+-----------+ |
| | maven-checkstyle-plugin | 2.5 | |
| *-----------------------------------+-----------+ |
| | maven-javadoc-plugin | 2.6.1 | |
| *-----------------------------------+-----------+ |
| | maven-jxr-plugin | 2.1 | |
| *-----------------------------------+-----------+ |
| | maven-plugin-plugin | 2.5.1 | |
| *-----------------------------------+-----------+ |
| | maven-pmd-plugin | 2.4 | |
| *-----------------------------------+-----------+ |
| | maven-project-info-reports-plugin | 2.2 | |
| *-----------------------------------+-----------+ |
| | maven-surefire-report-plugin | 2.4.3 | |
| *-----------------------------------+-----------+ |
| |
| ** Plugins Maintained by the Mojo Community |
| |
| *----------------------------------+-------------+ |
| | <<Plugin>> |<<Version>> | |
| *----------------------------------+-------------+ |
| | cobertura-maven-plugin | 2.3 | |
| *----------------------------------+-------------+ |
| | emma-maven-plugin | 1.0-alpha-2 | |
| *----------------------------------+-------------+ |
| |
| * Version Resolution |
| |
| When used with Maven 3, a report plugin version can be empty (like build plugins). |
| |
| The following order/strategy will be used to find/resolve a version: |
| |
| * search the same groupId/artifactId in the build.plugins section |
| |
| * search the same groupId/artifactId in the build.pluginManagement.plugins section |
| |
| * resolve with current repositories (can include automatic SNAPSHOT resolution) |
| |
| [] |
| |
| Notice that Maven 3.0.x reports a misleading warning in case of empty report plugin version: see |
| {{{https://issues.apache.org/jira/browse/MNG-5477}MNG-5477}}, fixed in Maven 3.1.0. |
| |
| * Site descriptor attachment |
| |
| In Maven 3, the default execution of <<<site:attach-descriptor>>> has been removed from the |
| built-in lifecycle bindings for projects with <<<pom>>> packaging. Users that actually use those |
| projects to provide a common site descriptor for sub modules will need to explicitly define |
| the following goal execution to restore the intended behavior: |
| |
| +-----+ |
| <build> |
| <plugins> |
| <plugin> |
| <artifactId>maven-site-plugin</artifactId> |
| <executions> |
| <execution> |
| <id>attach-descriptor</id> |
| <goals> |
| <goal>attach-descriptor</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| </build> |
| +-----+ |
| |
| * Using the same version of maven-site-plugin for both Maven 2 and Maven 3 |
| |
| Starting with version 3.0, maven-site-plugin can run with both Maven 2.2.x and 3.x. The |
| results should be exactly the same if reports are configured in the classical Maven 2 way, in the <<<\<reporting\>>>> |
| section. If you use the new Maven 3 way of configuring reports (not recommended), in the <<<\<reportPlugins\>>>> section, |
| it will only work with Maven 3. |
| |
| The following snippet automatically activates <<<site:attach-descriptor>>> when run with Maven 3: |
| |
| +-----+ |
| <profiles> |
| <profile> |
| <id>maven-3</id> |
| <activation> |
| <file> |
| <!-- This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) --> |
| <exists>${basedir}</exists> |
| </file> |
| </activation> |
| <build> |
| <plugins> |
| <plugin> |
| <artifactId>maven-site-plugin</artifactId> |
| <executions> |
| <execution> |
| <id>attach-descriptor</id> |
| <goals> |
| <goal>attach-descriptor</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| </build> |
| </profile> |
| </profiles> |
| +-----+ |
| |
| <<Note:>> The profile is needed to avoid duplicate install and deploy of the site descriptor when running with Maven 2.2.x |
| due to POM default lifecycle mappings. |
| |
| * Using maven-site-plugin 2.x with Maven 2 and maven-site-plugin 3.x with Maven 3 |
| |
| Before maven-site-plugin 3.0, maven-site-plugin 2.x was compatible only with Maven 2 and maven-site-plugin |
| 3.0-betas were compatible only with Maven 3. A trick was needed to let Maven 2 use one version of the plugin and Maven 3 |
| another version in the same <<<pom.xml>>>. |
| |
| The following snippet automatically activates maven-site-plugin 3.x when run with Maven 3: |
| |
| +-----+ |
| <profiles> |
| <profile> |
| <id>maven-3</id> |
| <activation> |
| <file> |
| <!-- This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) --> |
| <exists>${basedir}</exists> |
| </file> |
| </activation> |
| <build> |
| <pluginManagement> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-site-plugin</artifactId> |
| <version>${project.version}</version> |
| </plugin> |
| </plugins> |
| </pluginManagement> |
| <plugins> |
| <plugin> |
| <artifactId>maven-site-plugin</artifactId> |
| <executions> |
| <execution> |
| <id>attach-descriptor</id> |
| <goals> |
| <goal>attach-descriptor</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| </plugins> |
| </build> |
| </profile> |
| </profiles> |
| +-----+ |
| |
| <<Note:>> Be aware that you should also use <<<\<pluginManagement\>>>> to specify the version for maven-site-plugin 2.x. |
| If you define the plugin version directly inside the <<<\<plugins\>>>> section of the <<<\<build\>>>> element |
| then that version is always used, no matter which version of Maven is used. That snippet would look like this: |
| |
| +-----+ |
| <build> |
| <pluginManagement> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-site-plugin</artifactId> |
| <version>2.3</version> |
| </plugin> |
| </plugins> |
| </pluginManagement> |
| </build> |
| +-----+ |
| |
| * Configuration formats |
| |
| The <<<\<reporting\>>>> section of the POM has been added to the Site Plugin's configuration as <<<\<reportPlugins\>>>> in Maven 3. |
| The content of the configuration has been kept as similar as possible to Maven 2 and |
| the <<<{{{/shared/maven-reporting-exec/}maven-reporting-exec}}>>> component transforms the configuration on the fly. |
| |
| ** Classic configuration (Maven 2 & 3) |
| |
| Reports are configured in the <<<\<reporting\>>>> section of the POM. |
| <<This stays the recommended configuration format.>> |
| |
| +-----+ |
| <project> |
| ... |
| <reporting> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-project-info-reports-plugin</artifactId> |
| <version>2.4</version> |
| <configuration> |
| <dependencyDetailsEnabled>false</dependencyDetailsEnabled> |
| <dependencyLocationsEnabled>false</dependencyLocationsEnabled> |
| </configuration> |
| <reportSets> |
| <reportSet> |
| <reports> |
| <report>dependencies</report> |
| <report>scm</report> |
| </reports> |
| </reportSet> |
| </reportSets> |
| </plugin> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <version>2.8</version> |
| </plugin> |
| </plugins> |
| </reporting> |
| ... |
| </project> |
| +-----+ |
| |
| ** New Configuration (Maven 3 only, no reports configuration inheritance) |
| |
| Starting with <<<maven-site-plugin>>> 3.0, reports could be configured in the configuration of <<<maven-site-plugin>>> |
| as <<<\<reportPlugins\>>>> elements. |
| |
| <<This new configuration format is not actually ready for end-users: please don't use it for the moment.>> |
| |
| As a consequence, with <<<maven-site-plugin>>> 3.7, the <<<\<reportPlugins\>>>> configuration has simply been removed |
| (and marked marked private/internal since 3.3), and |
| {{{https://issues.apache.org/jira/browse/MNG-6189}Maven 3.5.0 prints following warning if <<<\<reportPlugins\>>>> is used}}: |
| |
| +-----+ |
| [WARNING] Reporting configuration should be done in <reporting> section, not in maven-site-plugin <configuration> as reportPlugins parameter. |
| +-----+ |
| |
| This documentation is kept public only to help people who used <<<\<reportPlugins\>>>> in previous versions |
| understand why they need to migrate back to classic configuration, and learn how to switch back to |
| {{{Classic_configuration_Maven_2__3}<<<\<reports\><plugins\>>>> classic configuration}}. |
| |
| <Explanation:> The (former) new format did not support report plugins configuration inheritance, which is crucial for |
| usability: see {{{https://issues.apache.org/jira/browse/MSITE-484}MSITE-484}}. This field is technically necessary to remove |
| most reporting logic from Maven 3, but a new inheritance mechanism still needs to be added to make it as flexible as the old format: |
| we made the field public before finding this crucial limitation and required to explain later why end-users must not use it, then |
| cannot use it since <<<maven-site-plugin>>> 3.3. |
| |
| Here is how this feature looked like: |
| |
| +-----+ |
| <project> |
| ... |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-site-plugin</artifactId> |
| <version>3.2</version><!-- last maven-site-plugin version supporting this reportPlugins configuration --> |
| <configuration> |
| ... |
| <reportPlugins><!-- not supported any more, causes WARNING in Maven 3.5.0: move to <project><reporting><plugins> instead --> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-project-info-reports-plugin</artifactId> |
| <version>2.4</version> |
| <configuration> |
| <dependencyDetailsEnabled>false</dependencyDetailsEnabled> |
| <dependencyLocationsEnabled>false</dependencyLocationsEnabled> |
| </configuration> |
| <!-- simpler configuration without reportSets available for usual cases --> |
| <reports> |
| <report>dependencies</report> |
| <report>scm</report> |
| </reports> |
| </plugin> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <version>2.8</version> |
| </plugin> |
| </reportPlugins> |
| </configuration> |
| </plugin> |
| </plugins> |
| </build> |
| ... |
| </project> |
| +-----+ |
| |
| * Inheritance of reports for Maven 3 before 3.0.4 |
| |
| Maven 3 before 3.0.4 works differently from Maven 2 when dealing with inheritance of reports: given |
| a plugin providing multiple report goals, in Maven 2, |
| reports configured in child pom are added to reports from parent, whereas in Maven 3 up to 3.0.3 |
| reports from child replace reports from parent. Since 3.0.4, though, inheritance of reports works |
| in the same way as with Maven 2. |
| |
| For example, given a multi module build where the parent POM has the <<<index>>> report |
| configured and the child POM has the <<<summary>>> report configured for |
| <<<maven-project-info-reports-plugin>>> plugin: |
| |
| * with Maven 2 and Maven 3.0.4, the child site will have both the <<<index>>> and <<<summary>>> reports, |
| |
| * with Maven 3.0.3, the child site will have only the <<<summary>>> report. |
| |
| [] |
| |
| For more info see {{{https://issues.apache.org/jira/browse/MSITE-596}MSITE-596}}. |