src/site/apt/howto.apt

 ------
 Maven 2 Assembly Plugin
 ------
 Johnny R. Ruiz III
 <jruiz@exist.com>
 ------
 October 16, 2005

How to Use

  These are brief examples of how to use the assembly:assembly and assembly:unpack goals.

  To use the assembly:assembly goal, you must define the descriptor file that you are going to use or
  define the descriptorId from the predefined {{{descriptor.html}descriptor ids}}.


* How To use assembly:assembly using a customized descriptor file.

-----
  mvn assembly:assembly -Ddescriptor=path/to/descriptor.xml
-----


** How to assemble your project with your project modules only.
  
  There may be some situations that you only needed the jars of your project 
  modules. You may exclude their dependencies but what if you have 10 
  modules with 10 dependencies each? Isn't it a bit hassle to exclude 100 where 
  you only needed 10. To achieve this goal, set the "projectModulesOnly" 
  parameter to true and maven will do it for you.

-----
 mvn assembly:assembly -DprojectModulesOnly=true
-----


* How to use assembly:assembly using predefined descriptor ids.

----

  mvn assembly:assembly -DdescriptorId=bin

  or  mvn assembly:assembly -DdescriptorId=jar-with-dependencies

  or  mvn assembly:assembly -DdescriptorId=src

-----

* How to configure the assembly:assembly plugin in your POM

 You can also configure this plugin inside your pom.xml.  To run use "mvn assembly:assembly".

-----

<project>
  ...
  <build>
    ...
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>2.0-beta-1</version>
        <configuration>
          <descriptors>
            <descriptor>path/to/descriptor.xml</descriptor>
          </descriptors>
          <finalName>final_name</finalName>
          <outputDirectory>output/directory</outputDirectory>
          <workDirectory>target/assembly/work</workDirectory>
        </configuration>
      </plugin>
     </plugins>
     ...
   </build>
   ...
</project>

-----


* How to use assembly:unpack

  After running this goal, all dependencies will be extracted into the location specified in the
  \<workDirectory\> element.

-----
 mvn assembly:unpack
-----

  For full documentation of plugin's goals and parameters, click {{{index.html}here}}.

* How to assemble a repository

 The simplest descriptor you can create for assembly a repository would be something like the following:

-----

<assembly>
  <id>bin</id>
  <formats>
    <format>zip</format>
  </formats>
  <repositories>
    <repository>
      <outputDirectory>repository</outputDirectory>
    </repository>
  </repositories>
</assembly>

-----

 With no <<<includes>>> or <<<excludes>>> specified all dependencies are used to create a repository. In fact when you
 specify no <<<includes>>> the default will be to include them all, but you can still specify <<<excludes>>> if you need
 to keep certain artifacts from making it into the repository you're trying to assemble.

 By default no repository metadata is generated when the repository is assembled. If you are trying to create a repository
 that is going to be used as a remote repository then you will need to have the metadata generated in order to for it
 to function properly as a remote repository. To do this just enable repository metadata generation by using the
 <<<includeMetadata>>> element:

-----

<assembly>
  <id>bin</id>
  <formats>
    <format>zip</format>
  </formats>
  <repositories>
    <repository>
      <outputDirectory>repository</outputDirectory>
      <includeMetadata>true</includeMetadata>
    </repository>
  </repositories>
</assembly>

-----

 Keep in mind that any dependencies specified in the POM will have their transitive dependencies placed in the
 assembly as well.
 
 
* How to reuse assembly's component
 
   There are situations where your project can produce multiple assemblies with the same set of 
   denpendencySets, fileSets and/or files. Instead of duplicating those elements in all assembly descriptors, 
   you can refactor them out into  common component descriptor(s)
 
   Here is an example of assembly descriptor that uses component descriptor(s)
 
-----
 <assembly>
   <id>someid</id>
   <formats>
     <format>zip</format>
   </formats>
   <componentDescriptors>
     <componentDescriptor>src/main/assembly/component.xml</componentDescriptor>
   </componentDescriptors>
 </assembly>
-----
 
 
  and here is an example of component descriptor file

-----
<component>
  <dependencySets>
    <dependencySet>
       ....
    </dependencySet>
    ....
  </dependencySets>
  <fileSets>
    <fileSet>
      .....
    </fileSet>
    .....
  </fileSets>
  <files>
    <file>
      .....
    </file>
  </files>
</component>
-----