Maven: Plugin: maven-assembly -plugin

Introduction

The Assembly Plugin for Maven is primarily intended to allow users to aggregate the project output along with its dependencies, modules, site documentation, and other files into a single distributable archive.

Your project can build distribution "assemblies" easily, using one of the convenient, prefabricated assembly descriptors. These descriptors handle many common operations, such as packaging a project's artifact along with generated documentation into a single zip archive. Alternatively, your project can provide its own descriptor and assume a much higher level of control over how dependencies, modules, file-sets, and individual files are packaged in the assembly.

Currently it can create distributions in the following formats:

• zip
• tar
• tar.gz (or tgz)
• tar.bz2 (or tbz2)
• tar.snappy
• tar.xz (or txz)
• jar
• dir
• war
• and any other format that the ArchiveManager has been configured for

If your project wants to package your artifact in an uber-jar, the assembly plugin provides only basic support. For more control, use the Maven Shade Plugin.

To use the Assembly Plugin in Maven, you simply need to:

• choose or write the assembly descriptor to use,
• configure the Assembly Plugin in your project's pom.xml, and
• run "mvn assembly:single" on your project.

To write your own custom assembly, you will need to refer to the Assembly Descriptor Format reference.

What is an Assembly?

An "assembly" is a group of files, directories, and dependencies that are assembled into an archive format and distributed. For example, assume that a Maven project defines a single JAR artifact that contains both a console application and a Swing application. Such a project could define two "assemblies" that bundle the application with a different set of supporting scripts and dependency sets. One assembly would be the assembly for the console application, and the other assembly could be a Swing application bundled with a slightly different set of dependencies.

The Assembly Plugin provides a descriptor format which allows you to define an arbitrary assembly of files and directories from a project. For example, if your Maven project contains the directory "src/main/bin", you can instruct the Assembly Plugin to copy the contents of this directory to the "bin" directory of an assembly and to change the permissions of the files in the "bin" directory to UNIX mode 755. The parameters for configuring this behavior are supplied to the Assembly Plugin by way of the assembly descriptor.

Goals

The main goal in the assembly plugin is the single goal. It is used to create all assemblies.

For more information about the goals that are available in the Assembly Plugin, see the plugin documentation page.

Assembly and Component Descriptor Schemas (XSD)

• http://maven.apache.org/xsd/assembly-2.0.0.xsd, http://maven.apache.org/xsd/assembly-component-2.0.0.xsd (for version 3.0 and higher)
• http://maven.apache.org/xsd/assembly-1.1.3.xsd, http://maven.apache.org/xsd/component-1.1.3.xsd (for version 2.5.4 and higher)
• http://maven.apache.org/xsd/assembly-1.1.2.xsd, http://maven.apache.org/xsd/component-1.1.2.xsd (for version 2.2 and higher)
• http://maven.apache.org/xsd/assembly-1.1.1.xsd, http://maven.apache.org/xsd/component-1.1.1.xsd (for version 2.2-beta-4 - 2.2-beta-5)
• http://maven.apache.org/xsd/assembly-1.1.0.xsd, http://maven.apache.org/xsd/component-1.1.0.xsd (for version 2.2-beta-1 - 2.2-beta-3)
• http://maven.apache.org/xsd/assembly-1.0.0.xsd, http://maven.apache.org/xsd/component-1.0.0.xsd (for version 2.1 and lower)

Usage

General instructions on how to use the Assembly Plugin can be found on the usage page. Some more specific use cases are described in the examples given below.

In case you still have questions regarding the plugin's usage, please have a look at the FAQ and feel free to contact the user mailing list. The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the mail archive.

If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our issue tracker. When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our source repository and will find supplementary information in the guide to helping with Maven.

Examples

To provide you with better understanding on some usages of the Assembly Plugin, you can take a look into the examples which can be found here.

bin

Use bin as the descriptorRef of your assembly-plugin configuration in order to create a binary distribution archive of your project. This built-in descriptor produces an assembly with the classifier bin in three archive formats: tar.gz, tar.bz2, and zip.

The assembled archive contains the binary JAR produced by running mvn package plus any README, LICENSE, and NOTICE files available in the project root directory.

Below is the bin descriptor format:

jar-with-dependencies

Use jar-with-dependencies as the descriptorRef of your assembly-plugin configuration in order to create a JAR which contains the binary output of your project, along its the unpacked dependencies. This built-in descriptor produces an assembly with the classifier jar-with-dependencies using the JAR archive format.

Note that jar-with-dependencies provides only basic support for uber-jars. For more control, use the Maven Shade Plugin.

Below is the jar-with-dependencies descriptor format:

src

Use src as the descriptorRef in your assembly-plugin configuration to create source archives for your project. The archive will contain the contents of your project's /src directory structure, for reference by your users. The src descriptorId produces an assembly archive with the classifier src in three formats: tar.gz, tar.bz2, and zip.

