| ----- |
| Introduction |
| ----- |
| Hervé Boutemy |
| ----- |
| 2013-07-24 |
| ----- |
| |
| ~~ 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 |
| |
| ${project.name} |
| |
| Classes to prepare report plugins execution with Maven 3, through |
| {{{./apidocs/org/apache/maven/reporting/exec/MavenReportExecutor.html}MavenReportExecutor}} |
| ({{{./apidocs/org/apache/maven/reporting/exec/DefaultMavenReportExecutor.html}implementation}}). |
| |
| Since 1.4, the request can (and should) be populated from |
| {{{/ref/current/maven-model/maven.html#class_reporting}pom's <<<\<reporting\>>>> section}}, |
| injected in Mojo parameter as <<<$\{project.reporting.plugins\}>>> default value: |
| |
| +----+ |
| @Parameter( defaultValue = "${esc.d}{project.reporting.plugins}", readonly = true ) |
| private org.apache.maven.model.ReportPlugin[] reportingPlugins; |
| +----+ |
| |
| Contrary to Maven 2.x, report <<<\<version\>>>> explicit definition is optional: |
| if no version is specified for a report plugin, version is determined by |
| |
| [[1]] searching for the plugin in the <<<build/plugins>>> section of the pom, |
| |
| [[2]] searching for the plugin in the <<<build/pluginManagement>>> section of the pom, |
| |
| [[3]] asking {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/version/PluginVersionResolver.html}PluginVersionResolver}} |
| to get a fallback version and display a warning as it's not a recommended use. |
| |
| [] |
| |
| Since <<<maven-reporting-exec>>> 1.2 (which is used by <<<maven-site-plugin>>> 3.4), plugin configuration in |
| <<<build/pluginManagement>>> is also injected into reports. |
| |
| * Notice on now obsolete reportPlugin format |
| |
| This section is kept to explain what happened in previous releases of the component, but this approach has been |
| abandonned so far after discovering major limitations: see |
| {{{/plugins/maven-site-plugin/maven-3.html#New_Configuration_Maven_3_only_no_reports_configuration_inheritance}Maven Site Plugin documentation}} |
| for more details. |
| |
| Report plugins can be configured in <<<\<configuration\>>>> element of <<<maven-site-plugin>>> or any other |
| report building plugin with following XML model corresponding to plugin's |
| <<<List<{{{./apidocs/org/apache/maven/reporting/exec/ReportPlugin.html}ReportPlugin}}>>>> parameter: |
| |
| +----+ |
| <reportPlugins> |
| <reportPlugin> |
| <groupId/> |
| <artifactId/> |
| <version/> |
| <configuration/> |
| <reports/> |
| <reportSets> |
| <reportSet> |
| <id/> |
| <configuration/> |
| <reports/> |
| </reportSet> |
| </reportSets> |
| </reportPlugin> |
| </reportPlugins> |
| +----+ |
| |
| Notice this is the model from plugins in |
| {{{/ref/current/maven-model/maven.html#class_reporting}<<<\<reporting\>>>> section of POM}}: |
| |
| * without <<<\<inherited\>>>> element: reporting plugins configuration inheritance is not supported at this level |
| (see {{{https://issues.apache.org/jira/browse/MSITE-484}MSITE-484}}), |
| |
| * with additional <<<\<reports\>>>> list outside <<<\<reportSet\>>>> that simplifies reports configuration in usual cases. |
| |
| [] |
| |
| Maven 3 core makes an automatic transformation of <<<\<reporting\>>>> POM section (which supports configuration inheritance) |
| to <<<maven-site-plugin>>>'s <<<reportPlugins>>> configuration through the |
| {{{/ref/current/maven-model-builder/apidocs/org/apache/maven/model/plugin/ReportingConverter.html}ReportingConverter}} |
| component. |
| |
| But Maven 3 does not do the same job for any other plugin wanting to use reports, like <<<maven-pdf-plugin>>> for example: |
| this is one of the key limitations that made Maven team drop this approach. |