src/site/apt/examples/copying-artifacts.apt.vm

~~ 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.    
 
  ------
  Copying specific artifacts
  ------
  Allan Ramirez
  Brian Fox
  Stephen Connolly
  ------
  2011-07-01
  ------

Copying specific artifacts

  In copying specific artifacts, you need to bind the <<<dependency:copy>>>
  mojo to a lifecycle, configure the plugin and specify the artifacts you
  want to copy. See the following example:

+---+
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>copy</id>
            <phase>package</phase>
            <goals>
              <goal>copy</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <artifactItems>
            <artifactItem>
              <groupId>junit</groupId>
              <artifactId>junit</artifactId>
              <version>3.8.1</version>
              <type>jar</type>
              <overWrite>false</overWrite>
              <outputDirectory>\${project.build.directory}/alternateLocation</outputDirectory>
              <destFileName>optional-new-name.jar</destFileName>
            </artifactItem>
          </artifactItems>
          <outputDirectory>\${project.build.directory}/wars</outputDirectory>
          <overWriteReleases>false</overWriteReleases>
          <overWriteSnapshots>true</overWriteSnapshots>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

    Then after executing <<<mvn package>>>, the artifact (junit) is copied to the
    given alternate location.

    Artifacts are resolved from the following sources in order:

      * the current reactor,

      * the local repository,

      * the configured remote repositories.

      []

    If the artifact cannot be resolved from the above sources then the build will fail.

    If the artifact is also listed as a dependency, the <<<version>>> of the <<<artifactItem>>> will default to
    the version from the <<<dependencies>>> or <<<dependencyManagement>>>, e.g.

+---+
<project>
  [...]
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>copy</id>
            <phase>package</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>junit</groupId>
                  <artifactId>junit</artifactId>
                  <overWrite>false</overWrite>
                  <outputDirectory>\${project.build.directory}/alternateLocation</outputDirectory>
                  <destFileName>optional-new-name.jar</destFileName>
                </artifactItem>
              </artifactItems>
              <outputDirectory>\${project.build.directory}/wars</outputDirectory>
              <overWriteReleases>false</overWriteReleases>
              <overWriteSnapshots>true</overWriteSnapshots>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

    The <<<dependency:copy>>> goal can also be used to copy the just built
    artifact to a custom location if desired. <<It must be bound
    to any phase after the package phase>> so that the artifact exists in the
    repository. The following configuration shows how (binding to the
    install phase in this case):

+---+
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>copy-installed</id>
            <phase>install</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>\${project.groupId}</groupId>
                  <artifactId>\${project.artifactId}</artifactId>
                  <version>\${project.version}</version>
                  <type>\${project.packaging}</type>
                </artifactItem>
              </artifactItems>
              <outputDirectory>some-other-place</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

{Using an alternate local repository}

    <<dependency:copy>> always downloads artifacts to default local repository first, and then
    copy the artifacts to the desired locations.  For large size unique snapshot artifacts, the downloads can quickly
    fill up default local repository, and therefore local disk, after many executions.  
    To clean up the downloaded artifacts as part the build, set <localRepositoryDirectory>'s value 
    to a location in your project's target directory.

    This use case also applies to <<dependency:unpack>> goal.

+---+
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>copy-with-alternalte-repo</id>
            <phase>install</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  [...]
                </artifactItem>
                [...]
              </artifactItems>
              <localRepositoryDirectory>\${project.build.directory}/localrepo</localRepositoryDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

{Copying from the command line}

	If you intend to configure this mojo for execution on the command line using:

+---+
mvn dependency:copy
+---+

	you must not put the configuration inside the <executions> tag. Your configuration should look like this:

+---+
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>${project.version}</version>
        <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>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+