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.5.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.5.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.5.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.

Advanced Configuration

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

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

Resources

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