Maven 3 中重构的一个主要目的是将 Maven 核心与Doxia分离,并允许开发任意报告系统。因此,所有与报告相关的代码都已从 Maven 3 ( MNG-4162 ) 的核心中删除。
因此,2.x 版本的 Maven 站点插件将无法与 Maven 3 一起使用。在 Maven 3 中使用此类版本的 Maven 站点插件不会从报告插件生成任何报告,只会生成手写的 Doxia 文档(apt、 xdoc, ...) 将被渲染。
您需要使用站点插件的 3.x 版本,以便它与 Maven 3 一起使用。
与 Maven 3 一起使用时,报告插件版本可以为空(如构建插件)。
以下顺序/策略将用于查找/解决版本:
Maven 2 和 Maven 3 在处理报告继承时的工作方式不同:给定一个提供多个报告目标的插件,在 Maven 2 中,子 pom 中配置的报告被添加到来自父级的报告中,而在 Maven 3 中来自子级的报告替换来自父级的报告。
例如,给定一个多模块构建,其中父 POM 配置了索引报告,子 POM配置了为maven-project-info-reports-plugin插件配置的摘要报告:
有关详细信息,请参阅MSITE-596。
在 Maven 3 中, site:attach-descriptor的默认执行已从pom打包项目的内置生命周期绑定中删除。实际使用这些项目为子模块提供公共站点描述符的用户将需要明确定义以下目标执行以恢复预期行为:
<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>
从 3.0 版开始,maven-site-plugin 可以与 Maven 2.2.x 和 3.x 一起运行。如果在<reporting>部分中以经典的 Maven 2 方式配置报告,结果应该完全相同。如果您使用新的 Maven 3 配置报告的方式(不推荐),在<reportPlugins>部分,它将仅适用于 Maven 3。
以下代码片段在使用 Maven 3 运行时会自动激活site:attach-descriptor :
<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>
注意:由于 POM 默认生命周期映射,需要配置文件以避免在使用 Maven 2.2.x 运行时重复安装和部署站点描述符。
在 maven-site-plugin 3.0 之前,maven-site-plugin 2.x 仅与 Maven 2 兼容,maven-site-plugin 3.0-betas 仅与 Maven 3 兼容。需要一个技巧来让 Maven 2 使用一个版本的该插件和 Maven 3 在同一个pom.xml中的另一个版本。
以下代码片段在使用 Maven 3 运行时会自动激活 maven-site-plugin 3.x:
<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>3.2</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>
注意:请注意,您还应该使用<pluginManagement>来指定 maven-site-plugin 2.x 的版本。如果您直接在<build>元素的<plugins>部分中定义插件版本,则始终使用该版本,无论使用哪个版本的 Maven。该片段看起来像这样:
<build> <pluginManagement> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <version>2.3</version> </plugin> </plugins> </pluginManagement> </build>
POM的<reporting>部分已添加到 Maven 3 中的站点插件配置中。配置的内容已尽可能与 Maven 2 保持相似,并且maven-reporting-exec组件会即时转换配置。
报告在 POM 的<reporting>部分中配置。这仍然是推荐的配置格式。
<reporting> <excludeDefaults>true</excludeDefaults> <outputDirectory>${project.build.directory}/site</outputDirectory> <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>
报告可以在maven-site-plugin的配置中配置为<reportPlugins>元素。
这种新的配置格式实际上并没有为最终用户准备好:请暂时不要使用它。
说明:新格式实际上不支持报告插件配置继承,这对可用性至关重要:参见MSITE-484。这种格式在技术上是从 Maven 3 中删除大多数报告逻辑所必需的,但仍需要添加新的继承机制以使其与旧格式一样灵活。
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <version>3.2</version> <configuration> ... <reportPlugins> <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>