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:

  1. <project>
  2.   <parent>
  3.     <artifactId>maven</artifactId>
  4.     <groupId>org.apache.maven</groupId>
  5.     <version>2.0-beta-3-SNAPSHOT</version>
  6.   </parent>
  7.   <modelVersion>4.0.0</modelVersion>
  8.   <groupId>org.apache.maven</groupId>
  9.   <artifactId>maven-embedder</artifactId>
  10.   <name>Maven Embedder</name>
  11.   <version>2.0-beta-3-SNAPSHOT</version>
  12.   <build>
  13.     <plugins>
  14.       <plugin>
  15.         <artifactId>maven-assembly-plugin</artifactId>
  16.         <version>2.5.3</version>
  17.         <configuration>
  18.           <descriptor>src/assembly/dep.xml</descriptor>
  19.         </configuration>
  20.         <executions>
  21.           <execution>
  22.             <id>create-archive</id>
  23.             <phase>package</phase>
  24.             <goals>
  25.               <goal>single</goal>
  26.             </goals>
  27.           </execution>
  28.         </executions>
  29.       </plugin>
  30.     </plugins>
  31.   </build>
  32.   ...
  33. </project>

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

Creating a binary assembly

This is the most typical usage of the assembly plugin where you are creating a distribution for standard use.

  1. <assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" 
  2.   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  3.   xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
  4.   <id>bin</id>
  5.   <formats>
  6.     <format>tar.gz</format>
  7.     <format>tar.bz2</format>
  8.     <format>zip</format>
  9.   </formats>
  10.   <fileSets>
  11.     <fileSet>
  12.       <directory>${project.basedir}</directory>
  13.       <outputDirectory>/</outputDirectory>
  14.       <includes>
  15.         <include>README*</include>
  16.         <include>LICENSE*</include>
  17.         <include>NOTICE*</include>
  18.       </includes>
  19.     </fileSet>
  20.     <fileSet>
  21.       <directory>${project.build.directory}</directory>
  22.       <outputDirectory>/</outputDirectory>
  23.       <includes>
  24.         <include>*.jar</include>
  25.       </includes>
  26.     </fileSet>
  27.     <fileSet>
  28.       <directory>${project.build.directory}/site</directory>
  29.       <outputDirectory>docs</outputDirectory>
  30.     </fileSet>
  31.   </fileSets>
  32. </assembly>

You can use a manually defined assembly descriptor as mentioned before but it is simpler to use the pre-defined assembly descriptor bin in such cases.

How to use such pre-defined assembly descriptors is described in the documentation of maven-assembly-plugin.

  1. <assembly 
  2.   xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" 
  3.   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4.   xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 
  5.   http://maven.apache.org/xsd/assembly-1.1.2.xsd">
  6.  
  7.   <!-- TODO: a jarjar format would be better -->
  8.   <id>dep</id>
  9.   <formats>
  10.     <format>jar</format>
  11.   </formats>
  12.   <includeBaseDirectory>false</includeBaseDirectory>
  13.   <fileSets>
  14.     <fileSet>
  15.       <outputDirectory>/</outputDirectory>
  16.     </fileSet>
  17.   </fileSets>
  18.   <dependencySets>
  19.     <dependencySet>
  20.       <outputDirectory>/</outputDirectory>
  21.       <unpack>true</unpack>
  22.       <scope>runtime</scope>
  23.       <excludes>
  24.         <exclude>junit:junit</exclude>
  25.         <exclude>commons-lang:commons-lang</exclude>
  26.         <exclude>commons-logging:commons-logging</exclude>
  27.         <exclude>commons-cli:commons-cli</exclude>
  28.         <exclude>jsch:jsch</exclude>
  29.         <exclude>org.apache.maven.wagon:wagon-ssh</exclude>
  30.         <!-- TODO: can probably be removed now -->
  31.         <exclude>plexus:plexus-container-default</exclude>
  32.       </excludes>
  33.     </dependencySet>
  34.   </dependencySets>
  35. </assembly>

If you like to create a source distribution package the best solution is to use the pre-defined assembly descriptor src for such purposes.

  1. <assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" 
  2.   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  3.   xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
  4.   <id>src</id>
  5.   <formats>
  6.     <format>tar.gz</format>
  7.     <format>tar.bz2</format>
  8.     <format>zip</format>
  9.   </formats>
  10.   <fileSets>
  11.     <fileSet>
  12.       <directory>${project.basedir}</directory>
  13.       <includes>
  14.         <include>README*</include>
  15.         <include>LICENSE*</include>
  16.         <include>NOTICE*</include>
  17.         <include>pom.xml</include>
  18.       </includes>
  19.       <useDefaultExcludes>true</useDefaultExcludes>
  20.     </fileSet>
  21.     <fileSet>
  22.       <directory>${project.build.sourceDirectory}/src</directory>
  23.       <useDefaultExcludes>true</useDefaultExcludes>
  24.     </fileSet>
  25.   </fileSets>
  26. </assembly>

You can now create the defined distribution packages via command line like this:

  1. mvn package