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）:

Goal Description

assembly:single	Assemble an application bundle or distribution from an assembly descriptor. This goal is suitable either for binding to the lifecycle or calling directly from the command line (provided all required files are available before the build starts, or are produced by another goal specified before this one on the command line).

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>