Apache Maven Assembly Plugin

Usage

To handle filtering this version of Maven Assembly Plugin uses Maven Filtering 3.3.1.

To handle archiving this version of Maven Assembly Plugin uses Maven Archiver 3.6.1.

This document is intended to provide instructions for using the maven-assembly-plugin. In order for this discussion to be useful, it's critical to cover two topics: configuration of the plugin - both inside the POM and, where possible, from the command line - and the different execution styles. For the sake of clarity, we'll cover configuration before execution.

Configuration

Getting started with the Assembly Plugin is pretty simple. If you want to use one of the prefabricated assembly descriptors, you configure which descriptor to use with the <descriptorRefs>/<descriptorRef> parameter. If you want to use a custom assembly descriptor, you configure the path to your descriptor using the <descriptors>/<descriptor> parameter.

Note that a single invocation of the Assembly Plugin can actually produce assemblies from multiple descriptors, allowing you maximum flexibility to customize the suite of binaries your project produces. When the assembly is created it will use the assemblyId as the artifact's classifier and will attach the created assembly to the project so that it will be uploaded into the repository in the install and deploy phase.

For example, imagine that our project produces a JAR. If we want to create an assembly binary that includes our project's dependencies, we can take advantage of one of the Assembly Plugin's prefabricated descriptors. You configure it as follows in your project's pom.xml:

<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <!-- NOTE: We don't need a groupId specification because the group is
             org.apache.maven.plugins ...which is assumed by default.
         -->
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.7.0</version>
        <configuration>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
        </configuration>
        [...]
</project>

Note that the Assembly Plugin allows you to specify multiple descriptorRefs at once, to produce multiple types of assemblies in a single invocation.

Alternatively, we've created a custom assembly descriptor called src.xml in the src/assembly directory (see the Resources section for more information). We can tell the Assembly Plugin to use that instead:

<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.7.0</version>
        <configuration>
          <descriptors>
            <descriptor>src/assembly/src.xml</descriptor>
          </descriptors>
        </configuration>
        [...]
</project>

Again, note that we could specify multiple custom assembly descriptors here. Additionally, it's possible to specify a mixture of descriptors and descriptorRefs within the same configuration.

Note: Many other configuration options are available for the various goals in the Assembly Plugin. For more information, see the examples section or the plugin parameter documentation.

Execution: Building an Assembly

Once you've configured the various descriptors and descriptorRefs for the assemblies you want the project to produce, it's time to build them.

In most cases, you'll want to make sure your assemblies are created as part of your normal build process. This ensures the assembly archives are made available for installation and deployment, and that they are created during the release of your project. This is handled by the assembly:single goal.

To bind the single goal to a project's build lifecycle, you can add this configuration (assuming you're using the jar-with-dependencies prefabricated descriptor):

<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.7.0</version>
        <configuration>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
        </configuration>
        <executions>
          <execution>
            <id>make-assembly</id> <!-- this is used for inheritance merges -->
            <phase>package</phase> <!-- bind to the packaging phase -->
            <goals>
              <goal>single</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      [...]
</project>

Then, to create a project assembly, simple execute the normal package phase from the default lifecycle:

mvn package

When this build completes, you should see a file in the target directory with a name similar to the following:

target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar

Notice the artifact classifier, between the end of the version and the beginning of the file extension, jar-with-dependencies. This is the id of the assembly descriptor used to create this artifact.

GOTCHA!

In most cases, the single goal should be bound to the package phase of the build. However, if your assembly doesn't require binaries, or if you need to use one assembly as input for another, you may need to change this. While it's possible to assign the single goal to any phase of the build lifecycle, you should be careful to make sure the resources included in your assembly exist before that assembly is created.

Advanced Configuration

Creating an Executable JAR

As you've no doubt noticed, the Assembly Plugin can be a very useful way to create a self-contained binary artifact for your project, among many other things. However, once you've created this self-contained JAR, you will probably want the ability to execute it using the -jar JVM switch.

To accommodate this, the Assembly Plugin supports configuration of an <archive> element which is handled by maven-archiver (see Resources). Using this configuration, it's easy to configure the Main-Class attribute of the JAR manifest:

<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.7.0</version>
        <configuration>
          [...]
          <archive>
            <manifest>
              <mainClass>org.sample.App</mainClass>
            </manifest>
          </archive>
        </configuration>
        [...]
      </plugin>
      [...]
</project>

If we add this configuration to the single goal example above and rebuild, we will see an entry like this in the META-INF/MANIFEST.MF file of the resulting JAR:

[...]
Main-Class: org.sample.App

For more information on advanced configuration for the Assembly Plugin, see the Resources section.

GOTCHA!

At this point, only the jar and war assembly formats support the <archive> configuration element.

Resources

For more information on writing your own assembly descriptor, read the Assembly Descriptor
For more information about maven-archiver, look here.
For more information on advanced maven-assembly-plugin configuration, see the examples.