src/site/apt/index.apt - maven-assembly-plugin - Git at Google

   ---
   Introduction
   ---
   John Casey
   Edwin Punzalan
   ---
   2 November 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


 Maven Assembly Plugin

 ~~ * Status
 ~~
 ~~   <<Current Assembly Plugin Version is: 2.1>>
 ~~
 * Introduction

   Do you want to create a binary distribution from a Maven project that includes
   supporting scripts, configuration files, and all runtime dependencies?  You
   need to use the Assembly Plugin to create a distribution for your project.

   This plugin generates "assemblies". It is the equivalent of the Maven 1
   distribution plug-in.  This plugin provides the capability to create binary
   and source distributions.  These distributions (assemblies) are defined using
   an assembly descriptor.  You can write your own {{{assembly.html}descriptor}}
   to create a custom assembly, or you can reuse one of the three
   {{{descriptor-refs.html}pre-defined assemblies}}.

   Currently it can create distributions in the following formats:

     * zip

     * tar.gz

     * tar.bz2

     * jar

     * dir

     * war

     * and any other format that the ArchiveManager has been configured for

   To use the Assembly Plugin in Maven 2, you simply need to:

     * choose or write the assembly descriptor to use,

     * configure the Assembly Plugin in your project's pom.xml, and

     * run "mvn assembly:assembly" on your project.

   To write your own custom assembly, you will need to refer to the
   {{{assembly.html}Assembly Descriptor Format}} reference.


 What is an Assembly?

   An "assembly" is a group of files, directories, and dependencies that are
   assembled into an archive format and distributed.  For example, assume that
   a Maven project defines a single JAR artifact that contains both a console
   application and a Swing application.  Such a project could define two
   "assemblies" that bundle the application with a different set of supporting
   scripts and dependency sets.  One assembly would be the assembly for the
   console application, and the other assembly could be a Swing application
   bundled with a slightly different set of dependencies.

   The Assembly Plugin provides a descriptor format which allows you to define
   an arbitrary assembly of files and directories from a project.  For example,
   if your Maven 2 project contains the directory "src/main/bin", you can
   instruct the Assembly Plugin to copy the contents of this directory to the
   "bin" directory of an assembly and to change the permissions of the files in
   the "bin" directory to UNIX mode 755.  The parameters for configuring this
   behavior are supplied to the Assembly Plugin by way of the
   {{{assembly.html}assembly descriptor}}.


 The Maven Assembly Plugin

   The Assembly Plugin for Maven 2.0 is primarily intended to allow users to
   aggregate the project output along with its dependencies, modules, site
   documentation, and other files into a single distributable archive.

   Your project build can build distribution assemblies easily, using one of the
   convenient, prefabricated assembly descriptors. These descriptors handle many
   common operations, such as packaging a project's artifact along with its
   dependencies in a single jar. Alternatively, your project can provide its own
   descriptor and assume a much higher level of control over how dependencies,
   modules, file-sets, and individual files are packaged in the assembly.


 * Goals Overview

   The Assembly Plugin has six goals:

   * {{{assembly-mojo.html}assembly:assembly}} Assembles an application bundle
   or distribution based on an assembly descriptor into an archive of a chosen
   format. Executed from the command-line.

   * {{{attached-mojo.html}assembly:attached}} Assembles an application bundle
   or distribution from an assembly descriptor into an archive of a chosen
   format. Executed within the Maven Lifecycle.

   * {{{directory-mojo.html}assembly:directory}} Assembles an application bundle
   from an assembly descriptor or distribution into a directory. Executed from
   the command-line.*

   * {{{directory-inline-mojo.html}assembly:directory-inline}} Assembles an
   application bundle or distribution into a directory. Executed within the Maven
   Lifecycle.*

   * {{{unpack-mojo.html}assembly:unpack}} Assembles an application bundle or
   distribution from an assembly descriptor into an archive of a chosen format
   but with the dependencies unpacked inside the archive.

   * {{{single-mojo.html}assembly:single}} An assembly mojo created as a
   work-around for lifecycle issues until addressed in the Maven 2.1 release.

   * {{{directory-single-mojo.html}assembly:directory-single}} An assembly mojo
   created as a work-around for lifecycle issues until addressed in the Maven 2.1
   release. This mojo will generate an assembly into a directory.

   []

   \* <<NOTE:>> Directory-based assemblies cannot be attached to a project for
   deployment or installation, since they do not represent a single,
   self-contained file which can be transferred across network connections.

 * Assembly Descriptor Schemas (XSD)

   * {{{http://maven.apache.org/xsd/assembly-1.1.0-SNAPSHOT.xsd}http://maven.apache.org/xsd/assembly-1.1.0-SNAPSHOT.xsd}} (for version 2.2-SNAPSHOT and higher)

   * {{{http://maven.apache.org/xsd/assembly-1.0.0.xsd}http://maven.apache.org/xsd/assembly-1.0.0.xsd}} (for versions 2.1 and below)

   []


 * Usage

   Instructions on how to use the Assembly Plugin can be found
   {{{usage.html}here}}.


 * Examples

   To provide you with better understanding on some usages of the Assembly
   Plugin, you can take a look into the examples which can be found
   {{{examples/index.html}here}}.
	---
	Introduction
	---
	John Casey
	Edwin Punzalan
	---
	2 November 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


	Maven Assembly Plugin

	~~ * Status
	~~
	~~ <<Current Assembly Plugin Version is: 2.1>>
	~~
	* Introduction

	Do you want to create a binary distribution from a Maven project that includes
	supporting scripts, configuration files, and all runtime dependencies? You
	need to use the Assembly Plugin to create a distribution for your project.

	This plugin generates "assemblies". It is the equivalent of the Maven 1
	distribution plug-in. This plugin provides the capability to create binary
	and source distributions. These distributions (assemblies) are defined using
	an assembly descriptor. You can write your own {{{assembly.html}descriptor}}
	to create a custom assembly, or you can reuse one of the three
	{{{descriptor-refs.html}pre-defined assemblies}}.

	Currently it can create distributions in the following formats:

	* zip

	* tar.gz

	* tar.bz2

	* jar

	* dir

	* war

	* and any other format that the ArchiveManager has been configured for

	To use the Assembly Plugin in Maven 2, you simply need to:

	* choose or write the assembly descriptor to use,

	* configure the Assembly Plugin in your project's pom.xml, and

	* run "mvn assembly:assembly" on your project.

	To write your own custom assembly, you will need to refer to the
	{{{assembly.html}Assembly Descriptor Format}} reference.


	What is an Assembly?

	An "assembly" is a group of files, directories, and dependencies that are
	assembled into an archive format and distributed. For example, assume that
	a Maven project defines a single JAR artifact that contains both a console
	application and a Swing application. Such a project could define two
	"assemblies" that bundle the application with a different set of supporting
	scripts and dependency sets. One assembly would be the assembly for the
	console application, and the other assembly could be a Swing application
	bundled with a slightly different set of dependencies.

	The Assembly Plugin provides a descriptor format which allows you to define
	an arbitrary assembly of files and directories from a project. For example,
	if your Maven 2 project contains the directory "src/main/bin", you can
	instruct the Assembly Plugin to copy the contents of this directory to the
	"bin" directory of an assembly and to change the permissions of the files in
	the "bin" directory to UNIX mode 755. The parameters for configuring this
	behavior are supplied to the Assembly Plugin by way of the
	{{{assembly.html}assembly descriptor}}.


	The Maven Assembly Plugin

	The Assembly Plugin for Maven 2.0 is primarily intended to allow users to
	aggregate the project output along with its dependencies, modules, site
	documentation, and other files into a single distributable archive.

	Your project build can build distribution assemblies easily, using one of the
	convenient, prefabricated assembly descriptors. These descriptors handle many
	common operations, such as packaging a project's artifact along with its
	dependencies in a single jar. Alternatively, your project can provide its own
	descriptor and assume a much higher level of control over how dependencies,
	modules, file-sets, and individual files are packaged in the assembly.


	* Goals Overview

	The Assembly Plugin has six goals:

	* {{{assembly-mojo.html}assembly:assembly}} Assembles an application bundle
	or distribution based on an assembly descriptor into an archive of a chosen
	format. Executed from the command-line.

	* {{{attached-mojo.html}assembly:attached}} Assembles an application bundle
	or distribution from an assembly descriptor into an archive of a chosen
	format. Executed within the Maven Lifecycle.

	* {{{directory-mojo.html}assembly:directory}} Assembles an application bundle
	from an assembly descriptor or distribution into a directory. Executed from
	the command-line.*

	* {{{directory-inline-mojo.html}assembly:directory-inline}} Assembles an
	application bundle or distribution into a directory. Executed within the Maven
	Lifecycle.*

	* {{{unpack-mojo.html}assembly:unpack}} Assembles an application bundle or
	distribution from an assembly descriptor into an archive of a chosen format
	but with the dependencies unpacked inside the archive.

	* {{{single-mojo.html}assembly:single}} An assembly mojo created as a
	work-around for lifecycle issues until addressed in the Maven 2.1 release.

	* {{{directory-single-mojo.html}assembly:directory-single}} An assembly mojo
	created as a work-around for lifecycle issues until addressed in the Maven 2.1
	release. This mojo will generate an assembly into a directory.

	[]

	\* <<NOTE:>> Directory-based assemblies cannot be attached to a project for
	deployment or installation, since they do not represent a single,
	self-contained file which can be transferred across network connections.

	* Assembly Descriptor Schemas (XSD)

	* {{{http://maven.apache.org/xsd/assembly-1.1.0-SNAPSHOT.xsd}http://maven.apache.org/xsd/assembly-1.1.0-SNAPSHOT.xsd}} (for version 2.2-SNAPSHOT and higher)

	* {{{http://maven.apache.org/xsd/assembly-1.0.0.xsd}http://maven.apache.org/xsd/assembly-1.0.0.xsd}} (for versions 2.1 and below)

	[]


	* Usage

	Instructions on how to use the Assembly Plugin can be found
	{{{usage.html}here}}.


	* Examples

	To provide you with better understanding on some usages of the Assembly
	Plugin, you can take a look into the examples which can be found
	{{{examples/index.html}here}}.