assembly:single

Full name:

org.apache.maven.plugins:maven-assembly-plugin:3.0.0:single

Description:

Assemble an application bundle or distribution from an assembly descriptor. This goal is suitable either for binding to the lifecycle or calling directly from the command line (provided all required files are available before the build starts, or are produced by another goal specified before this one on the command line).

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: compile.
  • The goal is thread-safe and supports parallel builds.
  • Is NOT inherited by default in multi-project builds.

Required Parameters

Name Type Since Description
outputDirectory File - The output directory of the assembled distribution file.
Default value is: ${project.build.directory}.
workDirectory File - Directory to unpack JARs into if needed
Default value is: ${project.build.directory}/assembly/work.

Optional Parameters

Name Type Since Description
appendAssemblyId boolean - Set to false to exclude the assembly id from the assembly final name, and to create the resultant assembly artifacts without classifier. As such, an assembly artifact having the same format as the packaging of the current Maven project will replace the file for this main project artifact.
Default value is: true.
User property is: assembly.appendAssemblyId.
archive MavenArchiveConfiguration - This is a set of instructions to the archive builder, especially for building .jar files. It enables you to specify a Manifest file for the jar, in addition to other options. See Maven Archiver Reference.
archiveBaseDirectory File - This is the base directory from which archive files are created. This base directory pre-pended to any <directory> specifications in the assembly descriptor. This is an optional parameter.
archiverConfig PlexusConfiguration 2.2-beta-3 Allows additional configuration options that are specific to a particular type of archive format. This is intended to capture an XML configuration that will be used to reflectively setup the options on the archiver instance.
For instance, to direct an assembly with the "ear" format to use a particular deployment descriptor, you should specify the following for the archiverConfig value in your plugin configuration:
<appxml>${project.basedir}/somepath/app.xml</appxml>

attach boolean 2.2-beta-1 Controls whether the assembly plugin tries to attach the resulting assembly to the project.
Default value is: true.
User property is: assembly.attach.
delimiters List 2.4

Set of delimiters for expressions to filter within the resources. These delimiters are specified in the form 'beginToken*endToken'. If no '*' is given, the delimiter is assumed to be the same for start and end.

So, the default filtering delimiters might be specified as:

<delimiters>
  <delimiter>${*}</delimiter>
  <delimiter>@</delimiter>
</delimiters>

Since the '@' delimiter is the same on both ends, we don't need to specify '@*@' (though we can).


descriptorRefs String[] - A list of references to assembly descriptors available on the plugin's classpath. The default classpath includes these built-in descriptors: bin, jar-with-dependencies, src, and project. You can add others by adding dependencies to the plugin.
descriptorSourceDirectory File - Directory to scan for descriptor files in. NOTE: This may not work correctly with assembly components.
descriptors String[] - A list of descriptor files to generate from.
dryRun boolean - If this flag is set, everything up to the call to Archiver.createArchive() will be executed.
Default value is: false.
User property is: assembly.dryRun.
encoding String - The character encoding scheme to be applied when filtering resources.
Default value is: ${project.build.sourceEncoding}.
User property is: encoding.
escapeString String 2.4 Expressions preceded with this String won't be interpolated. If you use "\" as the escape string then \${foo} will be replaced with ${foo}.
User property is: assembly.escapeString.
filters List - The list of extra filter properties files to be used along with System properties, project properties, and filter properties files specified in the POM build/filters section, which should be used for the filtering during the current mojo execution.
Normally, these will be configured from a plugin's execution section, to provide a different set of filters for a particular execution.
formats List - 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:
  • dir - Creates a directory
  • zip - Creates a ZIP file format
  • tar - Creates a TAR format
  • tar.gz or tgz - Creates a gzip'd TAR format
  • tar.bz2 or tbz2 - Creates a bzip'd TAR format

ignoreDirFormatExtensions boolean - If this flag is set, the ".dir" suffix will be suppressed in the output directory name when using assembly/format == 'dir' and other formats that begin with 'dir'.
NOTE: Since 2.2-beta-3, the default-value for this is true, NOT false as it used to be.
Default value is: true.
ignoreMissingDescriptor boolean - Set to true in order to not fail when a descriptor is missing.
Default value is: false.
User property is: assembly.ignoreMissingDescriptor.
ignorePermissions boolean 2.2

Set to true in order to avoid all chmod calls.

NOTE: This will cause the assembly plugin to DISREGARD all fileMode/directoryMode settings in the assembly descriptor, and all file permissions in unpacked dependencies!


