Maven assembly Plugin
External
- The Assembly Plugin http://maven.apache.org/plugins/maven-assembly-plugin
- Assembly Plugin Usage http://maven.apache.org/components/plugins/maven-assembly-plugin/usage.html
Internal
Overview
The assembly plugin provide a standard way to aggregate complex artifacts out of project modules' artifacts, dependencies, documentation and arbitrary files. The plugin produces a single distributable archive. A module has only one artifact - usually a JAR - but we may want to distribute that JAR together with documentation, source and supporting scripts in the form or an "atomic" archive, usually created for an official release. The assembly plugin does that.
Concepts
Assembly
An assembly is an single artifact produced by aggregating artifacts produced by modules, dependencies, documentation and arbitrary files. The assembly is built according to a specification formalized in the assembly descriptor.
Assembly ID
The assembly ID will become the assembly artifact classifier, present between the version and the extension.
Arbitrary Assembly File Name
The following configuration can be used to generate an assembly file with an arbitrary name. Properties such a ${project.version} are resolved correctly:
<configuration>
<finalName>example-${project.version}</finalName>
...
</configuration>
For more details about the plugin configuration, see "Plugin Configuration" section, below.
Assembly Descriptor
An assembly descriptor specifies the type of assembly archive to create, the contents of the assembly, and the ways in which dependencies or its modules are bundled with an assembly. It can also contain instructions to set specific permissions, etc.
Maven offers a set of predefined assembly descriptors, described below. Custom assembly descriptors can also be created, and this is the reference documentation for a custom assembly descriptor:
Custom assembly descriptors are conventionally placed under src/assembly.
Pre-defined Assembly Descriptors
bin
The assembled archive produced by this descriptor contains the binary JAR produced by running mvn package plus any README, LICENSE, and NOTICE files available in the project root directory. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#bin.
jar-with-dependencies
The assembled archive produced by this descriptor is a JAR which contains the binary output of your project, along its the unpacked dependencies. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#jar-with-dependencies
src
The assembled archive produced by this descriptor is the source archives for the project. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#src
project
The assembled archive produced by this descriptor is the entire project, minus any build output that lands in the /target directory. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#project
Plugin Configuration
<project>
...
<build>
<plugins>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>...</version>
<configuration>
<descriptorRefs>
<descriptorRef>jar-with-dependencies</descriptorRef>
</descriptorRefs>
</configuration>
</plugin>
</plugins>
...
</project>
Use <descriptorRefs> (one or more) when the pre-defined assembly descriptors are sufficient. For a list of available pre-defined assembly descriptors, see "Pre-defined Assembly Descriptors" section. In case a custom assembly descriptor is needed, it is declared as follows:
...
<configuration>
<descriptors>
<descriptor>src/assembly/release-artifact.xml</descriptor>
</descriptors>
</configuration>
...
Plugin Execution
The plugin has a single goal "single". The assembly plugin can be executed in isolation, or it can be executed during the build process of the project.
To execute the plugin in isolation:
mvn assembly:single
To execute the plugin as part of the build process, the plugin has to be first declared and configured, as described in the "Plugin Configuration" section, and then its "single" goal must be bound to the project lifecycle by associating it usually with the "package" phase, as follows:
<project>
...
<build>
<plugins>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>...</version>
<configuration>
...
</configuration>
<executions>
<execution>
<id>assembly-execution</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
...
</project>
Once the plug-in is bound to the project lifecycle, simply execute the normal package phase from the default lifecycle to create a project assembly:
mvn package
When this build completes, the assembly file is available in the target directory and has a name similar to the following: Put placeholders: target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar .
In case the assembly doesn't require binaries, so the package phase does not need to be executed, the assembly's goal can be bound to a different project phase. You should be careful to make sure the resources included in your assembly exist before that assembly is created.
The "single" Goal
More details available here: http://maven.apache.org/components/plugins/maven-assembly-plugin/single-mojo.html
Other Assembly Use Cases
!!!Create an assembly file without any suffix
By default, the assembly name is the <projectname>-<assemblyid>.<ext> If I just want it to be <projectname>.<ext>, don't use any {{{
<id>...</id>
}}} in the assembly descriptor.
!!!Creating two assemblies for the same project
{{{ <plugin>
<artifactId>maven-assembly-plugin</artifactId>
<executions>
<execution>
<id>jar-with-all-dependencies</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
<configuration>
<descriptors>
<descriptor>src/main/assembly/jar-with-all-dependencies.xml</descriptor>
</descriptors>
<archive>
<manifest>
<mainClass>${exec.main.class}</mainClass>
</manifest>
</archive>
</configuration>
</execution>
<execution>
<id>distribution-bundle</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
<configuration>
<descriptors>
<descriptor>src/main/assembly/distribution-bundle.xml</descriptor>
</descriptors>
</configuration>
</execution>
</executions>
</plugin>
}}}