Usage of the assembly:assembly, assembly:attached, assembly:directory, and assembly:directory-inline are DEPRECATED, since they wreak havoc with normal build processes and promote non-standard build practices.
Additionally, the assembly:single-directory mojo is redundant, and has been deprecated in favor of the dir assembly format.
Finally, the assembly:unpack mojo has been deprecated in favor of the far more comprehensive Maven Dependency Plugin.
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.
Getting started with the Assembly Plugin is pretty simple. If you're using one of the prefabricated assembly descriptors, you just tell it which one; if you're using a custom assembly descriptor, you give it the path to the descriptor. 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 and will be uploaded into the repository on an install and deploy goal.
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, as follows:
<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>2.2</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/main/assembly directory (see the Resources section for more information), we can tell the Assembly Plugin to use it instead:
<project> [...] <build> [...] <plugins> <plugin> <artifactId>maven-assembly-plugin</artifactId> <version>2.2</version> <configuration> <descriptors> <descriptor>src/main/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.
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 mojo.
To bind the single mojo 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>2.2</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> <!-- append to the packaging phase. --> <goals> <goal>single</goal> <!-- goals == mojos --> </goals> </execution> </executions> </plugin> [...] </project>
Then, to create a project assembly, simple execute the normal package phase from the default lifecycle:
When this build completes, you should see a file in the target directory with a name similar to the following:
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.
In most cases, the single mojo 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 mojo 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.
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 identical to that supported by the maven-jar-plugin (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>2.2</version> <configuration> [...] <archive> <manifest> <mainClass>org.sample.App</mainClass> </manifest> </archive> </configuration> [...] </plugin> [...] </project>
If we add this configuration to the single mojo 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.