Assembly

Maven Assembly Plugin relies on the provided assembly descriptors to dictate its execution. Although there are already prefabricated descriptors available for use, they can only suffice some of the common assembly requirements.

So in order for you to customize the way the Assembly Plugin creates your assemblies, you need to know how to use the Assembly Descriptor.

This descriptor specifies the type of assembly archive to create, the contents of the assembly, and the ways in which dependencies or its modules are bundled with an assembly. 

<assembly>
  <id/>
  <formats/>
  <includeBaseDirectory/>
  <includeSiteDirectory/>
  <moduleSets>
    <moduleSet>
      <includes/>
      <excludes/>
      <sources>
        <outputDirectory/>
        <includes/>
        <excludes/>
        <fileMode/>
        <directoryMode/>
      </sources>
      <binaries>
        <includeDependencies/>
        <unpack/>
        <outputFileNameMapping/>
        <outputDirectory/>
        <includes/>
        <excludes/>
        <fileMode/>
        <directoryMode/>
      </binaries>
    </moduleSet>
  </moduleSets>
  <fileSets>
    <fileSet>
      <directory/>
      <lineEnding/>
      <outputDirectory/>
      <includes/>
      <excludes/>
      <fileMode/>
      <directoryMode/>
    </fileSet>
  </fileSets>
  <files>
    <file>
      <source/>
      <outputDirectory/>
      <destName/>
      <fileMode/>
      <lineEnding/>
      <filtered/>
    </file>
  </files>
  <dependencySets>
    <dependencySet>
      <outputFileNameMapping/>
      <unpack/>
      <scope/>
      <outputDirectory/>
      <includes/>
      <excludes/>
      <fileMode/>
      <directoryMode/>
    </dependencySet>
  </dependencySets>
  <repositories>
    <repository>
      <includeMetadata/>
      <groupVersionAlignments>
        <groupVersionAlignment>
          <id/>
          <version/>
          <excludes/>
        </groupVersionAlignment>
      </groupVersionAlignments>
      <outputDirectory/>
      <includes/>
      <excludes/>
      <fileMode/>
      <directoryMode/>
    </repository>
  </repositories>
  <componentDescriptors/>
</assembly>

assembly

An assembly defines a collection of files usually distributed in an archive format such as zip, tar, or tar.gz that is generated from a project. For example, a project could produce a ZIP assembly which contains a project's JAR artifact in the root directory, the runtime dependencies in a lib/ directory, and a shell script to launch a stand-alone application.

Element Description
id Sets the id of this assembly. This is a symbolic name for a particular assembly of files from this project. Also, aside from being used to distinctly name the assembled package by attaching its value to the generated archive, the id is used as your artifact's classifier when deploying.
formats Specifies the formats of the assembly. Multiple formats can be supplied and the Assembly Plugin will generate an archive for each desired formats. When deploying your project, all file formats specified will also be deployed. A format is specified by supplying one of the following values in a <format> subelement:
  • "zip" - Creates a ZIP file format
  • "gz" - Creates a GZIP format
  • "tar" - Creates a TAR format
  • "tar.gz" - Creates a gzip'd TAR format
  • "tar.bz2 - Creates a bzip'd TAR format
includeBaseDirectory Includes a base directory in the final archive. For example, if you are creating an assembly named "your-app", setting includeBaseDirectory to true will create an archive that includes this base directory. If this option is set to false the archive created will unzip its content to the current directory. Default value is true.
includeSiteDirectory Includes a site directory in the final archive. The site directory location of a project is determined by the siteDirectory parameter of the Assembly Plugin. Default value is false.
moduleSets Specifies which module files to include in the assembly. A moduleSet is specified by providing one or more of <moduleSet> subelements.
fileSets Specifies which groups of files to include in the assembly. A fileSet is specified by providing one or more of <fileSet> subelements.
files Specifies which single files to include in the assembly. A file is specified by providing one or more of <file> subelements.
dependencySets Specifies which dependencies to include in the assembly. A dependencySet is specified by providing one or more of <dependencySet> subelements.
repositories Specifies which repository files to include in the assembly. A repository is specified by providing one or more of <repository> subelements.
componentDescriptors Specifies the shared components xml file locations to include in the assembly. The locations specified must be relative to the basedir of the project. When multiple componentDescriptors are found, their contents are merged. Check out the descriptor components for more information. A componentDescriptor is specified by providing one or more of <componentDescriptor> subelements.

moduleSet

A moduleSet represent one or more project <module> present inside a project's pom.xml. This allows you to include sources or binaries belonging to a project's <modules>.

NOTE: When using <moduleSets> from the command-line, it is required to pass first the package phase by doing: "mvn package assembly:assembly". This bug/issue is scheduled to be addressed by Maven 2.1.
Element Description
includes This is a list of <include/> subelements, each containing a module reference of the type groupId:artifactId. Modules matching these elements will be included in this set. If none is present, then <includes> represents all valid values.
excludes This is a list of <exclude/> subelements, each containing a module reference of the type groupId:artifactId. Modules matching these elements will be excluded from this set.
sources When this is present, the plugin will include the source files of the included modules from this set in the resulting assembly.
binaries When this is present, the plugin will include the binaries of the included modules from this set in the resulting assembly.

sources

