Custom Maven Assembly Descriptors

External

• Custom assembly descriptor reference http://maven.apache.org/components/plugins/maven-assembly-plugin/assembly.html

Internal

• Maven assembly Plugin

Overview

Aside from pre-defined assembly descriptors, Maven allows creation of custom assembly descriptors. Custom assembly descriptors are conventionally placed under src/assembly of the module that executes the plugin.

Assembly Descriptors and System Properties

Maven resolves system properties referred from values specified in the assembly descriptors. This helps with enforcing the pattern where module versions are specified in only one place - the parent project pom.xml. For more details, see "Multi-module maven projects versioning" section.

Example

This is an example of a custom assembly descriptor, used to build a complex release artifact for a multi-module project:

https://github.com/NovaOrdis/events/blob/master/release/src/assembly/release.xml

Elements

<id>

The <id> element in the assembly descriptor specifies the value of the assembly ID. The presence of the <id> element in the assembly descriptor is mandatory, if it is not specified, Maven will generate a parsing error. The assembly ID will become the assembly artifact classifier, present between the version and the extension. For more details on assembly artifact naming rules, see "The Name of the Assembly Artifact" section.

<format>

<formats>
    <format>zip</format>
</formats>

Multiple formats can be provided, and the plugin will generate an archive for each of them.

Archive Base Directory

The plugin is capable of creating an archive with an embedded base directory. This is useful for binaries distributions, to prevent a situation when unziping will "taint" a current directory, by placing unexpected files in it.

<includeBaseDirectory>true</includeBaseDirectory> will trigger the feature. If no <baseDirectory> is explicitly specified, ${project.build.finalName} will be used by default, otherwise the value of the base directory can be customized. <includeBaseDirectory>true</includeBaseDirectory> with no explicit <baseDirectory> is a good default.

Module Sets

• External: https://maven.apache.org/plugins/maven-assembly-plugin/advanced-module-set-topics.html

A module set contains one or more module declared in the project's pom.xml, and allows inclusion of sources or binaries belonging to those modules. The module set works and includes artifacts from other modules of the project even in the case the assembly is executed by a module of the project, not the (root) project itself.

By default, the moduleSet without any includes matches all modules of the project.

Assuming that the assembly is executed by a "release" module, and the project has a "module1" module, the following declaration makes the assembly plugin to include module1's artifact and its dependencies in the lib directory of the assembly:

<moduleSets>
    <moduleSet>
        <binaries>
           <outputDirectory>lib</outputDirectory>
        </binaries>
    </moduleSet>
</moduleSets>

File Sets

A <fileSet> allows the inclusion of groups of files into the assembly.

<fileSets>
    <fileSet>
        <directory>${project.build.directory}/bin</directory>
        <outputDirectory>/bin</outputDirectory>
        <includes>
            <include>*.sh</include>
        </includes>
        <fileMode>0755</fileMode>
    </fileSet>
    ...
</fileSets>

Individual Files

<files>
    <file>
        <source>../api/target/events-api-${module.api.version}.jar</source>
        <outputDirectory>lib</outputDirectory>
       <fileMode>0755</fileMode>
    </file>
    ...
</files>

Dependencies

The following configuration places all transitive dependencies of the project into the ./lib directory of the assembly.

<dependencySets>
    <dependencySet>
        <outputDirectory>lib</outputDirectory>
    </dependencySet>
</dependencySets>

Procedures

Change File Permissions

Use

<fileMode>0xxx</fileMode>

with <fileSet>s and <file>s.