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.

Example:

<assembly ...>
   <id>eap-module</id>
   ...
</assembly>

<format>

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

Multiple formats can be provided, and the plugin will generate an archive for each of them. Valid values are "zip", "tar", "tar.gz" ("tgz"), "tar.bz2" ("tbz2"), "jar", "dir","war".

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 with and includes artifacts from other modules that are declared in the same pom.xml as the assembly plugin.

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

Example:

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

In case of a "dedicated release module" pattern, no module set is necessary. It is sufficient to declare the other modules of the project as the dependencies of the release module and use a dependency set.

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>

Filtering and System Property Substitution

The assembly module can be instructed to filter symbols in the files as they are copied, using properties from the build configuration. By default this functionality is turned off and can be activated by setting <filtered> to true, for both <file>s and <fileSet>s:

<fileSet>
    ...
    <filtered>true</filtered>
</fileSet>

<file>
    ...
    <filtered>true</filtered>
</file>

For more details on how to specify the variables to be replaced, see:

Maven Filtering and Property Substitution

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>

In case of a "dedicated release module" pattern, it is sufficient to declare the other modules of the project as dependencies of the release module and use a generic dependency set in the release module assembly descriptor to include all the modules and their transitive dependencies.

Dependency Transitivity

By default, the dependency set will include the specified dependencies and the transitive dependencies. To turn off this behavior, use:

<dependencySet>
   ...
   <useTransitiveDependencies>false</useTransitiveDependencies>
</dependencySet>

Skipping the Current Project's Artifact

In case of a "POM-only" release project, this avoids the assembly plugin warning complaining that the release project does not have an artifact to include.

<dependencySet>
   ...
   <useProjectArtifact>false</useProjectArtifact>
</dependencySet>

Procedures

Change File Permissions

Use

<fileMode>0xxx</fileMode>

with <fileSet>s and <file>s.