src/site/apt/usage.apt - maven-plugins - Git at Google

   ---
   Configuration and Usage
   ---
   John Casey
   ---
   12-May-2006

 ~~ Copyright 2006 The Apache Software Foundation.
 ~~
 ~~ Licensed under the Apache License, Version 2.0 (the "License");
 ~~ you may not use this file except in compliance with the License.
 ~~ You may obtain a copy of the License at
 ~~
 ~~      http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing, software
 ~~ distributed under the License is distributed on an "AS IS" BASIS,
 ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 ~~ See the License for the specific language governing permissions and
 ~~ limitations under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/guides/mini/guide-apt-format.html

 Configuration and Usage

 * Introduction

   This document is intended to provide instructions for using the
   maven-assembly-plugin. In order for this discussion to be useful, it's
   critical to cover two topics: configuration of the plugin - both inside the
   POM and, where possible, from the command line - and the different execution
   styles. For the sake of clarity, we'll cover configuration before execution.

 * Configuring the Assembly Plugin

   Getting started with the Assembly Plugin is pretty simple. If you're using one
   of the prefabricated assembly descriptors, you just tell it which one; if
   you're using a custom assembly descriptor, you give it the path to the
   descriptor. Note that a single invocation of the Assembly Plugin can actually
   produce assemblies from multiple descriptors, allowing you maximum flexibility
   to customize the suite of binaries your project produces. When the assembly is
   created it will use the assemblyId as the artifact's classifier and will attach
   the created assembly to the project and will be uploaded into the repository
   on an install and deploy goal.


   For example, imagine that our project produces a jar. If we want to create an
   assembly binary that includes our project's dependencies, we can take
   advantage of one of the Assembly Plugin's prefabricated descriptors, as
   follows:

 +---+
 <project>
   [...]
   <build>
     [...]
     <plugins>
       <plugin>
         <!-- NOTE: We don't need a groupId specification because the group is
              org.apache.maven.plugins ...which is assumed by default.
          -->
         <artifactId>maven-assembly-plugin</artifactId>
         <configuration>
           <descriptorRefs>
             <descriptorRef>jar-with-dependencies</descriptorRef>
           </descriptorRefs>
         </configuration>
         [...]
 </project>
 +---+

   Note that the Assembly Plugin allows you to specify multiple
   <<<descriptorRefs>>> at once, to produce multiple types of assemblies in a
   single invocation.

   Alternatively, we've created a custom assembly descriptor called
   <<<src.xml>>> in the <<<src/assembly>>> directory (see the
   {{{#Resources}Resources}} section for more information), we can tell the
   Assembly Plugin to use it instead:

 +---+
 <project>
   [...]
   <build>
     [...]
     <plugins>
       <plugin>
         <artifactId>maven-assembly-plugin</artifactId>
         <configuration>
           <descriptors>
             <descriptor>src/assembly/src.xml</descriptor>
           </descriptors>
         </configuration>
         [...]
 </project>
 +---+

   Again, note that we could specify multiple custom assembly descriptors here.
   Additionally, it's possible to specify a mixture of <<<descriptors>>> and
   <<<descriptorRefs>>> within the same configuration.

   <<NOTE:>> Many other configuration options are available for the various mojos
   in the Assembly Plugin. For more information, see the
   {{{examples/index.html}examples section}} or the {{{plugin-info.html}plugin
   parameter documentation}}.

 * Executing: Building an Assembly

   Once you've configured the various <<<descriptors>>> and <<<descriptorRefs>>>
   for the assemblies you want the project to produce, it's time to determine how
   you want to build them.

   Currently, there are two basic approaches to building assemblies: as a
   dedicated build action, or bound to a phase of the normal build lifecycle.
   Beyond this, it's also possible to have the Assembly Plugin simply create an
   assembly directory for any given <<<descriptor>>> or <<<descriptorRef>>>,
   instead of creating archives.

 ** Building an Assembly as a Standalone Process

   First, let's examine how we can build an assembly directly, as a process
   separate from the normal build lifecycle. In this case, assemblies won't be
   produced when the normal build is executed, only in special circumstances.

   <<NOTE:>> Invoking the <<<assembly>>> and <<<directory>>> mojos will cause
   Maven to build the project using the normal lifecycle, up to the <<<package>>>
   phase. Because many assemblies will contain compiled classes and other
   binaries, it's reasonable to assume that the package phase will be required to
   ensure those binaries exist and have been tested. The main advantage of
   producing an assembly in this way is to avoid producing it as part of your
   normal build process. In some cases, you may only want to create an assembly
   periodically; these mojos provide two ways to accomplish that goal.

 *** Normal Assemblies

   You can build an assembly directly by executing:

 +---+
 mvn assembly:assembly
 +---+

   When this build completes, you should see a file in the target directory with
   a name similar to the following:

 +---+
 target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar
 +---+

   Notice the artifact classifier, between the end of the version and the
   beginning of the file extension, <<<jar-with-dependencies>>>. This is the
   <<<id>>> of the assembly descriptor used to create this artifact.

 *** Assembly Directories

   You can construct an assembly directory directly from the command line by
   executing:

 +---+
 mvn assembly:directory
 +---+

   When completed, you should see a directory structure similar to this:

 +---+
 target
 |-- sample-1.0-SNAPSHOT-jar-with-dependencies
 |   |-- META-INF
 |   |   |-- MANIFEST.MF
 |   |   `-- maven
 |   |       `-- org.sample
 |   |           `-- sample
 |   |               |-- pom.properties
 |   |               `-- pom.xml
 |   |-- junit
 [...]
 |   |       `-- TestRunner.class
 |   |-- junit3.8.1
 |   |-- org
 |   |   `-- sample
 |   |       `-- App.class
 |   `-- stylesheet.css
 +---+

 ** Building an Assembly as Part of the Build Lifecycle

   If you need to ensure that assemblies are produced whenever your project
   builds, or when a particular profile is activated (also useful for configuring
   other plugins during this special process), then the following two mojos are
   probably what you're looking for. The <<<attached>>> and
   <<<directory-inline>>> mojos are functional counterparts of the mojos
   discussed above, except that they are meant to bind into the default build
   lifecycle.

   The <<<assembly>>> mojo forces a <<<package>>> phase build to execute, in
   order to guarantee the availability of project binaries. Unfortunately, this
   currently means that binding the <<<assembly>>> mojo to the default lifecycle
   will cause Maven to execute the build twice - once for the main process, and
   once again in a forked lifecycle which is spawned by the <<<assembly>>> mojo
   itself.

   By contrast, the <<<attached>>> mojo assumes that the build has already
   produced project binaries or whatever else it needs prior to building the
   assembly itself. Because they depend on correct binding to the lifecycle in
   order to gain access to the files required by your project assembly, the
   <<<attached>>> and <<<directory-inline>>> mojos require the user to have much
   more intimate knowledge of the build process.

 *** Normal Assemblies

   To bind the <<<attached>>> mojo to a project's build lifecycle, you can add
   this configuration (assuming you're using the <<<jar-with-dependencies>>>
   prefabricated descriptor):

 +---+
 <project>
   [...]
   <build>
     [...]
     <plugins>
       <plugin>
         <artifactId>maven-assembly-plugin</artifactId>
         <configuration>
           <descriptorRefs>
             <descriptorRef>jar-with-dependencies</descriptorRef>
           </descriptorRefs>
         </configuration>
         <executions>
           <execution>
             <id>make-assembly</id> <!-- this is used for inheritance merges -->
             <phase>packaging</phase> <!-- append to the packaging phase. -->
             <goals>
               <goal>attached</goal> <!-- goals == mojos -->
             </goals>
           </execution>
         </executions>
       </plugin>
       [...]
 </project>
 +---+

   Then, to create a project assembly, simple execute the normal <<<package>>>
   phase from the default lifecycle:

 +---+
 mvn package
 +---+

   When this build completes, you should see a file in the target directory with
   a name similar to the following:

 +---+
 target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar
 +---+

   Notice the artifact classifier, between the end of the version and the
   beginning of the file extension, <<<jar-with-dependencies>>>. This is the
   <<<id>>> of the assembly descriptor used to create this artifact.

 *** Assembly Directories

   If instead you want to bind the <<<directory-inline>>> mojo to a project's
   build lifecycle - so you can construct a directory containing your assembly -
   you can add this configuration (assuming you're using the
   <<<jar-with-dependencies>>> prefabricated descriptor):

 +---+
 <project>
   [...]
   <build>
     [...]
     <plugins>
       <plugin>
         <artifactId>maven-assembly-plugin</artifactId>
         <configuration>
           <descriptorRefs>
             <descriptorRef>jar-with-dependencies</descriptorRef>
           </descriptorRefs>
         </configuration>
         <executions>
           <execution>
             <id>make-assembly</id> <!-- this is used for inheritance merges -->
             <phase>packaging</phase> <!-- append to the packaging phase. -->
             <goals>
               <goal>directory-inline</goal> <!-- goals == mojos -->
             </goals>
           </execution>
         </executions>
       </plugin>
       [...]
 </project>
 +---+

   Then, to create a project assembly, simple execute the normal <<<package>>>
   phase from the default lifecycle:

 +---+
 mvn package
 +---+

   When completed, you should see a directory structure similar to this:

 +---+
 target
 |-- sample-1.0-SNAPSHOT-jar-with-dependencies
 |   |-- META-INF
 |   |   |-- MANIFEST.MF
 |   |   `-- maven
 |   |       `-- org.sample
 |   |           `-- sample
 |   |               |-- pom.properties
 |   |               `-- pom.xml
 |   |-- junit
 [...]
 |   |       `-- TestRunner.class
 |   |-- junit3.8.1
 |   |-- org
 |   |   `-- sample
 |   |       `-- App.class
 |   `-- stylesheet.css
 +---+

 * Advanced Configuration

   As you've no doubt noticed, the Assembly Plugin can be a very useful way to
   create a self-contained binary artifact for your project, among many other
   things. However, once you've created this self-contained jar, you will
   probably want the ability to execute it using the <<<-jar>>> JVM switch.

   To accommodate this, the Assembly Plugin supports configuration of an
   <<<\<archive\>>>> element which is identical to that supported by the
   <<<maven-jar-plugin>>> (see {{{#Resources}Resources}}). Using this
   configuration, it's easy to configure the <<<Main-Class>>> attribute of the
   jar manifest:

 +---+
 <project>
   [...]
   <build>
     [...]
     <plugins>
       <plugin>
         <artifactId>maven-assembly-plugin</artifactId>
         <configuration>
           [...]
           <archive>
             <manifest>
               <mainClass>org.sample.App</mainClass>
             </manifest>
           </archive>
         </configuration>
         [...]
       </plugin>
       [...]
 </project>
 +---+

   If we add this configuration to the <<<attached>>> mojo example above and
   rebuild, we will see an entry like this in the META-INF/MANIFEST.MF file of
   the resulting jar:

 +---+
 [...]
 Main-Class: org.sample.App
 +---+

   For more information on advanced configuration for the Assembly Plugin, see
   the {{{#Resources}Resources}} section.

 ** GOTCHA!

   At this point, the directory-oriented mojos - <<<directory>>> and
   <<<directory-inline>>> - <<do not>> support the <<<\<archive\>>>>
   configuration element.

 * {Resources}

   [[1]] For more information on writing your own assembly descriptor, read the
         {{{assembly.html}Assembly Descriptor}}

   [[2]] For more information about the <<<maven-jar-plugin>>>, look
         {{{http://maven.apache.org/plugins/maven-jar-plugin/}here}}.

   [[3]] For more information on advanced <<<maven-assembly-plugin>>>
         configuration, see the {{{examples/index.html}examples}}.

   []
	---
	Configuration and Usage
	---
	John Casey
	---
	12-May-2006

	~~ Copyright 2006 The Apache Software Foundation.
	~~
	~~ Licensed under the Apache License, Version 2.0 (the "License");
	~~ you may not use this file except in compliance with the License.
	~~ You may obtain a copy of the License at
	~~
	~~ http://www.apache.org/licenses/LICENSE-2.0
	~~
	~~ Unless required by applicable law or agreed to in writing, software
	~~ distributed under the License is distributed on an "AS IS" BASIS,
	~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	~~ See the License for the specific language governing permissions and
	~~ limitations under the License.

	~~ NOTE: For help with the syntax of this file, see:
	~~ http://maven.apache.org/guides/mini/guide-apt-format.html

	Configuration and Usage

	* Introduction

	This document is intended to provide instructions for using the
	maven-assembly-plugin. In order for this discussion to be useful, it's
	critical to cover two topics: configuration of the plugin - both inside the
	POM and, where possible, from the command line - and the different execution
	styles. For the sake of clarity, we'll cover configuration before execution.

	* Configuring the Assembly Plugin

	Getting started with the Assembly Plugin is pretty simple. If you're using one
	of the prefabricated assembly descriptors, you just tell it which one; if
	you're using a custom assembly descriptor, you give it the path to the
	descriptor. Note that a single invocation of the Assembly Plugin can actually
	produce assemblies from multiple descriptors, allowing you maximum flexibility
	to customize the suite of binaries your project produces. When the assembly is
	created it will use the assemblyId as the artifact's classifier and will attach
	the created assembly to the project and will be uploaded into the repository
	on an install and deploy goal.


	For example, imagine that our project produces a jar. If we want to create an
	assembly binary that includes our project's dependencies, we can take
	advantage of one of the Assembly Plugin's prefabricated descriptors, as
	follows:

	+---+
	<project>
	[...]
	<build>
	[...]
	<plugins>
	<plugin>
	<!-- NOTE: We don't need a groupId specification because the group is
	org.apache.maven.plugins ...which is assumed by default.
	-->
	<artifactId>maven-assembly-plugin</artifactId>
	<configuration>
	<descriptorRefs>
	<descriptorRef>jar-with-dependencies</descriptorRef>
	</descriptorRefs>
	</configuration>
	[...]
	</project>
	+---+

	Note that the Assembly Plugin allows you to specify multiple
	<<<descriptorRefs>>> at once, to produce multiple types of assemblies in a
	single invocation.

	Alternatively, we've created a custom assembly descriptor called
	<<<src.xml>>> in the <<<src/assembly>>> directory (see the
	{{{#Resources}Resources}} section for more information), we can tell the
	Assembly Plugin to use it instead:

	+---+
	<project>
	[...]
	<build>
	[...]
	<plugins>
	<plugin>
	<artifactId>maven-assembly-plugin</artifactId>
	<configuration>
	<descriptors>
	<descriptor>src/assembly/src.xml</descriptor>
	</descriptors>
	</configuration>
	[...]
	</project>
	+---+

	Again, note that we could specify multiple custom assembly descriptors here.
	Additionally, it's possible to specify a mixture of <<<descriptors>>> and
	<<<descriptorRefs>>> within the same configuration.

	<<NOTE:>> Many other configuration options are available for the various mojos
	in the Assembly Plugin. For more information, see the
	{{{examples/index.html}examples section}} or the {{{plugin-info.html}plugin
	parameter documentation}}.

	* Executing: Building an Assembly

	Once you've configured the various <<<descriptors>>> and <<<descriptorRefs>>>
	for the assemblies you want the project to produce, it's time to determine how
	you want to build them.

	Currently, there are two basic approaches to building assemblies: as a
	dedicated build action, or bound to a phase of the normal build lifecycle.
	Beyond this, it's also possible to have the Assembly Plugin simply create an
	assembly directory for any given <<<descriptor>>> or <<<descriptorRef>>>,
	instead of creating archives.

	** Building an Assembly as a Standalone Process

	First, let's examine how we can build an assembly directly, as a process
	separate from the normal build lifecycle. In this case, assemblies won't be
	produced when the normal build is executed, only in special circumstances.

	<<NOTE:>> Invoking the <<<assembly>>> and <<<directory>>> mojos will cause
	Maven to build the project using the normal lifecycle, up to the <<<package>>>
	phase. Because many assemblies will contain compiled classes and other
	binaries, it's reasonable to assume that the package phase will be required to
	ensure those binaries exist and have been tested. The main advantage of
	producing an assembly in this way is to avoid producing it as part of your
	normal build process. In some cases, you may only want to create an assembly
	periodically; these mojos provide two ways to accomplish that goal.

	*** Normal Assemblies

	You can build an assembly directly by executing:

	+---+
	mvn assembly:assembly
	+---+

	When this build completes, you should see a file in the target directory with
	a name similar to the following:

	+---+
	target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar
	+---+

	Notice the artifact classifier, between the end of the version and the
	beginning of the file extension, <<<jar-with-dependencies>>>. This is the
	<<<id>>> of the assembly descriptor used to create this artifact.

	*** Assembly Directories

	You can construct an assembly directory directly from the command line by
	executing:

	+---+
	mvn assembly:directory
	+---+

	When completed, you should see a directory structure similar to this:

	+---+
	target
	\|-- sample-1.0-SNAPSHOT-jar-with-dependencies
	\| \|-- META-INF
	\| \| \|-- MANIFEST.MF
	\| \| `-- maven
	\| \| `-- org.sample
	\| \| `-- sample
	\| \| \|-- pom.properties
	\| \| `-- pom.xml
	\| \|-- junit
	[...]
	\| \| `-- TestRunner.class
	\| \|-- junit3.8.1
	\| \|-- org
	\| \| `-- sample
	\| \| `-- App.class
	\| `-- stylesheet.css
	+---+

	** Building an Assembly as Part of the Build Lifecycle

	If you need to ensure that assemblies are produced whenever your project
	builds, or when a particular profile is activated (also useful for configuring
	other plugins during this special process), then the following two mojos are
	probably what you're looking for. The <<<attached>>> and
	<<<directory-inline>>> mojos are functional counterparts of the mojos
	discussed above, except that they are meant to bind into the default build
	lifecycle.

	The <<<assembly>>> mojo forces a <<<package>>> phase build to execute, in
	order to guarantee the availability of project binaries. Unfortunately, this
	currently means that binding the <<<assembly>>> mojo to the default lifecycle
	will cause Maven to execute the build twice - once for the main process, and
	once again in a forked lifecycle which is spawned by the <<<assembly>>> mojo
	itself.

	By contrast, the <<<attached>>> mojo assumes that the build has already
	produced project binaries or whatever else it needs prior to building the
	assembly itself. Because they depend on correct binding to the lifecycle in
	order to gain access to the files required by your project assembly, the
	<<<attached>>> and <<<directory-inline>>> mojos require the user to have much
	more intimate knowledge of the build process.

	*** Normal Assemblies

	To bind the <<<attached>>> mojo to a project's build lifecycle, you can add
	this configuration (assuming you're using the <<<jar-with-dependencies>>>
	prefabricated descriptor):

	+---+
	<project>
	[...]
	<build>
	[...]
	<plugins>
	<plugin>
	<artifactId>maven-assembly-plugin</artifactId>
	<configuration>
	<descriptorRefs>
	<descriptorRef>jar-with-dependencies</descriptorRef>
	</descriptorRefs>
	</configuration>
	<executions>
	<execution>
	<id>make-assembly</id> <!-- this is used for inheritance merges -->
	<phase>packaging</phase> <!-- append to the packaging phase. -->
	<goals>
	<goal>attached</goal> <!-- goals == mojos -->
	</goals>
	</execution>
	</executions>
	</plugin>
	[...]
	</project>
	+---+

	Then, to create a project assembly, simple execute the normal <<<package>>>
	phase from the default lifecycle:

	+---+
	mvn package
	+---+

	When this build completes, you should see a file in the target directory with
	a name similar to the following:

	+---+
	target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar
	+---+

	Notice the artifact classifier, between the end of the version and the
	beginning of the file extension, <<<jar-with-dependencies>>>. This is the
	<<<id>>> of the assembly descriptor used to create this artifact.

	*** Assembly Directories

	If instead you want to bind the <<<directory-inline>>> mojo to a project's
	build lifecycle - so you can construct a directory containing your assembly -
	you can add this configuration (assuming you're using the
	<<<jar-with-dependencies>>> prefabricated descriptor):

	+---+
	<project>
	[...]
	<build>
	[...]
	<plugins>
	<plugin>
	<artifactId>maven-assembly-plugin</artifactId>
	<configuration>
	<descriptorRefs>
	<descriptorRef>jar-with-dependencies</descriptorRef>
	</descriptorRefs>
	</configuration>
	<executions>
	<execution>
	<id>make-assembly</id> <!-- this is used for inheritance merges -->
	<phase>packaging</phase> <!-- append to the packaging phase. -->
	<goals>
	<goal>directory-inline</goal> <!-- goals == mojos -->
	</goals>
	</execution>
	</executions>
	</plugin>
	[...]
	</project>
	+---+

	Then, to create a project assembly, simple execute the normal <<<package>>>
	phase from the default lifecycle:

	+---+
	mvn package
	+---+

	When completed, you should see a directory structure similar to this:

	+---+
	target
	\|-- sample-1.0-SNAPSHOT-jar-with-dependencies
	\| \|-- META-INF
	\| \| \|-- MANIFEST.MF
	\| \| `-- maven
	\| \| `-- org.sample
	\| \| `-- sample
	\| \| \|-- pom.properties
	\| \| `-- pom.xml
	\| \|-- junit
	[...]
	\| \| `-- TestRunner.class
	\| \|-- junit3.8.1
	\| \|-- org
	\| \| `-- sample
	\| \| `-- App.class
	\| `-- stylesheet.css
	+---+

	* Advanced Configuration

	As you've no doubt noticed, the Assembly Plugin can be a very useful way to
	create a self-contained binary artifact for your project, among many other
	things. However, once you've created this self-contained jar, you will
	probably want the ability to execute it using the <<<-jar>>> JVM switch.

	To accommodate this, the Assembly Plugin supports configuration of an
	<<<\<archive\>>>> element which is identical to that supported by the
	<<<maven-jar-plugin>>> (see {{{#Resources}Resources}}). Using this
	configuration, it's easy to configure the <<<Main-Class>>> attribute of the
	jar manifest:

	+---+
	<project>
	[...]
	<build>
	[...]
	<plugins>
	<plugin>
	<artifactId>maven-assembly-plugin</artifactId>
	<configuration>
	[...]
	<archive>
	<manifest>
	<mainClass>org.sample.App</mainClass>
	</manifest>
	</archive>
	</configuration>
	[...]
	</plugin>
	[...]
	</project>
	+---+

	If we add this configuration to the <<<attached>>> mojo example above and
	rebuild, we will see an entry like this in the META-INF/MANIFEST.MF file of
	the resulting jar:

	+---+
	[...]
	Main-Class: org.sample.App
	+---+

	For more information on advanced configuration for the Assembly Plugin, see
	the {{{#Resources}Resources}} section.

	** GOTCHA!

	At this point, the directory-oriented mojos - <<<directory>>> and
	<<<directory-inline>>> - <<do not>> support the <<<\<archive\>>>>
	configuration element.

	* {Resources}

	[[1]] For more information on writing your own assembly descriptor, read the
	{{{assembly.html}Assembly Descriptor}}

	[[2]] For more information about the <<<maven-jar-plugin>>>, look
	{{{http://maven.apache.org/plugins/maven-jar-plugin/}here}}.

	[[3]] For more information on advanced <<<maven-assembly-plugin>>>
	configuration, see the {{{examples/index.html}examples}}.

	[]