maven-assembly-plugin的使用

maven-assembly-plugin使用描述(拷自 maven-assembly-plugin 主頁)

The Assembly Plugin for Maven is primarily intended to allow users to aggregate the project output along with its dependencies, modules, site documentation, and other files into a single distributable archive.

目前它只有一個有意義的goal， 詳細的請看（http://maven.apache.org/plugins/maven-assembly-plugin/plugin-info.html）:

assembly:single

single操作有很多可配置的參數，詳細的請看（http://maven.apache.org/plugins/maven-assembly-plugin/single-mojo.html）。

簡單的說，maven-assembly-plugin 就是用來幫助打包用的，比如說打出一個什么類型的包，包里包括哪些內容等等。
目前至少支持以下打包類型：

• zip
• tar
• tar.gz
• tar.bz2
• jar
• dir
• war

默認情況下，打jar包時，只有在類路徑上的文件資源會被打包到jar中，並且文件名是${artifactId}-${version}.jar，下面看看怎么用maven-assembly-plugin插件來定制化打包。

首先需要添加插件聲明：

<plugin>  
    <groupId>org.apache.maven.plugins</groupId>  
    <artifactId>maven-assembly-plugin</artifactId>  
    <version>2.4</version>  
    <executions>  
        <execution>  
            <phase>package</phase>  
            <goals>  
                <goal>single</goal>  
            </goals>  
        </execution>  
    </executions>  
</plugin>  

 

使用內置的Assembly Descriptor

要使用maven-assembly-plugin，需要指定至少一個要使用的assembly descriptor 文件，對於當前使用的版本(2.4)對應的assembly descriptor的schema定義為：Assembly Schema ，其中assembly descriptor中又可以包括 component 的定義 (component 可以很方便的用於多個assembly descriptor之間共享)，component 的schema 定義在：Component Schema 。 關於assembly descriptor的component descriptor的更詳細的說明，請見：Component Descriptor 和 Assembly Descriptor 。

默認情況下，maven-assembly-plugin內置了幾個可以用的assembly descriptor：

• bin ： 類似於默認打包，會將bin目錄下的文件打到包中
• jar-with-dependencies ： 會將所有依賴都解壓打包到生成物中
• src ：只將源碼目錄下的文件打包
• project ： 將整個project資源打包

要查看它們的詳細定義，可以到maven-assembly-plugin-2.4.jar里去看，例如對應 bin 的assembly descriptor 如下：

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"   
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">  
  <id>bin</id>  
  <formats>  
    <format>tar.gz</format>  
    <format>tar.bz2</format>  
    <format>zip</format>  
  </formats>  
  <fileSets>  
    <fileSet>  
      <directory>${project.basedir}</directory>  
      <outputDirectory>/</outputDirectory>  
      <includes>  
        <include>README*</include>  
        <include>LICENSE*</include>  
        <include>NOTICE*</include>  
      </includes>  
    </fileSet>  
    <fileSet>  
      <directory>${project.build.directory}</directory>  
      <outputDirectory>/</outputDirectory>  
      <includes>  
        <include>*.jar</include>  
      </includes>  
    </fileSet>  
    <fileSet>  
      <directory>${project.build.directory}/site</directory>  
      <outputDirectory>docs</outputDirectory>  
    </fileSet>  
  </fileSets>  
</assembly>

 

自定義Assembly Descriptor

一般來說，內置的assembly descriptor都不滿足需求，這個時候就需要寫自己的assembly descriptor的實現了。先從一個最簡單的定義開始：

<?xml version='1.0' encoding='UTF-8'?>  
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"  
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0  
                    http://maven.apache.org/xsd/assembly-1.1.0.xsd">  
    <id>demo</id>  
    <formats>  
        <format>jar</format>  
    </formats>  
    <includeBaseDirectory>false</includeBaseDirectory>  
    <fileSets>  
        <fileSet>  
            <directory>${project.build.directory}/classes</directory>  
            <outputDirectory>/</outputDirectory>  
        </fileSet>  
    </fileSets>  
</assembly>

 

這個定義很簡單：

• format：指定打包類型
• includeBaseDirectory：指定是否包含打包層目錄（比如finalName是output，當值為true，所有文件被放在output目錄下，否則直接放在包的根目錄下）
• fileSets：指定要包含的文件集，可以定義多個fileSet
• directory：指定要包含的目錄
• outputDirectory：指定當前要包含的目錄的目的地
  要使用這個assembly descriptor，需要如下配置：

