src/site/apt/usage.apt

~~ 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.    
 
  ------
  Usage
  ------
  Allan Ramirez
  Brian Fox
  ------
  Jan 2007
  ------

Usage
 
  Brief examples on how to use the dependency goals.
 
* Generic Plugin configuration information

  See the following links for information about including and configuring plugins in your project:
  
  *{{{http://maven.apache.org/guides/mini/guide-configuring-plugins.html}Configuring Plugins}}
  
  *{{{http://maven.apache.org/guides/plugin/guide-java-plugin-development.html}Plugin Development}}

  *{{{http://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html}Plugin Prefix}}

* The <<<dependency:copy>>> mojo

   This goal is meant to be bound to a lifecycle phase and configured in your
   <<<pom.xml>>>. It will resolve the artifact from the repository and place a copy
   in the specified location. Multiple artifacts can be defined in a single
   execution. A default output directory is specified but can be overriden for
   each ArtifactItem by setting the optional outputDirectory field. An
   optional new name can be set to rename or the version stripped while copying. 
   
   The artifact version is optional. If not set, the plugin will attempt to resolve it from the
   project dependencies and then the dependencyManagement section.

   See the {{#Overwrite Rules}} section for rules about how overwriting is handled.

     []

   Configure the plugin something like this:

+---+
<project>
  [...]
  <build>
   <plugins>
     <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>copy</id>
            <phase>package</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>[ groupId ]</groupId>
                  <artifactId>[ artifactId ]</artifactId>
                  <version>[ version ]</version>
                  <type>[ packaging ]</type>
                  <overWrite>[ true or false ]</overWrite>
                  <outputDirectory>[ output directory ]</outputDirectory>
                  <destFileName>[ filename ]</destFileName>
                </artifactItem>
              </artifactItems>
              <!-- other configurations here -->
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

* The <<<dependency:copy-dependencies>>> mojo

   This goal can be bound to a lifecycle phase and configured in your <<<pom.xml>>>.
   It will resolve the dependencies (including transitive dependencies) from
   the repository and place a copy in the specified location. 

   The artifacts can be placed in subfolders based on type. For example:

   \outputDirectory

   \outputDirectory\jars

   \outputDirectory\wars

   The artifacts can be placed in a subfolder per artifact. For example:
   \outputDirectory\junit-junit-3.8.1\
   This feature also works with the subfolders per type. For example:
   \outputDirectory\jars\junit-junit-3.8.1\

   Artifacts can also be resolved by specifying the classifer and optionally
   type. Type is only used with the classifier and defaults to java-sources.
   When the classifier is set, the list of dependencies is used as the base to
   resolve artifacts with the classifer and type. For example:
   <<<mvn dependency:copy-dependencies -Dclassifer=sources>>> will try to find
   the sources for all dependencies and copy them.

   	Also included is the ability to include or exclude by type (war, jar etc), scope (runtime, test, etc), classifier (jdk14, sources, etc) or a combination of all three.

   See the {{#Overwrite Rules}} section for rules about how overwriting is handled.


   The goal can also be launched from the command line like:
   <<<mvn dependency:copy-dependencies [optional params]>>>

+---+
<project>
  [...]
  <build>
   <plugins>
     <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>copy-dependencies</id>
            <phase>package</phase>
            <goals>
              <goal>copy-dependencies</goal>
            </goals>
            <configuration>
                <!-- configure the plugin here -->
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+


* The <<<dependency:unpack>>> mojo

   This goal is meant to be bound to a lifecycle and configured in your pom.xml.
   It will resolve the artifact from the repository and place a copy in the
   specified location. Multiple artifacts can be defined in a single execution.
   A default outputDirectory is specified but can be overriden for each
   ArtifactItem by setting the optional outputDirectory field. 

   See the {{#Overwrite Rules}} section for rules about how overwriting is handled.

   The artifact version is optional. If not set, the plugin will attempt to resolve it from the
   project dependencies and then the dependencyManagement section.

+---+
<project>
  [...]
  <build>
   <plugins>
     <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>unpack</id>
            <phase>package</phase>
            <goals>
              <goal>unpack</goal>
            </goals>
            <configuration>
                <!-- configure the plugin here -->
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

* The <<<dependency:unpack-dependencies>>> mojo

   This goal can be bound to a lifecycle and configured in your pom.xml.
   It will resolve the dependencies (including transitive dependencies) from
   the repository and unpack them to the specified location.

   Unpack-dependencies includes transitive dependencies by default. To include
   only direct dependencies, set the excludeTransitive parameter to true.

   Dependencies can be included or excluded by a list of types. See
   {{{unpack-dependencies-mojo.html}unpack-dependencies}} for details.

   The artifacts can be unpacked in subfolders based on type. For example:

   \outputDirectory

   \outputDirectory\jars

   \outputDirectory\wars

   The artifacts can be placed in a subfolder per artifact. For example:
   \outputDirectory\junit-junit-3.8.1\
   This feature also works with the subfolders per type. For example:
   \outputDirectory\jars\junit-junit-3.8.1\

   Artifacts can also be resolved by specifying the classifer and optionally
   type. Type is only used with the classifier and defaults to java-sources.
   When the classifier is set, the list of dependencies is used as the base to
   resolve artifacts with the classifer and type. For example:
   <<<mvn dependency:unpack-dependencies -Dclassifer=sources>>> will try to find
   the sources for all dependencies and unpack them.
   
   Also included is the ability to include or exclude by type (war, jar etc), scope (runtime, test, etc), classifier (jdk14, sources, etc) or a combination of all three.

   See the {{#Overwrite Rules}} section for rules about how overwriting is handled.
                                      
   The goal can also be launched from the command line like:
   <<<mvn dependency:unpack-dependencies [optional params]>>>

+---+
<project>
  [...]
  <build>
   <plugins>
     <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>unpack-dependencies</id>
            <phase>package</phase>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
                <!-- configure the plugin here -->
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

* {Overwrite Rules}

    Artifacts are copied or unpacked using the following rules:

     * If the artifact doesn't exist in the destination, then copy/unpack it.
     
     Otherwise:
     
     * For copy/unpack mojo only: if <<<artifactItem / overWrite>>> or <<<overWrite>>> is true, then it will force an overwrite.
     
     * Releases check the <<<overWriteReleases>>> value (default = false). If true, then it will force an overwrite.

     * Snapshots check the <<<overWriteSnapshots>>> value (default = false). If true, then it will force an overwrite.
     
     * If none of the above is set to true, then it defaults to the <<<overWriteIfNewer>>> value (default = true). This value, if true, causes
     the plugin to only copy if the source is newer than the destination (or it doesn't exist in the destination). (for unpack, this checks the existence of the marker file, created in the <<<markersDirectory>>> path.
     To avoid unexpected behavior after <<<mvn clean>>>, this path should normally be contained within the <<</target>>> hierarchy.)
     
   Examples:
     
     * Using the default settings (<<<overWriteReleases>>> = false, <<<overWriteSnapshots>>> = false, <<<overWriteIfNewer>>> = true), then a release or snapshot artifact will
     only over write the destination if the source is newer than the destination (or marker file if unpacking).
     
     * If <<<overWriteReleases>>> = true, then a release artifact (ie <<<foo-1.0.jar>>>) will always overwrite.
     
     * If <<<overWriteSnapshots>>> = true, then a snapshot artifact (ie <<<foo-1.0-SNAPSHOT.jar>>>) will always overwrite.
     
     * If all of the values are false, then a copy/unpack will only occur if it doesn't exist in the destination (or <<<markersDirectory>>> if unpacking).
     
     

* The <<<dependency:resolve>>> mojo

  Resolve is intended to be used from the command line like:
  <<<mvn dependency:resolve -Dsilent=true>>>

  This goal simply tells maven to resolve all test scope (includes compile)
  dependencies and then displays the resolved versions. This is intended to
  help ensure all dependencies are downloaded to the local repository. This is
  usefull when troubleshooting or during intermittent remote repository
  failures when repeatedly building multiproject modules is undersirable and
  the build is failing on dependency resolution. It can also be used to quickly
  determine how versions are being resolved.

  Artifacts can also be resolved by specifying the classifer and optionally
  type. Type is only used with the classifier and defaults to java-sources.
  When the classifier is set, the list of dependencies is used as the base to
  resolve artifacts with the classifer and type. For example:
  <<<mvn dependency:resolve -Dclassifer=test-jar>>> will try to find the
  test-jar for all dependencies resolve them to the local repository.

* The <<<dependency:sources>>> mojo

  Sources is intended to be used from the command line like:
  <<<mvn dependency:sources -Dsilent=true>>>

  This is the same as the resolve goal except it includes the source
  attachments if they exist.  This is useful when you want the source
  attachments downloaded to your local repository and
  you don't want to use the eclipse plugin to do this since the eclipse plugin
  creates/overwrites the eclipse files. 
  
  You can also define the <<<markersDirectory>>> either in the pom or settings
  to be a common location for all projects. This allows the system to resolve sources faster for dependencies that don't
  have the sources published. The plugin will store a marker file to describe if the sources where resolved or not. By placing
  them in a common location, multiple attempts to resolve non-existent sources will be avoided.

* The <<<dependency:resolve-plugins>>> mojo

  Resolve-plugins is intended to be used from the command line like:
  <<<mvn dependency:resolve-plugins -Dsilent=true -DexcludeTransitive=true>>>

  This is the same as the resolve goal except it resolves plugins and
  optionally their dependencies.

* The <<<dependency:go-offline>>> mojo

  This goal is exactly the same as calling
  <<<mvn dependency:resolve dependency:resolve-plugins>>>.

* The <<<dependency:purge-local-repository>>> mojo

  This goal is meant to delete all of the dependencies for the current project
  (or projects, in the case of a multimodule build) from the local repository.
  Purges can be run with a variety of limiting parameters, including artifact
  exclusions, limiting to direct dependencies only, and different levels of
  depth for deletion. By default, deleted artifacts can be re-resolved 
  afterwards; you can disable this by specifying <<<-DreResolve=false>>>.

  In its simplest form, the mojo can be called like this:

+---+
mvn dependency:purge-local-repository
+---+

  To add the restriction that the <<<org.apache.maven:maven-plugin-api>>>
  artifact not be deleted, we can modify the command to this:

+---+
mvn dependency:purge-local-repository -Dexclude=org.apache.maven:maven-plugin-api
+---+

  <<NOTE:>> The <<<exclude>>> parameter is a comma-delimited list of 
  groupId:artifactId pairs. It has a corresponding List-based parameter -
  <<<excludes>>> - for convenient use inside the POM.

  Another handy aspect of this mojo is the ability to wipe out artifacts at
  varying depths. These depths are:

  * <<file>> - Delete just the artifact's file.

  * <<version>> - Delete the version directory containing this artifact. Amounts to
    <<<file.getParentFile()>>>.

  * <<artifactId>> - Delete the artifactId directory containing this artifact.
    Amounts to <<<file.getParentFile().getParentFile()>>>.

  * <<groupId>> - Delete the groupId directory structure containing this artifact.

    At a minimum, this amounts to <<<file.getParentFile().getParentFile().getParentFile()>>>.
    However, if the groupId contains multiple parts, the mojo will prune all groupId-part
    directories that contain only the files associated with this artifact. Again, note that
    the exception to this pruning algorithm is the lowest groupId part, which will always
    be pruned.

  []

  To prune dependency artifacts back to their associated artifactId directories
  (in order to verify proper artifact resolution, for example), simply use this
  command:

+---+
mvn dependency:prune-local-repository -DresolutionFuzziness=artifactId
+---+

  Finally, it's possible to bind this mojo to the build lifecycle. One reason for this
  might be to clean out all dependencies when the build is initialized, to verify
  correct resolution.