The Maven Assembly Plugin creates archives of your project's sources, classes, dependencies, and other resources from flexible assembly descriptors. It's commonly used to create distribution packages, fat JARs, or custom archive formats.

Plugin coordinates:

• Group Id: org.apache.maven.plugins
  
• Artifact Id: maven-assembly-plugin
  
• Version: 3.7.1
  

Plugin Prefix: assembly

The assembly plugin has the following main goals:

• help: Displays help information on the maven-assembly-plugin. Use this goal to get detailed information about plugin parameters and their usage.
  
  
• single: Assembles an application bundle or distribution from an assembly descriptor. This is the primary goal used to create custom archives, such as zip or tar files, based on the assembly descriptor's instructions.
  
  

The plugin also provides predefined descriptors like jar-with-dependencies, src, bin, and project for common use cases.

Common Use Cases:

• Uber JAR: Use jar-with-dependencies descriptor for executable JARs
  
• Distribution Package: Include binaries, documentation, and configuration files
  
• Source Distribution: Use src descriptor for source code packages
  
• Docker Build Context: Create custom archives for containerization
  

Best Practices:

• Set appendAssemblyId to false for single assemblies.
  
• Use Maven properties and filtering for dynamic content.
  
• Consider using useTransitiveFiltering for dependency management.
  
• Use proper file permissions (fileMode) for executable files.
  

The help goal provides general information about the assembly plugin, including available goals and their parameters.

Use the detail parameter to get detailed information about all goals and their configuration options:

# Display basic plugin information
$ mvn assembly:help

# Display detailed information about all goals and parameters
$ mvn assembly:help -Ddetail=true

If you need to use the plugin's full coordinates instead of its prefix, you can do that as follows:

# Display basic plugin information
$ mvn org.apache.maven.plugins:maven-assembly-plugin:3.7.1:help

# Display detailed information about all goals and parameters
$ mvn org.apache.maven.plugins:maven-assembly-plugin:3.7.1:help -Ddetail=true

You can also use the Maven help plugin to describe the assembly plugin:

# Basic plugin description using help plugin
$ mvn help:describe -Dplugin="org.apache.maven.plugins:maven-assembly-plugin:3.7.1"

# Detailed plugin description with all parameters
$ mvn help:describe -Dplugin="org.apache.maven.plugins:maven-assembly-plugin:3.7.1" -Ddetail=true

To get specific information about a goal, use the goal parameter:

# Help for the 'single' goal
$ mvn org.apache.maven.plugins:maven-assembly-plugin:3.7.1:help -Dgoal=single -Ddetail=true

# Help for the 'single' goal using the help plugin
$ mvn help:describe -Dplugin="org.apache.maven.plugins:maven-assembly-plugin:3.7.1" -Dgoal=single -Ddetail=true

Note: When using the plugin's help goal directly, you don't need to specify the version if the plugin is already configured in your POM or if you want to use the latest version.

Configure your pom.xml file with the following plugin configuration:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.7.1</version>

    <configuration>
        <!-- Set to false to avoid appending assembly id to final name -->
        <appendAssemblyId>false</appendAssemblyId>

        <descriptors>
            <descriptor>src/main/assembly/assembly.xml</descriptor>
        </descriptors>
    </configuration>

    <executions>
        <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Create the directory structure and "assembly.xml" descriptor file:

$ mkdir -p src/main/assembly/
$ vi src/main/assembly/assembly.xml

Example assembly descriptor (src/main/assembly/assembly.xml):

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0
                        http://maven.apache.org/xsd/assembly-2.2.0.xsd">

    <id>dist</id>
    <includeBaseDirectory>false</includeBaseDirectory>

    <formats>
        <format>zip</format>
        <format>tar.gz</format>
    </formats>

    <!-- Include project resources -->
    <fileSets>
        <fileSet>
            <directory>src/main/resources</directory>
            <outputDirectory>resources</outputDirectory>
            <filtered>true</filtered>
            <includes>
                <include>**/*.properties</include>
                <include>**/*.xml</include>
                <include>**/*.txt</include>
            </includes>
        </fileSet>

        <!-- Include compiled classes -->
        <fileSet>
            <directory>${project.build.outputDirectory}</directory>
            <outputDirectory>classes</outputDirectory>
            <includes>
                <include>**/*.class</include>
            </includes>
        </fileSet>

        <!-- Include project documentation -->
        <fileSet>
            <directory>${project.basedir}</directory>
            <outputDirectory></outputDirectory>
            <includes>
                <include>README*</include>
                <include>LICENSE*</include>
                <include>NOTICE*</include>
            </includes>
        </fileSet>
    </fileSets>

    <!-- Include dependencies -->
    <dependencySets>
        <dependencySet>
            <outputDirectory>lib</outputDirectory>
            <unpack>false</unpack>
            <scope>runtime</scope>

            <!-- Optional: Include specific dependencies -->
            <includes>
                <include>*:*</include>
            </includes>

            <!-- Optional: Exclude specific dependencies -->
            <excludes>
                <exclude>*:*:*:test</exclude>
            </excludes>

            <outputFileNameMapping>${artifact.artifactId}-${artifact.baseVersion}${dashClassifier?}.${artifact.extension}</outputFileNameMapping>
        </dependencySet>
    </dependencySets>
</assembly>

To execute the assembly:

$ mvn clean package
$ mvn assembly:single

Use predefined descriptor: jar-with-dependencies

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.7.1</version>
    <configuration>
        <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
        <archive>
            <manifest>
                <mainClass>com.example.Main</mainClass>
            </manifest>
        </archive>
    </configuration>
    <executions>
        <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
        </execution>
    </executions>
</plugin>