Maven assembly Plugin: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
Line 26: Line 26:
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.
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.


Maven offers a set of predefined assembly descriptors, described below. Custom assembly descriptors can also be created: http://maven.apache.org/components/plugins/maven-assembly-plugin/assembly.html.
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:
 
<blockquote style="background-color: AliceBlue; border: solid thin LightSteelBlue;">
:http://maven.apache.org/components/plugins/maven-assembly-plugin/assembly.html<br>
</blockquote>


===Pre-defined Assembly Descriptors===
===Pre-defined Assembly Descriptors===

Revision as of 02:51, 5 November 2016

External

Internal

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.

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.

Assembly ID

The assembly ID will become the assembly artifact classifier, present between the version and the extension.

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.

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:

http://maven.apache.org/components/plugins/maven-assembly-plugin/assembly.html

Pre-defined Assembly Descriptors

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

Plugin Execution

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:

To execute the plugin as part of the build process, bind the plugin's "single" goal to to the project lifecycle by associating it usually with the "package" phase, as follows:


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: Put placeholders: target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar .

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.

Building a Complex Release Artifact

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.


!!!External

  • [1]
  • [2]
  • Sonatype Assemblies [3]
  • Assembly Best Practices according to Sonatype [4]

!!!Internal

|[MavenFilesets] |[How to Exclude a File from the Final Artifact|MavenHOW2#HowToExcludeAFileFromTheFinalArtifact]

!!!Overview

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

!!!Notes

!!!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>
               <artifactId>maven-assembly-plugin</artifactId>
               <configuration>
                   <descriptors>
                       <descriptor>assembly.xml</descriptor>
                   </descriptors>
               </configuration>
               <executions>
                   <execution>
                       <id>make-assembly</id>
                       <phase>package</phase>
                       <goals>
                           <goal>single</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
           ...

}}}

!!assembly.xml

{{{ <assembly>

   <formats>
       <format>zip</format>
   </formats>
   <baseDirectory>.</baseDirectory>
   <includeBaseDirectory>false</includeBaseDirectory>
   <fileSets>
       <fileSet>
           <directory>archimedes-test-site</directory>
       </fileSet>
   </fileSets>

</assembly> }}}

!!!Jar With Dependencies

{{{ <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>

}}}

!!!Create an assembly file without any suffix


By default, the assembly name is the <projectname>-<assemblyid>.<ext> If I just want it to be <projectname>.<ext>, don't use any {{{

   <id>...</id>

}}} in the assembly descriptor.

!!!Creating two assemblies for the same project

{{{ <plugin>

  <artifactId>maven-assembly-plugin</artifactId>
     <executions>
         <execution>
             <id>jar-with-all-dependencies</id>

<phase>package</phase>

              <goals>
                  <goal>single</goal>
              </goals>
              <configuration>
                  <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>
                   ...

}}}