<configuration>  
    <finalName>demo</finalName>  
    <descriptors>  
        <descriptor>assemblies/demo.xml</descriptor>  
    </descriptors>  
    <outputDirectory>output</outputDirectory>  
</configuration> 

 

最后會生成一個demo-demo.jar 文件在目錄 output 下，其中前一個demo來自finalName，后一個demo來自assembly descriptor中的id，其中的內容和默認的打包出來的jar類似。

如果只想有finalName，則增加配置：

<appendAssemblyId>false</appendAssemblyId>  

 

添加文件

上面演示了添加所有編譯后的資源，同樣的可以增加其他資源，例如想添加當前工程目錄下的某個文件 b.txt ，在assembly descriptor的assembly結點下增加

<files>  
    <file>  
        <source>b.txt</source>  
        <outputDirectory>/</outputDirectory>  
    </file>  
</files>

 

這里用到了 files 元素類型，可以想象 fileSets 下的結點都是針對文件夾的；files 下的結點都是針對文件的。

也可以改變打包后的文件名，例如上面的 b.txt ，希望打包后的名字為 b.txt.bak， 只需要在file 里添加以下配置 ：

<destName>b.txt.bak</destName>  

 

排除文件

在fileSet里可以使用includes 和 excludes來更精確的控制哪些文件要添加，哪些文件要排除。
例如要排除某個目錄下所有的txt文件：

<fileSet>  
    <directory>${project.build.directory}/classes</directory>  
    <outputDirectory>/</outputDirectory>  
    <excludes>  
        <exclude>**/*.txt</exclude>  
    </excludes>  
</fileSet>

 

或者某個目錄下只想 .class 文件：

<fileSet>  
    <directory>${project.build.directory}/classes</directory>  
    <outputDirectory>/</outputDirectory>  
    <includes>  
        <include>**/*.class</include>  
    </includes>  
</fileSet>

 

添加依賴

如果想把一些依賴庫打到包里，可以用 dependencySets 元素，例如最簡單的，把當前工程的所有依賴都添加到包里：

<dependencySets>  
    <dependencySet>  
        <outputDirectory>/</outputDirectory>  
    </dependencySet>  
</dependencySets>

 

在assembly下添加以上配置，則當前工程的依賴和工程本身生成的jar都會被打包進來。

如果要排除工程自身生成的jar，則可以添加

<useProjectArtifact>false</useProjectArtifact>

 

unpack參數可以控制依賴包是否在打包進來時是否解開，例如解開所有包，添加以下配置：

<unpack>true</unpack>  

 

和 fileSet 一樣，可以使用 excludes 和 includes 來更詳細的控制哪些依賴需要打包進來；另外 useProjectAttachments，useTransitiveDependencies，useTransitiveFiltering等參數可以對間接依賴、傳遞依賴進行控制。

其他選項

• moduleSets：當有子模塊時候用
• repositories：想包含庫的時候用
• containerDescriptorHandlers：可以進行一些合並，定義ArtifactHandler之類的時候可以用，（可以參考：說明 ）
• componentDescriptors：如上所述，可以包含一些componentDescriptor定義，這些定義可以被多個assembly共享

Assembly Plugin更多配置

上面已經看到了一些Assembly Plugin本身的配置，例如 finalName， outputDirectory， appendAssemblyId和descriptors等，除了這些還有其他的一些可配置參數，參見：single，其中某些參數會覆蓋在assembly descriptor中的參數。有一個比較有用的參數是： archive，它的詳細配置在：archive。
下面介紹一些archive的用法。

指定Main-Class

archive的一個重要用處就是配置生成的MANIFEST.MF文件。默認會生成一個MANIFEST.MF文件，不過這個文件默認值沒什么意義。如果想指定生成jar的Main-Class，可以如下配置：

<archive>  
    <manifest>  
        <mainClass>demo.DemoMain</mainClass>  
    </manifest>  
</archive>

 

添加MANIFEST項

除了可以指定Main-Class外，還可以添加任意項。比如在OSGI bundle的MANIFEST.MF定義里就有很多用來定義bundle的屬性的項，如Import-Package，Export-Package等等。要添加項，可以使用如下配置：

<archive>  
    <manifestEntries>  
        <Import-Package>javax.xml.ws.*</Import-Package>  
    </manifestEntries>  
</archive> 

 

指定MANIFEST.MF文件

還可以直接指定MANIFEST.MF文件。如下：

<archive>  
    <manifestFile>META-INF/MANIFEST.MF</manifestFile>  
</archive>

 

---

 -END-