Maven: The Complete Reference

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.