---
Configuration and Usage
---
John Casey
---
2 November 2006
~~ Copyright 2006 The Apache Software Foundation.
~~
~~ Licensed under the Apache License, Version 2.0 (the "License");
~~ you may not use this file except in compliance with the License.
~~ You may obtain a copy of the License at
~~
~~ http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing, software
~~ distributed under the License is distributed on an "AS IS" BASIS,
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~ See the License for the specific language governing permissions and
~~ limitations under the License.
~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/guides/mini/guide-apt-format.html
Configuration and Usage
* Introduction
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.
* Configuring the Assembly Plugin
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:
+---+
[...]
[...]
maven-assembly-plugin
jar-with-dependencies
[...]
+---+
Note that the Assembly Plugin allows you to specify multiple
<<>> at once, to produce multiple types of assemblies in a
single invocation.
Alternatively, we've created a custom assembly descriptor called
<<>> in the <<>> directory (see the
{{{#Resources}Resources}} section for more information), we can tell the
Assembly Plugin to use it instead:
+---+
[...]
[...]
maven-assembly-plugin
src/main/assembly/src.xml
[...]
+---+
Again, note that we could specify multiple custom assembly descriptors here.
Additionally, it's possible to specify a mixture of <<>> and
<<>> within the same configuration.
<> Many other configuration options are available for the various mojos
in the Assembly Plugin. For more information, see the
{{{examples/index.html}examples section}} or the {{{plugin-info.html}plugin
parameter documentation}}.
* Executing: Building an Assembly
Once you've configured the various <<>> and <<>>
for the assemblies you want the project to produce, it's time to determine how
you want to build them.
Currently, there are two basic approaches to building assemblies: as a
dedicated build action, or bound to a phase of the normal build lifecycle.
Beyond this, it's also possible to have the Assembly Plugin simply create an
assembly directory for any given <<>> or <<>>,
instead of creating archives.
** Building an Assembly as a Standalone Process
First, let's examine how we can build an assembly directly, as a process
separate from the normal build lifecycle. In this case, assemblies won't be
produced when the normal build is executed, only in special circumstances.
<> Invoking the <<>> and <<>> mojos will cause
Maven to build the project using the normal lifecycle, up to the <<>>
phase. Because many assemblies will contain compiled classes and other
binaries, it's reasonable to assume that the package phase will be required to
ensure those binaries exist and have been tested. The main advantage of
producing an assembly in this way is to avoid producing it as part of your
normal build process. In some cases, you may only want to create an assembly
periodically; these mojos provide two ways to accomplish that goal.
*** Normal Assemblies
You can build an assembly directly by executing:
+---+
mvn assembly:assembly
+---+
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, <<>>. This is the
<<>> of the assembly descriptor used to create this artifact.
*** Assembly Directories
You can construct an assembly directory directly from the command line by
executing:
+---+
mvn assembly:directory
+---+
When completed, you should see a directory structure similar to this:
+---+
target
|-- sample-1.0-SNAPSHOT-jar-with-dependencies
| |-- META-INF
| | |-- MANIFEST.MF
| | `-- maven
| | `-- org.sample
| | `-- sample
| | |-- pom.properties
| | `-- pom.xml
| |-- junit
[...]
| | `-- TestRunner.class
| |-- junit3.8.1
| |-- org
| | `-- sample
| | `-- App.class
| `-- stylesheet.css
+---+
** Building an Assembly as Part of the Build Lifecycle
If you need to ensure that assemblies are produced whenever your project
builds, or when a particular profile is activated (also useful for configuring
other plugins during this special process), then the following two mojos are
probably what you're looking for. The <<>> and
<<>> mojos are functional counterparts of the mojos
discussed above, except that they are meant to bind into the default build
lifecycle.
The <<>> mojo forces a <<>> phase build to execute, in
order to guarantee the availability of project binaries. Unfortunately, this
currently means that binding the <<>> mojo to the default lifecycle
will cause Maven to execute the build twice - once for the main process, and
once again in a forked lifecycle which is spawned by the <<>> mojo
itself.
By contrast, the <<>> mojo assumes that the build has already
produced project binaries or whatever else it needs prior to building the
assembly itself. Because they depend on correct binding to the lifecycle in
order to gain access to the files required by your project assembly, the
<<>> and <<>> mojos require the user to have much
more intimate knowledge of the build process.
*** Normal Assemblies
To bind the <<>> mojo to a project's build lifecycle, you can add
this configuration (assuming you're using the <<>>
prefabricated descriptor):
+---+
[...]
[...]
maven-assembly-plugin
jar-with-dependencies
make-assembly
package
attached
[...]
+---+
Then, to create a project assembly, simple execute the normal <<>>
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, <<>>. This is the
<<>> of the assembly descriptor used to create this artifact.
*** Assembly Directories
If instead you want to bind the <<>> mojo to a project's
build lifecycle - so you can construct a directory containing your assembly -
you can add this configuration (assuming you're using the
<<>> prefabricated descriptor):
+---+
[...]
[...]
maven-assembly-plugin
jar-with-dependencies
make-assembly
package
directory-inline
[...]
+---+
Then, to create a project assembly, simple execute the normal <<>>
phase from the default lifecycle:
+---+
mvn package
+---+
When completed, you should see a directory structure similar to this:
+---+
target
|-- sample-1.0-SNAPSHOT-jar-with-dependencies
| |-- META-INF
| | |-- MANIFEST.MF
| | `-- maven
| | `-- org.sample
| | `-- sample
| | |-- pom.properties
| | `-- pom.xml
| |-- junit
[...]
| | `-- TestRunner.class
| |-- junit3.8.1
| |-- org
| | `-- sample
| | `-- App.class
| `-- stylesheet.css
+---+
* Advanced Configuration
** Creating Assemblies from Multiple Projects in a Multimodule Build
In certain cases, you may need to create several assembly archives from
different points in a multimodule build. For this reason, two new assembly
mojos have been introduced: <<>>, and
<<>>. These mojos will perform the usual tasks
associated with creating assembly archives or directories, without running in
a once-per-build mode. However, it's important to note that the use of the
<<<\>>> section in the assembly descriptor may be limited in
these cases, since the assembly mojo will not have access to the full list of
projects in the current build. See the examples entry in the
{{{#Resources}Resources}} section below for more information.
** 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
<<<\>>> element which is identical to that supported by the
<<>> (see {{{#Resources}Resources}}). Using this
configuration, it's easy to configure the <<>> attribute of the
jar manifest:
+---+
[...]
[...]
maven-assembly-plugin
[...]
org.sample.App
[...]
[...]
+---+
If we add this configuration to the <<>> 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}Resources}} section.
** GOTCHA!
At this point, only the <<>> assembly format supports the <<<\>>>
configuration element. By definition, directory-based assembly mojos -
<<>>, <<>>, and
<<>> - do not produce a jar-format archive, and
therefore do not support the <<<\>>> element.
* {Resources}
[[1]] For more information on writing your own assembly descriptor, read the
{{{assembly.html}Assembly Descriptor}}
[[2]] For more information about the <<>>, look
{{{http://maven.apache.org/plugins/maven-jar-plugin/}here}}.
[[3]] For more information on advanced <<>>
configuration, see the {{{examples/index.html}examples}}.
[]