Below is the src descriptor format:

project

Using the project <descriptorRef> in your Assembly Plugin configuration will produce an assembly containing your entire project, minus any build output that lands in the /target directory. The resulting assembly should allow your users to build your project using Maven, Ant, or whatever build system you have configured in your project's normal SCM working directory. It produces assemblies with the classifier project in three archive formats: tar.gz, tar.bz2, and zip.

The following is the assembly descriptor for the project descriptorRef:

System Requirements

The following specifies the minimum requirements to run this Maven plugin:

Usage

You should specify the version in your project's plugin configuration:

For more information, see "Guide to Configuring Plug-ins"

Assembly

https://maven.apache.org/plugins/maven-assembly-plugin/assembly.html

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 xmlns="http://maven.apache.org/ASSEMBLY/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
    <id/>
    <formats/>
    <includeBaseDirectory/>
    <baseDirectory/>
    <includeSiteDirectory/>
    <containerDescriptorHandlers>
        <containerDescriptorHandler>
            <handlerName/>
            <configuration/>
        </containerDescriptorHandler>
    </containerDescriptorHandlers>
    <moduleSets>
        <moduleSet>
            <useAllReactorProjects/>
            <includeSubModules/>
            <includes/>
            <excludes/>
            <sources>
                <useDefaultExcludes/>
                <outputDirectory/>
                <includes/>
                <excludes/>
                <fileMode/>
                <directoryMode/>
                <fileSets>
                    <fileSet>
                        <useDefaultExcludes/>
                        <outputDirectory/>
                        <includes/>
                        <excludes/>
                        <fileMode/>
                        <directoryMode/>
                        <directory/>
                        <lineEnding/>
                        <filtered/>
                    </fileSet>
                </fileSets>
                <includeModuleDirectory/>
                <excludeSubModuleDirectories/>
                <outputDirectoryMapping/>
            </sources>
            <binaries>
                <outputDirectory/>
                <includes/>
                <excludes/>
                <fileMode/>
                <directoryMode/>
                <attachmentClassifier/>
                <includeDependencies/>
                <dependencySets>
                    <dependencySet>
                        <outputDirectory/>
                        <includes/>
                        <excludes/>
                        <fileMode/>
                        <directoryMode/>
                        <useStrictFiltering/>
                        <outputFileNameMapping/>
                        <unpack/>
                        <unpackOptions>
                            <includes/>
                            <excludes/>
                            <filtered/>
                            <lineEnding/>
                            <useDefaultExcludes/>
                            <encoding/>
                        </unpackOptions>
                        <scope/>
                        <useProjectArtifact/>
                        <useProjectAttachments/>
                        <useTransitiveDependencies/>
                        <useTransitiveFiltering/>
                    </dependencySet>
                </dependencySets>
                <unpack/>
                <unpackOptions>
                    <includes/>
                    <excludes/>
                    <filtered/>
                    <lineEnding/>
                    <useDefaultExcludes/>
                    <encoding/>
                </unpackOptions>
                <outputFileNameMapping/>
            </binaries>
        </moduleSet>
    </moduleSets>
    <fileSets>
        <fileSet>
            <useDefaultExcludes/>
            <outputDirectory/>
            <includes/>
            <excludes/>
            <fileMode/>
            <directoryMode/>
            <directory/>
            <lineEnding/>
            <filtered/>
        </fileSet>
    </fileSets>
    <files>
        <file>
            <source/>
            <outputDirectory/>
            <destName/>
            <fileMode/>
            <lineEnding/>
            <filtered/>
        </file>
    </files>
    <dependencySets>
        <dependencySet>
            <outputDirectory/>
            <includes/>
            <excludes/>
            <fileMode/>
            <directoryMode/>
            <useStrictFiltering/>
            <outputFileNameMapping/>
            <unpack/>
            <unpackOptions>
                <includes/>
                <excludes/>
                <filtered/>
                <lineEnding/>
                <useDefaultExcludes/>
                <encoding/>
            </unpackOptions>
            <scope/>
            <useProjectArtifact/>
            <useProjectAttachments/>
            <useTransitiveDependencies/>
            <useTransitiveFiltering/>
        </dependencySet>
    </dependencySets>
    <repositories>
        <repository>
            <outputDirectory/>
            <includes/>
            <excludes/>
            <fileMode/>
            <directoryMode/>
            <includeMetadata/>
            <groupVersionAlignments>
                <groupVersionAlignment>
                    <id/>
                    <version/>
                    <excludes/>
                </groupVersionAlignment>
            </groupVersionAlignments>
            <scope/>
        </repository>
    </repositories>
    <componentDescriptors/>
</assembly>