Default value is: false.
User property is: assembly.ignorePermissions.
includeProjectBuildFilters boolean 2.4.2 If True (default) then the ${project.build.filters} are also used in addition to any further filters defined for the Assembly.
Default value is: true.
User property is: assembly.includeProjectBuildFilters.
mergeManifestMode String 3 sets the merge manifest mode in the JarArchiver
recompressZippedFiles boolean 2.4 Indicates if zip archives (jar,zip etc) being added to the assembly should be compressed again. Compressing again can result in smaller archive size, but gives noticeably longer execution time.
Default value is: true.
runOnlyAtExecutionRoot boolean 2.2-beta-4 This will cause the assembly to run only at the top of a given module tree. That is, run in the project contained in the same folder where the mvn execution was launched.
Default value is: false.
User property is: assembly.runOnlyAtExecutionRoot.
skipAssembly boolean - Flag allowing one or more executions of the assembly plugin to be configured as skipped for a particular build. This makes the assembly plugin more controllable from profiles.
Default value is: false.
User property is: assembly.skipAssembly.
tarLongFileMode String - Sets the TarArchiver behavior on file paths with more than 100 characters length. Valid values are: "warn" (default), "fail", "truncate", "gnu", "posix", "posix_warn" or "omit".
Default value is: warn.
User property is: assembly.tarLongFileMode.
updateOnly boolean 2.2 This will cause the assembly to only update an existing archive, if it exists.

Note: The property that can be used on the command line was misspelled as "assembly.updatOnly" in versions prior to version 2.4.


Default value is: false.
User property is: assembly.updateOnly.
useJvmChmod boolean 2.2

will use the jvm chmod, this is available for user and all level group level will be ignored As of assembly-plugin 2.5, this flag is ignored for users of java7+


Default value is: false.
User property is: assembly.useJvmChmod.

Parameter Details

appendAssemblyId:

Set to false to exclude the assembly id from the assembly final name, and to create the resultant assembly artifacts without classifier. As such, an assembly artifact having the same format as the packaging of the current Maven project will replace the file for this main project artifact.
  • Type: boolean
  • Required: No
  • User Property: assembly.appendAssemblyId
  • Default: true

archive:

This is a set of instructions to the archive builder, especially for building .jar files. It enables you to specify a Manifest file for the jar, in addition to other options. See Maven Archiver Reference.
  • Type: org.apache.maven.archiver.MavenArchiveConfiguration
  • Required: No

archiveBaseDirectory:

This is the base directory from which archive files are created. This base directory pre-pended to any <directory> specifications in the assembly descriptor. This is an optional parameter.
  • Type: java.io.File
  • Required: No

archiverConfig:

Allows additional configuration options that are specific to a particular type of archive format. This is intended to capture an XML configuration that will be used to reflectively setup the options on the archiver instance.
For instance, to direct an assembly with the "ear" format to use a particular deployment descriptor, you should specify the following for the archiverConfig value in your plugin configuration:
<appxml>${project.basedir}/somepath/app.xml</appxml>
  • Type: org.codehaus.plexus.configuration.PlexusConfiguration
  • Since: 2.2-beta-3
  • Required: No

attach:

Controls whether the assembly plugin tries to attach the resulting assembly to the project.
  • Type: boolean
  • Since: 2.2-beta-1
  • Required: No
  • User Property: assembly.attach
  • Default: true

delimiters:

Set of delimiters for expressions to filter within the resources. These delimiters are specified in the form 'beginToken*endToken'. If no '*' is given, the delimiter is assumed to be the same for start and end.

So, the default filtering delimiters might be specified as:

<delimiters>
  <delimiter>${*}</delimiter>
  <delimiter>@</delimiter>
</delimiters>

Since the '@' delimiter is the same on both ends, we don't need to specify '@*@' (though we can).

  • Type: java.util.List
  • Since: 2.4
  • Required: No

descriptorRefs:

A list of references to assembly descriptors available on the plugin's classpath. The default classpath includes these built-in descriptors: bin, jar-with-dependencies, src, and project. You can add others by adding dependencies to the plugin.
  • Type: java.lang.String[]
  • Required: No

descriptorSourceDirectory:

Directory to scan for descriptor files in. NOTE: This may not work correctly with assembly components.
  • Type: java.io.File
  • Required: No

descriptors:

A list of descriptor files to generate from.
  • Type: java.lang.String[]
  • Required: No

dryRun:

