Maven включает JavaDoc Jar в сборку - PullRequest
Новая
       22

Maven включает JavaDoc Jar в сборку

5 голосов
/ 08 октября 2009

У меня есть проект с несколькими модулями, в том числе и за который отвечает за сборку финальной сборки из артефактов других модулей. Как часть сборки, я хочу включить JavaDocs для двух других модулей. Я обновил файлы pom для этих модулей, чтобы сгенерировать файлы JAR JavaDoc, и изменил проект сборки, чтобы перечислять эти файлы Jar JavaDoc как зависимости. Однако, когда я собираю проект с верхнего уровня, проект сборки говорит мне, что он не может найти javaDoc jar. Если я сначала установлю все остальные модули, а затем соберу модуль сборки напрямую, сборка будет работать нормально.

Как получить правильную сборку со всеми указанными зависимостями при запуске из проекта верхнего уровня?

Отредактировано для добавления дополнительной информации по запросу респондентов:

Вот упрощенный проект, который я создал вместе, чтобы продемонстрировать проблему. Структура каталога выглядит следующим образом: 

sample/
  \--pom.xml
  \--module1/
       \--pom.xml
       \--src/ 
            \--{the usual main/java layout with a single java file, with javadocs}
  \--package/
       \--pom.xml
       \--assemblies/
            \--bin.xml

Верхний уровень pom.xml под образцом выглядит следующим образом: 

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>test</groupId>
  <artifactId>project</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <modules>
    <module>module1</module>
    <module>package</module>
  </modules>

  <build>
    <defaultGoal>package</defaultGoal>
  </build>
</project>

module1 pom.xml - это основной файл проекта с записью для плагина javadoc: 

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>test</groupId>
  <artifactId>module1</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.6</version>
        <executions>
          <execution>
            <id>javadoc-jar</id>
            <phase>package</phase>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Файл pom модуля пакета определяет зависимости от файла JAR модуля1 и файла JavaDoc модуля1: 

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <!-- The Basics -->
  <groupId>test</groupId>
  <artifactId>packaging</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <!-- Shared Dependencies -->
  <dependencies>
    <dependency>
      <groupId>test</groupId>
      <artifactId>module1</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>

    <dependency>
      <groupId>test</groupId>
      <artifactId>module1</artifactId>
      <version>1.0-SNAPSHOT</version>
      <classifier>javadoc</classifier>
    </dependency>
  </dependencies>

  <!-- Build Settings -->
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>2.2-beta-4</version>
        <configuration>
          <descriptors>
            <descriptor>assemblies/bin.xml</descriptor>
          </descriptors>
        </configuration>

        <executions>
          <execution>
            <id>make-assembly</id> <!-- this is used for inheritance merges -->
            <phase>package</phase> <!-- append to the packaging phase. -->
            <goals>
              <goal>single</goal> <!-- goals == mojos -->
            </goals>
          </execution>
        </executions>

      </plugin>

    </plugins>
  </build>

</project>

И, наконец, файл сборки включает в себя две зависимости, при этом файл jar JavaDoc сохраняется распакованным в собранный файл. У меня есть каждый пакет dependencySet, использующий строгую фильтрацию, чтобы выделить неспособность плагина сборки найти указанные файлы. 

<assembly>
  <id>bin</id>
  <formats>
    <format>jar</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>

  <dependencySets>
    <dependencySet>
      <excludes>
        <!-- Exclude the Jars that are included in later sections -->
        <exclude>test:module1:jar:javadoc</exclude>
      </excludes>
      <outputDirectory>lib</outputDirectory>
      <unpack>false</unpack>
      <useTransitiveDependencies>true</useTransitiveDependencies>
      <useTransitiveFiltering>false</useTransitiveFiltering>
      <useProjectArtifact>false</useProjectArtifact>
    </dependencySet>

    <dependencySet>
      <includes>
        <include>test:module1:jar:javadoc</include>
      </includes>
      <outputDirectory>docs</outputDirectory>
      <unpack>true</unpack>
      <useTransitiveDependencies>true</useTransitiveDependencies>
      <useProjectArtifact>false</useProjectArtifact>
      <useStrictFiltering>true</useStrictFiltering>
    </dependencySet>
  </dependencySets>
</assembly>

Запуск этого проекта сверху приводит к следующему выводу: 

