site/src/site/apt/guide/advanced/dependencies.apt

 ------
 Project Dependencies
 ------
 ------
 25 Feb 2009
 ------
~~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.

Project Dependencies

  This section defines the basic configuration of adding dependencies (otherwise known as <references>) into the
  project. To avoid runtime errors, make sure that the library to be loaded does not have conflicting instance(s) and/or
  is not yet loaded in the .NET Framework.
  
  Dependency Types:

    * normal - Local repository content artifacts that are added as dependencies.

    * <<<gac_msil>>> - Artifacts that are installed in the GAC and used as references. Configuration similar to the
      following is used, <<< \<type\>gac_msil\</type\> >>>

    * <<<system>>> - Artifact references to standard framework namespaces. Configuration similar to the following is
      added, <<< \<scope\>system\</scope\> >>> and the <<< \<systemPath\>[path_to_library]\</systemPath\> >>>

    * <<<com_references>>> - Artifact references to Component Object Model that is installed in the system.
      Configuration similar to the following is used, <<< \<type\>com_reference\</type\> >>>

    []

* Adding Dependencies

  Adding dependencies follows the normal Maven pattern, using the NPanday packaging types. For example:

+------+
<dependency>
  <groupId>NUnit</groupId>
  <artifactId>NUnit.Framework</artifactId>
  <version>2.2.8.0</version>
  <type>library</type>
</dependency>
+------+

  These dependencies can also refer to other modules in a multi-module build, which will be installed in the local
  Maven repository before building the project that depends on them.

  As mentioned above, the special type of <<<gac_msil>>> is available to refer to dependencies in the GAC.

  For all other dependencies, they should be located in a remote artifact repository. NPanday offers a few dependencies
  in the repository {{https://archiva-repository.apache.org/archiva/repository/3rdparty/}}. More commonly however, you will establish
  and populate your own artifact repository as described in
  {{{../devinfra/artifact-repository.html} Setting up an Artifact Repository}}.

** Installing an Artifact Locally

  If you are testing a new library and do not yet have it available in a remote artifact repository, you may wish to
  install it locally.

  Use the following command:

+------+
mvn org.apache.npanday.plugins:maven-install-plugin:install-file -Dfile=[path_to_file] \
  -DgroupId=[group_id] -DartifactId=[artifact_id] -DartifactVersion=[version] \
  -Dpackaging=[packaging_type]
+------+

  and supply appropriate values:

    * <<file>>: the location of the file to be installed.

    * <<groupId>>: the groupId of the file.

    * <<artifactId>>: artifact name of the file.

    * <<artifactVersion>>: the version of file.

    * <<packaging>>: the type of file to be installed.

    []

  If you use the Visual Studio Add-in, you can also have your project's
  references installed to the local repository as part of generating a Maven
  POM.

* Adding System Scope Dependencies

  To add a system scope dependency, add a configuration similar to the following in the project's <<<pom.xml>>>:
  
+------+
<dependency>
  <groupId>artifact_group_id</groupId>
  <artifactId>my.lib</artifactId>
  <version>2.2</version>
  <type>library</type>
  <scope>system</scope>
  <systemPath>C:\path\to\your\library.dll</systemPath>
</dependency>
+------+

  Supply the proper values for the dependency's <<<\<groupId\>>>>, <<<\<artifactId\>>>>, <<<\<version\>>>>,
  <<<\<type\>>>>, <<<\<scope\>>>>, and <<<\<systemPath\>>>>.
  Exact match of <<<artifactId>>> and <<<version>>> are required when manually adding dependencies into the project's
  <<<pom.xml>>>.

  Note that in general system dependencies are not recommended as they may be located elsewhere on a different machine.
  If they are required, you may mitigate this problem by using a property value that can be set differently on
  another system:

+------+
<dependencies>
  [...]
  <dependency>
    <groupId>artifact_group_id</groupId>
    <artifactId>my.lib</artifactId>
    <version>2.2</version>
    <type>library</type>
    <scope>system</scope>
    <systemPath>${some.property}\library.dll</systemPath>
  </dependency>
  [...]
</dependencies>
[...]
<properties>
  <some.property>C:\path\to\your</some.property>
</properties>
+------+

  The other system can then override it with <<<mvn -Dsome.property=c:\another\path ...>>> or by adding it to Maven's
  <<<settings.xml>>> file.