< Previous Next >

Maven Tutorial

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.

Maven Assembly descriptor can be created and configured in two ways:

Pre-defined Descriptor Files
Write your own custom descriptor file

Pre-defined Descriptor Files

bin
jar-with-dependencies
src
project

bin

Use bin as the descriptorRef of your assembly-plugin configuration in order to create a binary distribution archive of your project. This built-in descriptor produces an assembly with the classifier bin in three archive formats: tar.gz, tar.bz2, and zip.

The assembled archive contains the binary JAR produced by running mvn package plus any README, LICENSE, and NOTICE files available in the project root directory.

Below is the bin descriptor format:

<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.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>

How to configure this plugin in pom.xml of your maven project?

<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.5.3</version>
<configuration>
 <descriptorRefs>
  <descriptorRef>bin</descriptorRef>
 </descriptorRefs>
</configuration>
 <executions>
  <execution>
   <id>create-archive</id>
   <phase>package</phase>
   <goals>
    <goal>single</goal>
   </goals>
  </execution>
 </executions>
</plugin>

jar-with-dependencies

Use jar-with-dependencies as the descriptorRef of your assembly-plugin configuration in order to create a JAR which contains the binary output of your project, along its the unpacked dependencies. This built-in descriptor produces an assembly with the classifier jar-with-dependencies using the JAR archive format.

Note that jar-with-dependencies provides only basic support for uber-jars. For more control, use the Maven Shade Plugin.

Below is the jar-with-dependencies descriptor format:

<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
  <!-- TODO: a jarjar format would be better -->
  <id>jar-with-dependencies</id>
  <formats>
    <format>jar</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/</outputDirectory>
      <useProjectArtifact>true</useProjectArtifact>
      <unpack>true</unpack>
      <scope>runtime</scope>
    </dependencySet>
  </dependencySets>
</assembly>

How to configure this plugin in pom.xml of your maven project?

<plugin>
 <artifactId>maven-assembly-plugin</artifactId>
 <version>2.5.3</version>
 <configuration>
  <descriptorRefs>
   <descriptorRef>jar-with-dependencies</descriptorRef>
  </descriptorRefs>
 </configuration>
 <executions>
  <execution>
   <id>create-archive</id>
   <phase>package</phase>
   <goals>
    <goal>single</goal>
   </goals>
  </execution>
 </executions>
</plugin>

src Use src as the descriptorRef in your assembly-plugin configuration to create source archives for your project. The archive will contain the contents of your project's /src directory structure, for reference by your users. The src descriptorId produces an assembly archive with the classifier src in three formats: tar.gz, tar.bz2, and zip.

Below is the src descriptor format:

<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
  <id>src</id>
  <formats>
    <format>tar.gz</format>
    <format>tar.bz2</format>
    <format>zip</format>
  </formats>
  <fileSets>
    <fileSet>
      <directory>${project.basedir}</directory>
      <includes>
        <include>README*</include>
        <include>LICENSE*</include>
        <include>NOTICE*</include>
        <include>pom.xml</include>
      </includes>
      <useDefaultExcludes>true</useDefaultExcludes>
    </fileSet>
    <fileSet>
      <directory>${project.basedir}/src</directory>
      <useDefaultExcludes>true</useDefaultExcludes>
    </fileSet>
  </fileSets>
</assembly>

How to use src as the descriptorRef in your assembly-plugin configuration in pom.xml?

<plugin>
 <artifactId>maven-assembly-plugin</artifactId>
 <version>2.5.3</version>
 <configuration>
  <descriptorRefs>
   <descriptorRef>src</descriptorRef>
  </descriptorRefs>
 </configuration>
 <executions>
  <execution>
   <id>create-archive</id>
   <phase>package</phase>
   <goals>
    <goal>single</goal>
   </goals>
  </execution>
 </executions>
</plugin>