[INFO] Scanning for projects...
[INFO] Reactor build order: 
[INFO]   Unnamed - test:module1:jar:1.0-SNAPSHOT
[INFO]   Unnamed - test:packaging:pom:1.0-SNAPSHOT
[INFO]   Unnamed - test:project:pom:1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] Building Unnamed - test:module1:jar:1.0-SNAPSHOT
[INFO]    task-segment: [clean, package]
[INFO] ------------------------------------------------------------------------
[INFO] [clean:clean]
[INFO] Deleting directory /Users/john/Documents/src/workspace/sample/module1/target
[INFO] [resources:resources]
[WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 0 resource
[INFO] [compiler:compile]
[INFO] Compiling 1 source file to /Users/john/Documents/src/workspace/sample/module1/target/classes
[INFO] [resources:testResources]
[WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory /Users/john/Documents/src/workspace/sample/module1/src/test/resources
[INFO] [compiler:testCompile]
[INFO] No sources to compile
[INFO] [surefire:test]
[INFO] No tests to run.
[INFO] [jar:jar]
[INFO] Building jar: /Users/john/Documents/src/workspace/sample/module1/target/module1-1.0-SNAPSHOT.jar
[INFO] [javadoc:jar {execution: javadoc-jar}]
[WARNING] Source files encoding has not been set, using platform encoding MacRoman, i.e. build is platform dependent!
Loading source files for package test...
Constructing Javadoc information...
Standard Doclet version 1.5.0_20
Building tree for all the packages and classes...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/test//AClass.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/test//package-frame.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/test//package-summary.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/test//package-tree.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/constant-values.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/test/class-use//AClass.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/test//package-use.html...
Building index for all the packages and classes...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/overview-tree.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/index-all.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/deprecated-list.html...
Building index for all classes...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/allclasses-frame.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/allclasses-noframe.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/index.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/help-doc.html...
Generating /Users/john/Documents/src/workspace/sample/module1/target/apidocs/stylesheet.css...
[INFO] Building jar: /Users/john/Documents/src/workspace/sample/module1/target/module1-1.0-SNAPSHOT-javadoc.jar
[INFO] ------------------------------------------------------------------------
[INFO] Building Unnamed - test:packaging:pom:1.0-SNAPSHOT
[INFO]    task-segment: [clean, package]
[INFO] ------------------------------------------------------------------------
[INFO] [clean:clean]
[INFO] Deleting directory /Users/john/Documents/src/workspace/sample/package/target
[INFO] [site:attach-descriptor]
[INFO] [assembly:single {execution: make-assembly}]
[INFO] Reading assembly descriptor: assemblies/bin.xml
[WARNING] The following patterns were never triggered in this artifact exclusion filter:
o  'test:module1:jar:javadoc'

[WARNING] The following patterns were never triggered in this artifact inclusion filter:
o  'test:module1:jar:javadoc'

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] : org.apache.maven.plugin.assembly.model.Assembly@139c27
Assembly is incorrectly configured: bin

Assembly: bin is not configured correctly: One or more filters had unmatched criteria. Check debug log for more information.
[INFO] ------------------------------------------------------------------------
[INFO] For more information, run Maven with the -e switch
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 12 seconds
[INFO] Finished at: Wed Oct 07 15:23:26 PDT 2009
[INFO] Final Memory: 26M/52M
[INFO] ------------------------------------------------------------------------

Я разместил этот проект для загрузки .

Ответы [ 3 ]

5 голосов
/ 08 октября 2009

Разобрался с решением, которое, кажется, работает (по крайней мере, в примере приложения, которое я разместил). Я изменил записи включения / исключения в файле сборки для подстановочного знака только типа, и теперь сборка ведет себя точно так, как ожидается. JAR-файл JavaDoc не помещается в каталог lib, а JavaDocs распаковывается, как предполагалось.

Файл окончательной сборки выглядит следующим образом: 

<assembly>
  <id>bin</id>
  <formats>
 <format>jar</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>

  <dependencySets>
    <dependencySet>
      <excludes>
        <!-- Exclude the Jars that are included in later sections -->
        <b><exclude>test:module1:*:javadoc</exclude></b>
      </excludes>
      <outputDirectory>lib</outputDirectory>
      <unpack>false</unpack>
      <useTransitiveDependencies>true</useTransitiveDependencies>
      <useTransitiveFiltering>false</useTransitiveFiltering>
      <useProjectArtifact>false</useProjectArtifact>
    </dependencySet>

    <dependencySet>
      <includes>
        <b><include>test:module1:*:javadoc</include></b>
      </includes>
      <outputDirectory>docs</outputDirectory>
      <unpack>true</unpack>
      <useTransitiveDependencies>true</useTransitiveDependencies>
      <useProjectArtifact>false</useProjectArtifact>
      <useStrictFiltering>true</useStrictFiltering>
    </dependencySet>
  </dependencySets>
</assembly>

Обновление: Некоторое быстрое тестирование показало, что тип Jar-файлов JavaDoc, по крайней мере, при ссылке на него из полной сборки, - это «javadoc». Однако, когда модуль пакета запускается автономно, этот тип не распознается и не может быть получен из локального репозитория. Таким образом, кажется, что для получения обоих режимов сборки (как части общей сборки, так и при сборке независимо) вам необходимо подстановочный знак типа для файлов Jar JavaDoc в сборке.

4 голосов
/ 08 октября 2009

Существует проблема с шаблоном идентификации test:module1:jar:javadoc, используемым для исключения и включения зависимостей в обоих <dependencySet>, как показано в трассировке ошибок сборки: 

[WARNING] The following patterns were never triggered in this artifact exclusion filter:
o  'test:module1:jar:javadoc'

[WARNING] The following patterns were never triggered in this artifact inclusion filter:
o  'test:module1:jar:javadoc'

Если честно, я не вижу, что не так с шаблоном test:module1:jar:javadoc: он соответствует формату groupId:artifactId:type[:classifier] и выглядит для меня абсолютно нормально (может ли это быть ошибкой?) Но дело в том, что он не соответствует какой-либо зависимости, и это вызывает две проблемы:

  1. банка javadoc не исключается и заканчивается в lib рядом с другой банкой,
  2. ничего не найдено для распаковки в docs, и это приводит к сбою сборки.

На самом деле, единственный способ, с помощью которого я нашел всю работу, - это использовать шаблон с подстановочным знаком (точнее *:javadoc). Ниже обновленный дескриптор сборки: 

<assembly>
  <id>bin</id>
  <formats>
    <format>jar</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>

  <dependencySets>
    <dependencySet>
      <excludes>
        <!-- Exclude the Jars that are included in later sections -->
        <exclude>*:javadoc</exclude>
      </excludes>
      <outputDirectory>lib</outputDirectory>
      <unpack>false</unpack>
      <useTransitiveDependencies>true</useTransitiveDependencies>
      <useTransitiveFiltering>false</useTransitiveFiltering>
      <useProjectArtifact>false</useProjectArtifact>
    </dependencySet>

    <dependencySet>
      <includes>
        <include>*:javadoc</include>
      </includes>
      <outputDirectory>docs</outputDirectory>
      <unpack>true</unpack>
      <useTransitiveDependencies>true</useTransitiveDependencies>
      <useProjectArtifact>false</useProjectArtifact>
      <useStrictFiltering>true</useStrictFiltering>
    </dependencySet>
  </dependencySets>
</assembly>

Не уверен, что этого будет достаточно, но, по крайней мере, он работает и дает ожидаемый результат.

3 голосов
/ 25 мая 2013

Мне удалось заставить его работать так: 

<?xml version="1.0" encoding="UTF-8"?>
<assembly>
<id>bundle</id>
<formats>
    <format>zip</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>

<moduleSets>
    <moduleSet>
        <!-- Collect JAR libraries -->
        <useAllReactorProjects>true</useAllReactorProjects>
        <binaries>
            <includeDependencies>true</includeDependencies>
            <outputDirectory>/</outputDirectory>
            <unpack>false</unpack>
        </binaries>
    </moduleSet>
    <moduleSet>
        <!-- Collect sources -->
        <useAllReactorProjects>true</useAllReactorProjects>
        <binaries>
            <includeDependencies>true</includeDependencies>
            <attachmentClassifier>sources</attachmentClassifier>
            <outputDirectory>/</outputDirectory>
            <unpack>false</unpack>
        </binaries>
    </moduleSet>
    <moduleSet>
        <!-- Collect javadoc -->
        <useAllReactorProjects>true</useAllReactorProjects>
        <binaries>
            <includeDependencies>true</includeDependencies>
            <attachmentClassifier>javadoc</attachmentClassifier>
            <outputDirectory>/</outputDirectory>
            <unpack>false</unpack>
        </binaries>
    </moduleSet>
</moduleSets>

В основном у меня есть модуль Set для JAR, другой для источников и другой для javadocs. Сборка производится в последнем модуле проекта. Надеюсь, это поможет.

...