If this flag is set, everything up to the call to Archiver.createArchive() will be executed.
  • Type: boolean
  • Required: No
  • User Property: assembly.dryRun
  • Default: false

encoding:

The character encoding scheme to be applied when filtering resources.
  • Type: java.lang.String
  • Required: No
  • User Property: encoding
  • Default: ${project.build.sourceEncoding}

escapeString:

Expressions preceded with this String won't be interpolated. If you use "\" as the escape string then \${foo} will be replaced with ${foo}.
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • User Property: assembly.escapeString

filters:

The list of extra filter properties files to be used along with System properties, project properties, and filter properties files specified in the POM build/filters section, which should be used for the filtering during the current mojo execution.
Normally, these will be configured from a plugin's execution section, to provide a different set of filters for a particular execution.
  • Type: java.util.List
  • Required: No

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:
  • dir - Creates a directory
  • zip - Creates a ZIP file format
  • tar - Creates a TAR format
  • tar.gz or tgz - Creates a gzip'd TAR format
  • tar.bz2 or tbz2 - Creates a bzip'd TAR format
  • Type: java.util.List
  • Required: No

ignoreDirFormatExtensions:

If this flag is set, the ".dir" suffix will be suppressed in the output directory name when using assembly/format == 'dir' and other formats that begin with 'dir'.
NOTE: Since 2.2-beta-3, the default-value for this is true, NOT false as it used to be.
  • Type: boolean
  • Required: No
  • Default: true

ignoreMissingDescriptor:

Set to true in order to not fail when a descriptor is missing.
  • Type: boolean
  • Required: No
  • User Property: assembly.ignoreMissingDescriptor
  • Default: false

ignorePermissions:

Set to true in order to avoid all chmod calls.

NOTE: This will cause the assembly plugin to DISREGARD all fileMode/directoryMode settings in the assembly descriptor, and all file permissions in unpacked dependencies!

  • Type: boolean
  • Since: 2.2
  • Required: No
  • User Property: assembly.ignorePermissions
  • Default: false

includeProjectBuildFilters:

If True (default) then the ${project.build.filters} are also used in addition to any further filters defined for the Assembly.
  • Type: boolean
  • Since: 2.4.2
  • Required: No
  • User Property: assembly.includeProjectBuildFilters
  • Default: true

mergeManifestMode:

sets the merge manifest mode in the JarArchiver
  • Type: java.lang.String
  • Since: 3
  • Required: No

outputDirectory:

The output directory of the assembled distribution file.
  • Type: java.io.File
  • Required: Yes
  • Default: ${project.build.directory}

recompressZippedFiles:

Indicates if zip archives (jar,zip etc) being added to the assembly should be compressed again. Compressing again can result in smaller archive size, but gives noticeably longer execution time.
  • Type: boolean
  • Since: 2.4
  • Required: No
  • Default: true

runOnlyAtExecutionRoot:

This will cause the assembly to run only at the top of a given module tree. That is, run in the project contained in the same folder where the mvn execution was launched.
  • Type: boolean
  • Since: 2.2-beta-4
  • Required: No
  • User Property: assembly.runOnlyAtExecutionRoot
  • Default: false

skipAssembly:

Flag allowing one or more executions of the assembly plugin to be configured as skipped for a particular build. This makes the assembly plugin more controllable from profiles.
  • Type: boolean
  • Required: No
  • User Property: assembly.skipAssembly
  • Default: false

tarLongFileMode:

Sets the TarArchiver behavior on file paths with more than 100 characters length. Valid values are: "warn" (default), "fail", "truncate", "gnu", "posix", "posix_warn" or "omit".
  • Type: java.lang.String
  • Required: No
  • User Property: assembly.tarLongFileMode
  • Default: warn

updateOnly:

This will cause the assembly to only update an existing archive, if it exists.

Note: The property that can be used on the command line was misspelled as "assembly.updatOnly" in versions prior to version 2.4.

  • Type: boolean
  • Since: 2.2
  • Required: No
  • User Property: assembly.updateOnly
  • Default: false

useJvmChmod:

will use the jvm chmod, this is available for user and all level group level will be ignored As of assembly-plugin 2.5, this flag is ignored for users of java7+

  • Type: boolean
  • Since: 2.2
  • Required: No
  • User Property: assembly.useJvmChmod
  • Default: false

workDirectory:

Directory to unpack JARs into if needed
  • Type: java.io.File
  • Required: Yes
  • Default: ${project.build.directory}/assembly/work