project Using the project <descriptorRef> in your Assembly Plugin configuration will produce an assembly containing your entire project, minus any build output that lands in the /targetdirectory. The resulting assembly should allow your users to build your project using Maven, Ant, or whatever build system you have configured in your project's normal SCM working directory. It produces assemblies with the classifier project in three archive formats: tar.gz, tar.bz2, and zip.

The following is the assembly descriptor for the project descriptorRef:

<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
  <id>project</id>
  <formats>
    <format>tar.gz</format>
    <format>tar.bz2</format>
    <format>zip</format>
  </formats>
  <fileSets>
    <fileSet>
      <directory>${project.basedir}</directory>
      <outputDirectory>/</outputDirectory>
      <useDefaultExcludes>true</useDefaultExcludes>
      <excludes>
        <exclude>**/*.log</exclude>
        <exclude>**/${project.build.directory}/**</exclude>
      </excludes>
    </fileSet>
  </fileSets>
</assembly>

How to use project as the descriptorRef in your assembly-plugin configuration in pom.xml?

<plugin>
 <artifactId>maven-assembly-plugin</artifactId>
 <version>2.5.3</version>
 <configuration>
  <descriptorRefs>
   <descriptorRef>project</descriptorRef>
  </descriptorRefs>
 </configuration>
 <executions>
  <execution>
   <id>create-archive</id>
   <phase>package</phase>
   <goals>
    <goal>single</goal>
   </goals>
  </execution>
 </executions>
</plugin>

Currently it can create distributions in the following formats:

zip
tar
tar.gz (or tgz)
tar.bz2 (or tbz2)
tar.snappy
tar.xz (or txz)
jar
dir
war
and any other format that the ArchiveManager has been configured for

To use the Assembly Plugin in Maven, you simply need to:

choose or write the assembly descriptor to use,
configure the Assembly Plugin in your project's pom.xml, and
run "mvn assembly:single" on your project.

Write your own custom assembly

To write your own custom assembly, you will need to refer to the Assembly Descriptor Formatreference.

Guide to creating assemblies The assembly mechanism in Maven provides an easy way to create distributions using a assembly descriptor and dependency information found in you POM. In order to use the assembly plug-in you need to configure the assembly plug-in in your POM and it might look like the following:

<project>
  <parent>
    <artifactId>maven</artifactId>
    <groupId>org.apache.maven</groupId>
    <version>2.0-beta-3-SNAPSHOT</version>
  </parent>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.apache.maven</groupId>
  <artifactId>maven-embedder</artifactId>
  <name>Maven Embedder</name>
  <version>2.0-beta-3-SNAPSHOT</version>
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>2.5.3</version>
        <configuration>
          <descriptor>src/assembly/dep.xml</descriptor>
        </configuration>
        <executions>
          <execution>
            <id>create-archive</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

You'll notice that the assembly descriptor is located in ${project.basedir}/src/assembly which is the standard location for assembly descriptors.

The custom descriptor for dep.xml

<assembly 
  xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 
  http://maven.apache.org/xsd/assembly-1.1.2.xsd">
 
  <!-- TODO: a jarjar format would be better -->
  <id>dep</id>
  <formats>
    <format>jar</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <fileSets>
    <fileSet>
      <outputDirectory>/</outputDirectory>
    </fileSet>
  </fileSets>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/</outputDirectory>
      <unpack>true</unpack>
      <scope>runtime</scope>
      <excludes>
        <exclude>junit:junit</exclude>
        <exclude>commons-lang:commons-lang</exclude>
        <exclude>commons-logging:commons-logging</exclude>
        <exclude>commons-cli:commons-cli</exclude>
        <exclude>jsch:jsch</exclude>
        <exclude>org.apache.maven.wagon:wagon-ssh</exclude>
        <!-- TODO: can probably be removed now -->
        <exclude>plexus:plexus-container-default</exclude>
      </excludes>
    </dependencySet>
  </dependencySets>
</assembly>