Contains configuration options for including the source files of a project module in an assembly.
Element Description
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
includes When <include> subelements are present, they define a set of files and directory to include. If none is present, then <includes> represents all valid values.
excludes When <exclude> subelements are present, they define a set of files and directory to exclude. If none is present, then <excludes> represents no exclusions.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
directoryMode Similar to a UNIX permission, sets the directory mode of the directories included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0755 translates to User read-write, Group and Other read-only. (more on unix-style permissions)

binaries

Contains configuration options for including the binary files of a project module in an assembly.
Element Description
includeDependencies If set to true, the plugin will include the direct and transitive dependencies of of the project modules included here. Otherwise, it will only include the module packages only. Default value is false.
unpack If set to true, this property will unpack all module packages into the specified output directory. When set to false module packages will be included as archives (jars). Default value is true.
outputFileNameMapping Sets the mapping pattern for all dependencies included in this assembly. Default is ${artifactId}-${version}.${extension}.
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
includes When <include> subelements are present, they define a set of files and directory to include. If none is present, then <includes> represents all valid values.
excludes When <exclude> subelements are present, they define a set of files and directory to exclude. If none is present, then <excludes> represents no exclusions.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
directoryMode Similar to a UNIX permission, sets the directory mode of the directories included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0755 translates to User read-write, Group and Other read-only. (more on unix-style permissions)

fileSet

A fileSet allows the inclusion of groups of files into the assembly.
Element Description
directory Sets the absolute or relative location from the module's directory. For example, "src/main/bin" would select this subdirectory of the project in which this dependency is defined.
lineEnding Sets the line-endings of the files in this fileSet. Valid values:
  • "keep" - Preserve all line endings
  • "unix" - Use Unix-style line endings
  • "lf" - Use a single line-feed line endings
  • "dos" - Use DOS-style line endings
  • "crlf" - Use Carraige-return, line-feed line endings
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
includes When <include> subelements are present, they define a set of files and directory to include. If none is present, then <includes> represents all valid values.
excludes When <exclude> subelements are present, they define a set of files and directory to exclude. If none is present, then <excludes> represents no exclusions.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
directoryMode Similar to a UNIX permission, sets the directory mode of the directories included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0755 translates to User read-write, Group and Other read-only. (more on unix-style permissions)

file

A file allows individual file inclusion with the option to change the destination filename not supported by fileSets.
Element Description
source Sets the absolute or relative path from the module's directory of the file to be included in the assembly.
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
destName Sets the destination filename in the outputDirectory. Default is the same name as the source's file.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
lineEnding Sets the line-endings of the files in this file. Valid values are:
  • "keep" - Preserve all line endings
  • "unix" - Use Unix-style line endings
  • "lf" - Use a single line-feed line endings
  • "dos" - Use DOS-style line endings
  • "crlf" - Use Carraige-return, line-feed line endings
filtered Sets whether to determine if the file is filtered.

dependencySet

A dependencySet allows inclusion and exclusion of project dependencies in the assembly.
Element Description
outputFileNameMapping Sets the mapping pattern for all dependencies included in this assembly. Default is ${artifactId}-${version}.${extension}.
unpack If set to true, this property will unpack all dependencies into the specified output directory. When set to false dependencies will be includes as archives (jars). Can only unpack jar, zip, tar.gz, and tar.bz archives. Default value is false.
scope Sets the dependency scope for this dependencySet. Default scope value is "runtime".
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
includes When <include> subelements are present, they define a set of files and directory to include. If none is present, then <includes> represents all valid values.
excludes When <exclude> subelements are present, they define a set of files and directory to exclude. If none is present, then <excludes> represents no exclusions.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
directoryMode Similar to a UNIX permission, sets the directory mode of the directories included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0755 translates to User read-write, Group and Other read-only. (more on unix-style permissions)

repository

Defines a Maven repository to be included in the assembly. The artifacts available to be included in a repository are your project's dependency artifacts. The repository created contains the needed metadata entries and also contains both sha1 and md5 checksums. This is useful for creating archives which will be deployed to internal repositories.

NOTE: Currently, only artifacts from the central repository are allowed.
Element Description
includeMetadata If set to true, this property will trigger the creation of repository metadata which will allow the repository to be used as a functional remote repository. Default value is false.
groupVersionAlignments Specifies that you want to align a group of artifacts to a specified version. A groupVersionAlignment is specified by providing one or more of <groupVersionAlignment> subelements.
outputDirectory Sets the output directory relative to the root of the root directory of the assembly. For example, "log" will put the specified files in the log directory.
includes When <include> subelements are present, they define a set of files and directory to include. If none is present, then <includes> represents all valid values.
excludes When <exclude> subelements are present, they define a set of files and directory to exclude. If none is present, then <excludes> represents no exclusions.
fileMode Similar to a UNIX permission, sets the file mode of the files included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0644 translates to User read-write, Group and Other read-only. (more on unix-style permissions)
directoryMode Similar to a UNIX permission, sets the directory mode of the directories included. Format: (User)(Group)(Other) where each component is a sum of Read = 4, Write = 2, and Execute = 1. For example, the default value of 0755 translates to User read-write, Group and Other read-only. (more on unix-style permissions)

groupVersionAlignment

Allows a group of artifacts to be aligned to a specified version.
Element Description
id The groupId of the artifacts for which you want to align the versions.
version The version you want to align this group to.
excludes When <exclude> subelements are present, they define the artifactIds of the artifacts to exclude. If none is present, then <excludes> represents no exclusions. An exclude is specified by providing one or more of <exclude> subelements.