8.4. The Assembly Descriptor
This section is a tour of the assembly descriptor which contains some
guidelines for developing a custom assembly descriptor. The Assembly
plugin is one of the largest plugins in the Maven ensemble, and one of
the most flexible.
8.4.1. Property References in Assembly Descriptors
Any property discussed in Section 9.2, “Maven Properties” can
be referenced in an assembly descriptor. Before any assembly
descriptor is used by Maven, it is interpolated using information from
the POM and the current build environment. All properties supported
for interpolation within the POM itself are valid for use in assembly
descriptors, including POM properties, POM element values, system
properties, user-defined properties, and operating-system environment
variables.
The only exceptions to this interpolation step are elements in various
sections of the descriptor named outputDirectory
,
outputDirectoryMapping
, or outputFileNameMapping
. The reason these
are held back in their raw form is to allow artifact- or
module-specific information to be applied when resolving expressions
in these values, on a per-item basis. <!--This last paragraph is not
clear.-→
8.4.2. Required Assembly Information
There are two essential pieces of information that are required for
every assembly: the id
, and the list of archive formats to
produce. In practice, at least one other section of the descriptor is
required - since most archive format components will choke if they
don’t have at least one file to include - but without at least one
format
and an id
, there is no archive to create. The id
is used
both in the archive’s file name, and as part of the archive’s artifact
classifier in the Maven repository. The format string also controls
the archiver-component instance that will create the final assembly
archive. All assembly descriptors must contain an id
and at least
one format
:
Required Assembly Descriptor Elements.
<assembly>
<id>bundle</id>
<formats>
<format>zip</format>
</formats>
...
</assembly>
The assembly id
can be any string that does not contain spaces. The
standard practice is to use dashes when you must separate words within
the assembly id
. If you were creating an assembly to create an
interesting unique package structure, you would give your an id
of
something like interesting-unique-package
. It also supports multiple
formats within a single assembly descriptor, allowing you to create
the familiar .zip, .tar.gz, and .tar.bz2 distribution archive
set with ease. If you don’t find the archive format you need, you can
also create a custom format. Custom formats are discussed in
Section 8.5.8, “componentDescriptors
and”. The Assembly plugin supports
several archive formats natively, including:
-
jar
-
zip
-
tar
-
bzip2
-
gzip
-
tar.gz
-
tar.bz2
-
rar
-
war
-
ear
-
sar
-
dir
The id
and format
are essential because they will become a part of
the coordinates for the assembled archive. The example from
Required Assembly Descriptor Elements will create an assembly artifact of type
zip
with a classifier of bundle
.