What is Maven Assembly Plugin? How to use it to create distribution packages?

Maven Assembly Plugin is a powerful plugin provided by Maven for creating custom distributions. It allows developers to package projects and their dependencies into various formats such as ZIP, TAR, GZ, etc., meeting different distribution needs.

Role of Assembly Plugin:

1. Create distributable software packages
2. Package projects and all their dependencies
3. Support custom file structures and layouts
4. Generate multiple compression formats
5. Create executable startup scripts

Configuring Assembly Plugin:

1. Add Plugin Dependency:

xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <version>3.4.2</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>
    </plugins>
</build>

1. Use Predefined Descriptors:

• jar-with-dependencies: JAR package containing all dependencies
• bin: Binary distribution package
• src: Source code distribution package
• project: Project distribution package

Custom Assembly Descriptor:

Create src/assembly/distribution.xml file:

xml
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.1.0
          https://maven.apache.org/xsd/assembly-2.1.0.xsd">
    <id>distribution</id>
    <formats>
        <format>zip</format>
        <format>tar.gz</format>
    </formats>
    <includeBaseDirectory>true</includeBaseDirectory>
    <baseDirectory>${project.artifactId}-${project.version}</baseDirectory>
    
    <fileSets>
        <fileSet>
            <directory>src/main/scripts</directory>
            <outputDirectory>bin</outputDirectory>
            <fileMode>0755</fileMode>
        </fileSet>
        <fileSet>
            <directory>src/main/config</directory>
            <outputDirectory>conf</outputDirectory>
        </fileSet>
    </fileSets>
    
    <dependencySets>
        <dependencySet>
            <outputDirectory>lib</outputDirectory>
            <useProjectArtifact>true</useProjectArtifact>
            <scope>runtime</scope>
        </dependencySet>
    </dependencySets>
</assembly>

Reference Custom Descriptor in POM:

xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.4.2</version>
    <configuration>
        <descriptors>
            <descriptor>src/assembly/distribution.xml</descriptor>
        </descriptors>
    </configuration>
</plugin>

Core Elements of Assembly Descriptor:

1. formats: Define output formats (zip, tar, tar.gz, jar, war, etc.)
2. fileSets: Define file sets, including source files and target directories
3. dependencySets: Define dependency sets, including dependency output directories and scopes
4. files: Define individual files
5. moduleSets: Define module sets for multi-module projects

Create Executable JAR:

xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
        <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
        <archive>
            <manifest>
                <mainClass>com.example.Main</mainClass>
            </manifest>
        </archive>
    </configuration>
</plugin>

Create Startup Scripts: Create startup scripts in the src/main/scripts directory:

start.sh (Unix/Linux):

bash
#!/bin/bash
APP_HOME=$(cd "$(dirname "$0")"; pwd)
java -jar $APP_HOME/lib/${project.artifactId}-${project.version}.jar

start.bat (Windows):

batch
@echo off
set APP_HOME=%~dp0
java -jar %APP_HOME%lib\${project.artifactId}-${project.version}.jar

Using Assembly Plugin:

bash
mvn clean package

The generated distribution packages are located in the target directory.

Best Practices:

1. Use custom descriptors to meet specific needs
2. Reasonably organize file structure for easy user use
3. Include README and LICENSE files
4. Set correct file permissions (fileMode)
5. Use Profile to distinguish distribution packages for different environments
6. Automate distribution package creation in CI/CD processes
7. Regularly test the usability of distribution packages

Common Issue Resolution:

1. Dependency Conflicts: Use <excludes> to exclude unwanted dependencies
2. File Permissions: Set correct file modes in Unix systems
3. Path Issues: Use relative paths to ensure cross-platform compatibility
4. Package Size: Use <useTransitiveFiltering> to control dependency scope

Maven Assembly Plugin is a powerful tool for creating professional distribution packages, capable of meeting various complex distribution needs.