src/site/apt/index.apt.vm

  ---
  Introduction
  ---
  John Casey
  Edwin Punzalan
  ---
  2013-07-22
  ---

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you 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/doxia/references/apt-format.html

${project.name}

* Introduction

  The Assembly Plugin for Maven 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 can build distribution "assemblies" easily, using one of the
  convenient, {{{./descriptor-refs.html}prefabricated assembly descriptors}}.
  These descriptors handle many common operations, such as packaging a project's
  artifact along with generated documentation into a
  {{{./descriptor-refs.html#bin}single zip archive}}.
  Alternatively, your project can provide its own {{{./assembly.html}descriptor}}
  and assume a much higher level of control over how dependencies, modules,
  file-sets, and individual files are packaged in the assembly.

  Currently it can create distributions in the following formats:

    * zip

    * tar

    * tar.gz (or tgz)

    * tar.bz2 (or tbz2)

    * tar.snappy

    * jar

    * dir

    * war

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

  If your project wants to package your artifact in an uber-jar, the assembly
  plugin provides only basic support. For more control, use the
  {{{http://maven.apache.org/plugins/maven-shade-plugin/} Maven Shade Plugin}}.

  To use the Assembly Plugin in Maven, 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:single" 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 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}}.


* Goals

  The main goal in the assembly plugin is the {{{./single-mojo.html}single}} goal. It is used to create all assemblies.

  For more information about the goals that are available in the Assembly Plugin,
  see {{{./plugin-info.html}the plugin documentation page}}.


* Assembly and Component Descriptor Schemas (XSD)

  * {{{http://maven.apache.org/xsd/assembly-2.0.0.xsd}http://maven.apache.org/xsd/assembly-2.0.0.xsd}},
    {{{http://maven.apache.org/xsd/assembly-component-2.0.0.xsd}http://maven.apache.org/xsd/assembly-component-2.0.0.xsd}} (for version 3.0 and higher)

  * {{{http://maven.apache.org/xsd/assembly-1.1.3.xsd}http://maven.apache.org/xsd/assembly-1.1.3.xsd}},
    {{{http://maven.apache.org/xsd/component-1.1.3.xsd}http://maven.apache.org/xsd/component-1.1.3.xsd}} (for version 2.5.4 and higher)

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

  * {{{http://maven.apache.org/xsd/assembly-1.1.1.xsd}http://maven.apache.org/xsd/assembly-1.1.1.xsd}},
    {{{http://maven.apache.org/xsd/component-1.1.1.xsd}http://maven.apache.org/xsd/component-1.1.1.xsd}} (for version 2.2-beta-4 - 2.2-beta-5)

  * {{{http://maven.apache.org/xsd/assembly-1.1.0.xsd}http://maven.apache.org/xsd/assembly-1.1.0.xsd}},
    {{{http://maven.apache.org/xsd/component-1.1.0.xsd}http://maven.apache.org/xsd/component-1.1.0.xsd}} (for version 2.2-beta-1 - 2.2-beta-3)

  * {{{http://maven.apache.org/xsd/assembly-1.0.0.xsd}http://maven.apache.org/xsd/assembly-1.0.0.xsd}},
    {{{http://maven.apache.org/xsd/component-1.0.0.xsd}http://maven.apache.org/xsd/component-1.0.0.xsd}} (for version 2.1 and lower)

  []


* Usage

  General instructions on how to use the Assembly Plugin can be found on the {{{./usage.html}usage page}}. Some more
  specific use cases are described in the examples given below.

  In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel
  free to contact the {{{./mail-lists.html}user mailing list}}. The posts to the mailing list are archived and could
  already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching
  the {{{./mail-lists.html}mail archive}}.

  If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our
  {{{./issue-tracking.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your
  concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason,
  entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated.
  Of course, patches are welcome, too. Contributors can check out the project from our
  {{{./source-repository.html}source repository}} and will find supplementary information in the
  {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.


* 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}}.