Maven Assembly Plugin

Tuesday, 10 May 2011 18:40

Maven Asembly Plugin Tutorial

Maven Assembly is a plugin to create archives of your project's sources, classes, dependencies etc. from flexible assembly descriptors.

Create a zip file of your project using Maven assembly

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:

Include the following snippet in the <build><plugins> section of your project's pom.xml-file to configure your maven assembly plugin :

<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>2.2.1</version>
        <configuration>
          <descriptorRefs>
            <descriptorRef>project</descriptorRef>
          </descriptorRefs>
        </configuration>
        [...]
</project>

NOTE: We don't need a groupId specification because the group is org.apache.maven.plugins ...which is assumed by default.

Let's execute the assembly goal

mvn assembly:assembly

As a result you should have in your target folder a file called <my project>-project.zip containing all your project files (a tar.bz2 and a targ.gz as well)

Maven Assembly Goals (version 2.2.1)

assembly:single

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).

Available parameters:

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.



archiveBaseDirectory


This is the base directory from which archive files are created. This base
directory pre-pended to any specifications in the assembly
descriptor. This is an optional parameter.



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:



${project.basedir}/somepath/app.xml

attach (Default: true)


Controls whether the assembly plugin tries to attach the resulting
assembly to the project.
Expression: ${assembly.attach}



classifier


Deprecated. Please use the Assembly's id for classifier instead

This is the artifact classifier to be used for the resultant assembly
artifact. Normally, you would use the assembly-id instead of specifying
this here.
Expression: ${classifier}



descriptor


Deprecated. Please use descriptors instead

Assembly XML Descriptor file. This must be the path to your customized
descriptor file.
Expression: ${descriptor}



descriptorId


Deprecated. Please use descriptorRefs instead

Predefined Assembly Descriptor Id's. You can select bin,
jar-with-dependencies, or src.
Expression: ${descriptorId}



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.



descriptors


A list of descriptor files to generate from.



descriptorSourceDirectory


Directory to scan for descriptor files in. NOTE: This may not work
correctly with assembly components.



dryRun (Default: false)


If this flag is set, everything up to the call to Archiver.createArchive()
will be executed.
Expression: ${assembly.dryRun}



filters


(no description available)



finalName (Default: ${project.build.finalName})


The filename of the assembled distribution file.
Required: Yes 



ignoreDirFormatExtensions (Default: true)


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.



ignoreMissingDescriptor (Default: false)


Set to true in order to not fail when a descriptor is missing.
Expression: ${assembly.ignoreMissingDescriptor}



ignorePermissions (Default: false)


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!
Expression: ${assembly.ignorePermissions}



includeSite (Default: false)


Deprecated. Please set this variable in the assembly descriptor instead

Set to true to include the site generated by site:site goal.
Expression: ${includeSite}



outputDirectory (Default: ${project.build.directory})


The output directory of the assembled distribution file.
Required: Yes



runOnlyAtExecutionRoot (Default: false)


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.
Expression: ${assembly.runOnlyAtExecutionRoot}



skipAssembly (Default: false)


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.
Expression: ${assembly.skipAssembly}



tarLongFileMode (Default: warn)


Sets the TarArchiver behavior on file paths with more than 100 characters
length. Valid values are: 'warn' (default), 'fail', 'truncate', 'gnu', or
'omit'.
Expression: ${assembly.tarLongFileMode}



updateOnly (Default: false)


This will cause the assembly to only update an existing archive, if it
exists.
Expression: ${assembly.updatOnly}



useJvmChmod (Default: false)


will use the jvm chmod, this is available for user and all level group
level will be ignored
Expression: ${assembly.useJvmChmod}



workDirectory (Default: ${project.build.directory}/assembly/work)


Directory to unpack JARs into if needed
Required: Yes

Other Maven Plugins : Maven Plugin List