Maven assembly Plugin: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(65 intermediate revisions by the same user not shown)
Line 10: Line 10:
=Overview=
=Overview=


The assembly plugin provide a standard way to aggregate complex artifacts out of project modules' artifacts, dependencies, documentation and arbitrary files with the goal of producing a single distributable archive.
The assembly plugin provide a standard way to aggregate complex artifacts using the project modules artifacts, dependencies, documentation and arbitrary files. The plugin produces a single distributable archive. A module has only one artifact - usually a JAR - but we may want to distribute that JAR together with documentation, source and supporting scripts in the form or an "atomic" archive, usually created for an official release. The assembly plugin does that.


=Concepts=
=Concepts=
Line 18: Line 18:
An ''assembly'' is an single artifact produced by aggregating artifacts produced by modules, dependencies, documentation and arbitrary files. The assembly is built according to a specification formalized in the [[#Assembly_Descriptor|assembly descriptor]].
An ''assembly'' is an single artifact produced by aggregating artifacts produced by modules, dependencies, documentation and arbitrary files. The assembly is built according to a specification formalized in the [[#Assembly_Descriptor|assembly descriptor]].


===Assembly ID===
==The Name of the Assembly Artifact==


The assembly ID will become the assembly artifact classifier, present between the version and the extension.
By default, the name of the assembly artifact is generated according to the pattern ''artifactId-version-assemblyId.extension'', where:


==Assembly Descriptor==
* "artifactId" is the value of the <artifactId> element for the project (root or sub-module) that executes the assembly plugin.
* "version" is the value of the <version> element for the project (root or sub-module)  that executes the assembly plugin.
* "assemblyId" is the value of the <id> element for the assembly descriptor that drives the plugin. The assembly ID is used as a [[Maven Concepts#Classifier|classifier]] in the artifact name. In some cases, you may not want that; to configure Maven not to include it,  see section "[[#Prevent_the_Use_of_assemblyId_in_the_Artifact_Name|Prevent the Use of assemblyId in the Artifact Name]]" below. For more details on the <id> element, see [[Custom_Maven_Assembly_Descriptors#.3Cid.3E|Custom Maven Assembly Descriptors - the AssemblyID]].
* "extension" is dictated by the <format> element of the assembly descriptor. For more details see [[Custom_Maven_Assembly_Descriptors#.3Cid.3E|Custom Maven Assembly Descriptors]].


An ''assembly 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. It can also contain instructions to set specific permissions, etc.
====<finalName>====


Maven offers a set of predefined assembly descriptors, described below. Custom assembly descriptors can also be created, and this is the reference documentation for a custom assembly descriptor:  
The base name of the assembly artifact can be overridden using the <finalName> assembly plugin configuration element:


<blockquote style="background-color: AliceBlue; border: solid thin LightSteelBlue;">
<pre>
:http://maven.apache.org/components/plugins/maven-assembly-plugin/assembly.html<br>
  ...
</blockquote>
  <configuration>
      <finalName>someFinalName</finalName>
      ...
  </configuration>
  ...
</pre>


===Pre-defined Assembly Descriptors===
For the configuration presented above, the value specified as <finalName> is prepended to the assemblyId classifier and the extension, as follows: ''someFinalName-assemblyId.extension'' Note that the <finalName> may include system properties, such as ${project.version}, which will be de-referenced.
====bin====


The assembled archive produced by this descriptor contains the binary JAR produced by running mvn package plus any README, LICENSE, and NOTICE files available in the project root directory. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#bin.
<blockquote style="background-color: Gold; border: solid thin Goldenrod;">
:Experience has shown that is best if we use <finalName> to name the assembly artifact. It offers more flexibility, as particular values for "artifactId" may interfere with the build process. We recommend using a "release" module with a "release" artifactId, and naming the assembly with <finalName>. However, as explained in the "[[Maven_pom.xml#.3CfinalName.3E|<finalName>]]" section, the custom finalName is only used to generate the artifact file in the local target directory. The artifact file installed in the artifact repository will still be named "release-..."<br>
</blockquote>


====jar-with-dependencies====
====Prevent the Use of assemblyId in the Artifact Name====


The assembled archive produced by this descriptor is a JAR which contains the binary output of your project, along its the unpacked dependencies. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#jar-with-dependencies
<span id="no_assemblyid_classifier">In order to prevent the inclusion of the assemblyId value</span> in the artifact name, use the following configuration element:


====src====
<pre>
  ...
  <configuration>
      <finalName>someFinalName</finalName>
      <appendAssemblyId>false</appendAssemblyId>
      ...
  </configuration>
  ...
</pre>


The assembled archive produced by this descriptor is the source archives for the project.  For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#src
For more details about the plugin configuration, see "[[#Plugin_Configuration|Plugin Configuration]]" section, below.


====project====
==Assembly Descriptor==


The assembled archive produced by this descriptor is the entire project, minus any build output that lands in the /target directory. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#project
An ''assembly 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. It can also contain instructions to set specific permissions, etc. Maven offers a set of predefined assembly descriptors, described below. Custom assembly descriptors can also be created.


==Plugin Execution==
===Pre-defined Assembly Descriptors===


The assembly plugin can be executed in isolation, or it can be executed during the build process of the project.
* "'''bin'''": the assembled archive produced by this descriptor contains the binary JAR produced by running mvn package plus any README, LICENSE, and NOTICE files available in the project root directory. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#bin
* "'''jar-with-dependencies'''": the assembled archive produced by this descriptor is a JAR which contains the binary output of your project, along its the unpacked dependencies. For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#jar-with-dependencies
* "'''src'''": the assembled archive produced by this descriptor is the source archives for the project.  For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#src
* "'''project'''": the assembled archive produced by this descriptor is the entire project, minus any build output that lands in the /target directory.  For more details see http://maven.apache.org/components/plugins/maven-assembly-plugin/descriptor-refs.html#project


To execute the plugin in isolation:
===Custom Assembly Descriptors===
 
To execute the plugin as part of the build process, bind the plugin's "single" goal to to the [[Maven Concepts - Lifecycle|project lifecycle]] by associating it usually with the [[Maven_Concepts_-_Lifecycle#package|"package" phase]], as follows:


<blockquote style="background-color: #f9f9f9; border: solid thin lightgrey;">
:[[Custom Maven Assembly Descriptors]]
</blockquote>


Once the plug-in is bound to the project lifecycle, simply execute the normal package phase from the default lifecycle to create a project assembly:
=Plugin Configuration=


<pre>
<pre>
mvn package
<project>
    ...
    <build>
        ...
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>2.6</version>
                <configuration>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                </configuration>
            </plugin>
        </plugins>
        ...
    </build>
    ...     
</project>
</pre>
</pre>


When this build completes, the assembly file is available in the target directory and has a name similar to the following: <font color=red>Put placeholders: <tt>target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar </tt>.</font>
Always update the plugin version to the latest stable version, to get reproducible builds.


In case the assembly doesn't require binaries, so the package phase does not need to be executed, the assembly's goal can be bound to a different project phase. You should be careful to make sure the resources included in your assembly exist before that assembly is created.
Use <descriptorRefs> (one or more) when the pre-defined assembly descriptors are sufficient. For a list of available pre-defined assembly descriptors, see "[[Maven_assembly_Plugin#Pre-defined_Assembly_Descriptors|Pre-defined Assembly Descriptors]]" section.  


=Building a Complex Release Artifact=
In case a custom assembly descriptor is needed, it is declared as follows:


This section describes the procedure of configuring Maven to build one complex release artifact, containing multiple individual artifacts, possibly produced by multiple modules, as well as arbitrary files from the project, dependencies, and so on, or otherwise what is known to Maven as an [[#Assembly|assembly]].  
<pre>
    ...
    <configuration>
        <descriptors>
            <descriptor>src/assembly/release.xml</descriptor>
        </descriptors>
    </configuration>
    ...
</pre>


For more details on custom assembly descriptors, see the "[[#Assembly_Descriptor|Assembly Descriptor]]" section.


!!!External
=Plugin Execution=


* [http://maven.apache.org/plugins/maven-assembly-plugin/]
The plugin has a single goal "single". The assembly plugin can be executed in isolation, or it can be executed during the build process of the project.
* [http://maven.apache.org/plugins/maven-assembly-plugin/assembly.html]
* Sonatype Assemblies [http://www.sonatype.com/books/mvnref-book/reference/assemblies.html]
* Assembly Best Practices according to Sonatype [http://www.sonatype.com/books/mvnref-book/reference/assemblies-sect-best-practices.html]


!!!Internal
To execute the plugin in isolation:


|[MavenFilesets]
<pre>
|[How to Exclude a File from the Final Artifact|MavenHOW2#HowToExcludeAFileFromTheFinalArtifact]
mvn assembly:single
</pre>


!!!Overview
To execute the plugin as part of the build process, the plugin has to be first declared and configured, as described in the "[[#Plugin_Configuration|Plugin Configuration]]" section, and then its "single" goal must be bound to the [[Maven Concepts - Lifecycle|project lifecycle]] by associating it usually with the [[Maven_Concepts_-_Lifecycle#package|"package" phase]], as follows:


An "assembly" is a group of files, directories, and dependencies that are assembled into an archive format and distributed as a project's artifact. A module has only one artifact - usually a JAR - but we may want to distribute that jar together with documentation, source and supporting scripts in the form or an "atomic" archive. The way to do it is to define that archive as an "assembly".
<pre>
 
<project>
!!!Notes
    ...
 
    <build>
* The {{assembly.xml}} file should go under {{src/main/assembly}}. It also works if it goes into the {{basedir}}.
        <plugins>
 
!!!Multi-Module Assemblies
 
|[MavenAssemblyPluginMultiModule]
 
!!!The simplest way to create a ZIP artifact
 
The following will create a test site content zip. The assembly plug in is the only "active" plug-in for a sub-module whose whole reason to exist is to create the content zip.
 
!!pom.xml
 
{{{
<plugins>
            ...
             <plugin>
             <plugin>
                 <artifactId>maven-assembly-plugin</artifactId>
                 <artifactId>maven-assembly-plugin</artifactId>
                <version>...</version>
                 <configuration>
                 <configuration>
                     <descriptors>
                     ...
                        <descriptor>assembly.xml</descriptor>
                    </descriptors>
                 </configuration>
                 </configuration>
                 <executions>
                 <executions>
                     <execution>
                     <execution>
                         <id>make-assembly</id>
                         <id>assembly-execution</id>
                         <phase>package</phase>
                         <phase>package</phase>
                         <goals>
                         <goals>
Line 123: Line 154:
                 </executions>
                 </executions>
             </plugin>
             </plugin>
            ...
        </plugins>
}}}
      ...
</project>
</pre>


!!assembly.xml
Once the plug-in is bound to the project lifecycle, simply execute the normal package phase from the default lifecycle to create a project assembly:


{{{
<pre>
<assembly>
mvn package
    <formats>
</pre>
        <format>zip</format>
    </formats>
    <baseDirectory>.</baseDirectory>
    <includeBaseDirectory>false</includeBaseDirectory>
    <fileSets>
        <fileSet>
            <directory>archimedes-test-site</directory>
        </fileSet>
    </fileSets>
</assembly>
}}}


!!!Jar With Dependencies
When this build completes, the assembly file is available in the target directory and has a name similar to the following: artifactId-version-jar-with-dependencies.jar (if "jar-with-dependencies" pre-defined assembly descriptor was used).


{{{
In case the assembly doesn't require binaries, so the package phase does not need to be executed, the assembly's goal can be bound to a different project phase. You should be careful to make sure the resources included in your assembly exist before that assembly is created.
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">
  <id>jar-with-dependencies</id>
  <formats>
    <format>jar</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <dependencySets>
    <dependencySet>
      <unpack>true</unpack>
      <scope>runtime</scope>
    </dependencySet>
  </dependencySets>
  <fileSets>
    <fileSet>
      <directory>${project.build.outputDirectory}</directory>
    </fileSet>
  </fileSets>
</assembly>
}}}
 
 
!!!Create an executable jar
 
{{{
<project>
  [...]
  <build>
    [...]
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>2.2-beta-5</version>
        <configuration>
          [...]
          <archive>
            <manifest>
              <mainClass>org.sample.App</mainClass>
            </manifest>
          </archive>
        </configuration>
        [...]
      </plugin>
      [...]
</project>


}}}
==The "single" Goal==


!!!Create an assembly file without any suffix
More details available here: http://maven.apache.org/components/plugins/maven-assembly-plugin/single-mojo.html


==Creating Two Assemblies for the Same Project==


By default, the assembly name is the &lt;projectname&gt;-&lt;assemblyid&gt;.&lt;ext&gt; If I just want it to be &lt;projectname&gt;.&lt;ext&gt;, don't use any
In order to create two (or more) assemblies for the same project, specify two (or more) <executions> elements.
{{{
    <id>...</id>
}}}
in the assembly descriptor.


!!!Creating two assemblies for the same project
=Other Assembly Use Cases=


{{{
<blockquote style="background-color: #f9f9f9; border: solid thin lightgrey;">
<plugin>
:
  <artifactId>maven-assembly-plugin</artifactId>
:[[Maven ZIP Artifact|ZIP  Artifact]]
      <executions>
:
          <execution>
:[[Maven JAR with Dependencies|JAR with Dependencies]]
              <id>jar-with-all-dependencies</id>
:
      <phase>package</phase>
:[[Maven Executable JAR|Executable JAR]]
              <goals>
:
                  <goal>single</goal>
:[[Building a Maven Complex Release Artifact]]
              </goals>
:
              <configuration>
</blockquote>
                  <descriptors>
                      <descriptor>src/main/assembly/jar-with-all-dependencies.xml</descriptor>
                  </descriptors>
                  <archive>
                      <manifest>
                          <mainClass>${exec.main.class}</mainClass>
                      </manifest>
                  </archive>
              </configuration>
          </execution>
          <execution>
              <id>distribution-bundle</id>
              <phase>package</phase>
              <goals>
                    <goal>single</goal>
              </goals>
              <configuration>
                    <descriptors>
                            <descriptor>src/main/assembly/distribution-bundle.xml</descriptor>
                    </descriptors>
              </configuration>
          </execution>
          </executions>
</plugin>
}}}
 
!!!Directly Specifying the Name of the Assembly Result File
 
{{{
    <build>
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <configuration>
                    <finalName>BLAH-${project.version}</finalName>
                    ...
}}}

Latest revision as of 15:21, 21 December 2016

External

Internal

Overview

The assembly plugin provide a standard way to aggregate complex artifacts using the project modules artifacts, dependencies, documentation and arbitrary files. The plugin produces a single distributable archive. A module has only one artifact - usually a JAR - but we may want to distribute that JAR together with documentation, source and supporting scripts in the form or an "atomic" archive, usually created for an official release. The assembly plugin does that.

Concepts

Assembly

An assembly is an single artifact produced by aggregating artifacts produced by modules, dependencies, documentation and arbitrary files. The assembly is built according to a specification formalized in the assembly descriptor.

The Name of the Assembly Artifact

By default, the name of the assembly artifact is generated according to the pattern artifactId-version-assemblyId.extension, where:

  • "artifactId" is the value of the <artifactId> element for the project (root or sub-module) that executes the assembly plugin.
  • "version" is the value of the <version> element for the project (root or sub-module) that executes the assembly plugin.
  • "assemblyId" is the value of the <id> element for the assembly descriptor that drives the plugin. The assembly ID is used as a classifier in the artifact name. In some cases, you may not want that; to configure Maven not to include it, see section "Prevent the Use of assemblyId in the Artifact Name" below. For more details on the <id> element, see Custom Maven Assembly Descriptors - the AssemblyID.
  • "extension" is dictated by the <format> element of the assembly descriptor. For more details see Custom Maven Assembly Descriptors.

<finalName>

The base name of the assembly artifact can be overridden using the <finalName> assembly plugin configuration element:

  ...
  <configuration>
      <finalName>someFinalName</finalName>
      ...
  </configuration>
  ...

For the configuration presented above, the value specified as <finalName> is prepended to the assemblyId classifier and the extension, as follows: someFinalName-assemblyId.extension Note that the <finalName> may include system properties, such as ${project.version}, which will be de-referenced.

Experience has shown that is best if we use <finalName> to name the assembly artifact. It offers more flexibility, as particular values for "artifactId" may interfere with the build process. We recommend using a "release" module with a "release" artifactId, and naming the assembly with <finalName>. However, as explained in the "<finalName>" section, the custom finalName is only used to generate the artifact file in the local target directory. The artifact file installed in the artifact repository will still be named "release-..."

Prevent the Use of assemblyId in the Artifact Name

In order to prevent the inclusion of the assemblyId value in the artifact name, use the following configuration element:

  ...
  <configuration>
      <finalName>someFinalName</finalName>
      <appendAssemblyId>false</appendAssemblyId>
      ...
  </configuration>
  ...

For more details about the plugin configuration, see "Plugin Configuration" section, below.

Assembly Descriptor

An assembly 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. It can also contain instructions to set specific permissions, etc. Maven offers a set of predefined assembly descriptors, described below. Custom assembly descriptors can also be created.

Pre-defined Assembly Descriptors

Custom Assembly Descriptors

Custom Maven Assembly Descriptors

Plugin Configuration

<project>
    ...
    <build>
        ...
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>2.6</version>
                <configuration>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                </configuration>
            </plugin>
        </plugins>
        ...
    </build>
    ...      
</project>

Always update the plugin version to the latest stable version, to get reproducible builds.

Use <descriptorRefs> (one or more) when the pre-defined assembly descriptors are sufficient. For a list of available pre-defined assembly descriptors, see "Pre-defined Assembly Descriptors" section.

In case a custom assembly descriptor is needed, it is declared as follows:

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

For more details on custom assembly descriptors, see the "Assembly Descriptor" section.

Plugin Execution

The plugin has a single goal "single". The assembly plugin can be executed in isolation, or it can be executed during the build process of the project.

To execute the plugin in isolation:

mvn assembly:single

To execute the plugin as part of the build process, the plugin has to be first declared and configured, as described in the "Plugin Configuration" section, and then its "single" goal must be bound to the project lifecycle by associating it usually with the "package" phase, as follows:

<project>
    ...
    <build>
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>...</version>
                <configuration>
                    ...
                </configuration>
                <executions>
                    <execution>
                        <id>assembly-execution</id>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
       ...
</project>

Once the plug-in is bound to the project lifecycle, simply execute the normal package phase from the default lifecycle to create a project assembly:

mvn package

When this build completes, the assembly file is available in the target directory and has a name similar to the following: artifactId-version-jar-with-dependencies.jar (if "jar-with-dependencies" pre-defined assembly descriptor was used).

In case the assembly doesn't require binaries, so the package phase does not need to be executed, the assembly's goal can be bound to a different project phase. You should be careful to make sure the resources included in your assembly exist before that assembly is created.

The "single" Goal

More details available here: http://maven.apache.org/components/plugins/maven-assembly-plugin/single-mojo.html

Creating Two Assemblies for the Same Project

In order to create two (or more) assemblies for the same project, specify two (or more) <executions> elements.

Other Assembly Use Cases

ZIP Artifact
JAR with Dependencies
Executable JAR
Building a Maven Complex Release Artifact