assembly:single

Full name:

org.apache.maven.plugins:maven-assembly-plugin:3.7.1: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).
Note that the parameters descriptors, descriptorRefs, and descriptorSourceDirectory are disjoint, i.e., they are not combined during descriptor location calculation.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: test.
  • The goal is thread-safe and supports parallel builds.

Required Parameters

Name Type Since Description
<finalName> String - The filename of the assembled distribution file.
NOTE: This parameter has only impact on name in project target directory, installed/deployed artifacts will follow convention for artifact names.
Default: ${project.build.finalName}
<outputDirectory> File - The output directory of the assembled distribution file.
Default: ${project.build.directory}
<workDirectory> File - Directory to unpack JARs into if needed
Default: ${project.build.directory}/assembly/work

Optional Parameters

Name Type Since Description
<additionalProperties> Properties 3.3.0 A set of additional properties to use for filtering
<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: true
User Property: 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.
To see the possible options for archiver configuration visit the Plexus Archiver Documentation
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: true
User Property: assembly.attach
<delimiters> List<String> 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.
<descriptors> String[] - A list of descriptor files to generate from.
<descriptorSourceDirectory> File - Directory to scan for descriptor files in. NOTE: This may not work correctly with assembly components.
<dryRun> boolean - If this flag is set, everything up to the call to Archiver.createArchive() will be executed.
Default: false
User Property: assembly.dryRun
<encoding> String - The character encoding scheme to be applied when filtering resources.
Default: ${project.build.sourceEncoding}
User Property: 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: assembly.escapeString
<filters> List<String> - 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<String> - 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
  • tar.snappy - Creates a snappy'd TAR format
  • tar.xz or txz - Creates a xz'd TAR format
  • tar.zst or tzst - Creates a zst'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: true
<ignoreMissingDescriptor> boolean - Set to true in order to not fail when a descriptor is missing.
Default: false
User Property: 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: false
User Property: 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: true
User Property: assembly.includeProjectBuildFilters
<inlineDescriptors> List<Assembly> 3.7.0 An inline list of descriptor to generate from.

Each element of list must follow Assembly Descriptor format.
<mergeManifestMode> String 3 sets the merge manifest mode in the JarArchiver
<outputTimestamp> String 3.2.0 Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).
Default: ${project.build.outputTimestamp}
<overrideGid> Integer - Override of group ID in archive type which can store it.
<overrideGroupName> String - Override of group name in archive type which can store it.
<overrideUid> Integer - Override of user ID in archive type which can store it.
<overrideUserName> String - Override of user name in archive type which can store it.
<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: 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: false
User Property: 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: false
User Property: 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: warn
User Property: 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: false
User Property: assembly.updateOnly

Parameter Details

<additionalProperties>

A set of additional properties to use for filtering
  • Type: java.util.Properties
  • Since: 3.3.0
  • Required: report.plugin.goal.no

<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: report.plugin.goal.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: report.plugin.goal.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: report.plugin.goal.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.
To see the possible options for archiver configuration visit the Plexus Archiver Documentation
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: report.plugin.goal.no

<attach>

Controls whether the assembly plugin tries to attach the resulting assembly to the project.
  • Type: boolean
  • Since: 2.2-beta-1
  • Required: report.plugin.goal.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<java.lang.String>
  • Since: 2.4
  • Required: report.plugin.goal.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: report.plugin.goal.no

<descriptors>

A list of descriptor files to generate from.
  • Type: java.lang.String[]
  • Required: report.plugin.goal.no

<descriptorSourceDirectory>

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

<dryRun>

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

<encoding>

The character encoding scheme to be applied when filtering resources.
  • Type: java.lang.String
  • Required: report.plugin.goal.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: report.plugin.goal.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<java.lang.String>
  • Required: report.plugin.goal.no

<finalName>

The filename of the assembled distribution file.
NOTE: This parameter has only impact on name in project target directory, installed/deployed artifacts will follow convention for artifact names.
  • Type: java.lang.String
  • Required: report.plugin.goal.yes
  • Default: ${project.build.finalName}

<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
  • tar.snappy - Creates a snappy'd TAR format
  • tar.xz or txz - Creates a xz'd TAR format
  • tar.zst or tzst - Creates a zst'd TAR format
  • Type: java.util.List<java.lang.String>
  • Required: report.plugin.goal.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: report.plugin.goal.no
  • Default: true

<ignoreMissingDescriptor>

Set to true in order to not fail when a descriptor is missing.
  • Type: boolean
  • Required: report.plugin.goal.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: report.plugin.goal.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: report.plugin.goal.no
  • User Property: assembly.includeProjectBuildFilters
  • Default: true

<inlineDescriptors>

An inline list of descriptor to generate from.

Each element of list must follow Assembly Descriptor format.

<mergeManifestMode>

sets the merge manifest mode in the JarArchiver
  • Type: java.lang.String
  • Since: 3
  • Required: report.plugin.goal.no

<outputDirectory>

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

<outputTimestamp>

Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).
  • Type: java.lang.String
  • Since: 3.2.0
  • Required: report.plugin.goal.no
  • Default: ${project.build.outputTimestamp}

<overrideGid>

Override of group ID in archive type which can store it.
  • Type: java.lang.Integer
  • Required: report.plugin.goal.no

<overrideGroupName>

Override of group name in archive type which can store it.
  • Type: java.lang.String
  • Required: report.plugin.goal.no

<overrideUid>

Override of user ID in archive type which can store it.
  • Type: java.lang.Integer
  • Required: report.plugin.goal.no

<overrideUserName>

Override of user name in archive type which can store it.
  • Type: java.lang.String
  • Required: report.plugin.goal.no

<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: report.plugin.goal.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: report.plugin.goal.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: report.plugin.goal.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: report.plugin.goal.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: report.plugin.goal.no
  • User Property: assembly.updateOnly
  • Default: false

<workDirectory>

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