src/site/apt/examples/single/using-repositories.apt.vm

 ------
  Using Repositories
 ------
  Edwin Punzalan
 ------
  26-July-2006
 ------

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

Using Repositories

* Introduction

  The Assembly Plugin allows the inclusion of needed artifacts from your local
  repository to the generated archive. They are copied into the assembly in a
  directory similar to what's in your remote repository, complete with metadata
  and the checksums.

  This example demonstrates the creation of repository artifacts in an assembly
  so that the archive can easily be used to update an internal repository with
  the artifacts used by your project.

* The Assembly Descriptor

  A functional repository archive for your project can be created with:

+-----
<assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
  <id>repository</id>
  <formats>
    <format>jar</format>
  </formats>
  <repositories>
    <repository>
      <includeMetadata>true</includeMetadata>
      <outputDirectory>maven2</outputDirectory>
    </repository>
  </repositories>
</assembly>
+-----

  The above descriptor tells the Assembly Plugin to create a repository-like
  directory structure inside the <<<maven2>>> directory from within the
  generated archive. Setting <<<includeMetadata>>> to <<<true>>> will make the
  plugin to also copy metadata information into the generated archive.

* The POM

  The pom.xml for your project is very similar to how you configure the Assembly
  Plugin for other distribution types.

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

* Generating The Assembly Archive

  The assembly archive is then created using:

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

  The generated archive can be extracted to an internal repository so users of
  your project can download the dependencies from it.

* Examining the Output

  When the Maven execution completes, the archive contents should be similar to:

+-----
target/artifactId-version-repository.jar
`-- maven2
    |-- groupId
    |   |-- maven-metadata.xml
    |   |-- maven-metadata.xml.md5
    |   |-- maven-metadata.xml.sha1
    |   `-- artifactId
    |       |-- maven-metadata.xml
    |       |-- maven-metadata.xml.md5
    |       |-- maven-metadata.xml.sha1
    |       `-- version
    |           |-- artifactId-version.jar
    |           |-- artifactId-version.jar.md5
    |           |-- artifactId-version.jar.sha1
    |           |-- artifactId-version.pom
    |           |-- artifactId-version.pom.md5
    |           |-- artifactId-version.pom.sha1
    |           |-- maven-metadata.xml
    |           |-- maven-metadata.xml.md5
    |           `-- maven-metadata.xml.sha1
    `-- groupId2
        `-- [...]
+-----