# DependencyHandler

API Documentation: | `DependencyHandler`

A `DependencyHandler` is used to declare dependencies. Dependencies are grouped into configurations (see `Configuration`).

To declare a specific dependency for a configuration you can use the following syntax:

    dependencies {
        configurationName dependencyNotation1, dependencyNotation2, ...
    }

Example shows a basic way of declaring dependencies.

    apply plugin: 'java'
    //so that we can use 'compile', 'testCompile' for dependencies

    dependencies {
      //for dependencies found in artifact repositories you can use
      //the group:name:version notation
      compile 'commons-lang:commons-lang:2.6'
      testCompile 'org.mockito:mockito:1.9.0-rc1'

      //map-style notation:
      compile group: 'com.google.code.guice', name: 'guice', version: '1.0'

      //declaring arbitrary files as dependencies
      compile files('hibernate.jar', 'libs/spring.jar')

      //putting all jars from 'libs' onto compile classpath
      compile fileTree('libs')
    }

### Advanced dependency configuration

To do some advanced configuration on a dependency when it is declared, you can additionally pass a configuration closure:

    dependencies {
        configurationName(dependencyNotation){
            configStatement1
            configStatement2
        }
    }

Examples of advanced dependency declaration including:

- Forcing certain dependency version in case of the conflict.
- Excluding certain dependencies by name, group or both. More details about per-dependency exclusions can be found in docs for `ModuleDependency.exclude(java.util.Map)`.
- Avoiding transitive dependencies for certain dependency.

    apply plugin: 'java' //so that I can declare 'compile' dependencies

    dependencies {
      compile('org.hibernate:hibernate:3.1') {
        //in case of versions conflict '3.1' version of hibernate wins:
        force = true

        //excluding a particular transitive dependency:
        exclude module: 'cglib' //by artifact name
        exclude group: 'org.jmock' //by group
        exclude group: 'org.unwanted', module: 'iAmBuggy' //by both name and group

        //disabling all transitive dependencies of this dependency
        transitive = false
      }
    }

More examples of advanced configuration, useful when dependency module has multiple artifacts:

- Declaring dependency to a specific configuration of the module.
- Explicit specification of the artifact. See also `ModuleDependency.artifact(groovy.lang.Closure)`.

    apply plugin: 'java' //so that I can declare 'compile' dependencies

    dependencies {
      //configuring dependency to specific configuration of the module
      compile configuration: 'someConf', group: 'org.someOrg', name: 'someModule', version: '1.0'

      //configuring dependency on 'someLib' module
      compile(group: 'org.myorg', name: 'someLib', version:'1.0') {
        //explicitly adding the dependency artifact:
        artifact {
          //useful when some artifact properties unconventional
          name = 'someArtifact' //artifact name different than module name
          extension = 'someExt'
          type = 'someType'
          classifier = 'someClassifier'
        }
      }
    }

### Dependency notations

There are several supported dependency notations. These are described below. For each dependency declared this way, a `Dependency` object is created. You can use this object to query or further configure the dependency.

You can also always add instances of `Dependency` directly:

`configurationName <instance>`

#### External dependencies

There are two notations supported for declaring a dependency on an external module. One is a string notation formatted this way:

`configurationName "group:name:version:classifier@extension"`

The other is a map notation:

`configurationName group: group, name: name, version: version, classifier: classifier, ext: extension`

In both notations, all properties, except name, are optional.

External dependencies are represented by a `ExternalModuleDependency`.

    apply plugin: 'java'
    //so that we can use 'compile', 'testCompile' for dependencies

    dependencies {
      //for dependencies found in artifact repositories you can use
      //the string notation, e.g. group:name:version
      compile 'commons-lang:commons-lang:2.6'
      testCompile 'org.mockito:mockito:1.9.0-rc1'

      //map notation:
      compile group: 'com.google.code.guice', name: 'guice', version: '1.0'
    }

#### Project dependencies

To add a project dependency, you use the following notation:

`configurationName project(':someProject')`

The notation `project(':projectA')` is similar to the syntax you use when configuring a projectA in a multi-module gradle project.

By default, when you declare dependency to projectA, you actually declare dependency to the 'default' configuration of the projectA. If you need to depend on a specific configuration of projectA, use map notation for projects:

`configurationName project(path: ':projectA', configuration: 'someOtherConfiguration')`

Project dependencies are represented using a `ProjectDependency`.

#### File dependencies

You can also add a dependency using a `FileCollection`:

`configurationName files('a file')`

    apply plugin: 'java'
    //so that we can use 'compile', 'testCompile' for dependencies

    dependencies {
      //declaring arbitrary files as dependencies
      compile files('hibernate.jar', 'libs/spring.jar')

      //putting all jars from 'libs' onto compile classpath
      compile fileTree('libs')
    }

File dependencies are represented using a `SelfResolvingDependency`.

#### Dependencies to other configurations

You can add a dependency using a `Configuration`.

When the configuration is from the same project as the target configuration, the target configuration is changed to extend from the provided configuration.

When the configuration is from a different project, a project dependency is added.

#### Gradle distribution specific dependencies

It is possible to depend on certain Gradle APIs or libraries that Gradle ships with. It is particularly useful for Gradle plugin development. Example:

    //Our Gradle plugin is written in groovy
    apply plugin: 'groovy'
    //now we can use the 'compile' configuration for declaring dependencies

    dependencies {
      //we will use the Groovy version that ships with Gradle:
      compile localGroovy()

      //our plugin requires Gradle API interfaces and classes to compile:
      compile gradleApi()

      //we will use the Gradle test-kit to test build logic:
      testCompile gradleTestKit()
    }

#### Client module dependencies

To add a client module to a configuration you can use the notation:

    configurationName module(moduleNotation) {
        module dependencies
    }

The module notation is the same as the dependency notations described above, except that the classifier property is not available. Client modules are represented using a `ClientModule`.

### Properties

Property | Description
`components` | Incubating The component metadata handler for this project. The returned handler can be used for adding rules that modify the metadata of depended-on software components.
`modules` | Incubating The component module metadata handler for this project. The returned handler can be used for adding rules that modify the metadata of depended-on software components.

### Methods

Method | Description
`add(configurationName, dependencyNotation)` | Adds a dependency to the given configuration.
`add(configurationName, dependencyNotation, configureClosure)` | Adds a dependency to the given configuration, and configures the dependency using the given closure.
`components(configureAction)` | Incubating Configures component metadata for this project.
`create(dependencyNotation)` | Creates a dependency without adding it to a configuration.
`create(dependencyNotation, configureClosure)` | Creates a dependency without adding it to a configuration, and configures the dependency using the given closure.
`createArtifactResolutionQuery()` | Incubating Creates an artifact resolution query.
`gradleApi()` | Creates a dependency on the API of the current version of Gradle.
`gradleTestKit()` | Incubating Creates a dependency on the Gradle test-kit API.
`localGroovy()` | Creates a dependency on the Groovy that is distributed with the current version of Gradle.
`module(notation)` | Creates a dependency on a client module.
`module(notation, configureClosure)` | Creates a dependency on a client module. The dependency is configured using the given closure before it is returned.
`modules(configureAction)` | Incubating Configures module metadata for this project.
`project(notation)` | Creates a dependency on a project.

### Script blocks

No script blocks

### Property details

#### `ComponentMetadataHandler` `components` (read-only)

Note: This property is incubating and may change in a future version of Gradle.

The component metadata handler for this project. The returned handler can be used for adding rules that modify the metadata of depended-on software components.

#### `ComponentModuleMetadataHandler` `modules` (read-only)

Note: This property is incubating and may change in a future version of Gradle.

The component module metadata handler for this project. The returned handler can be used for adding rules that modify the metadata of depended-on software components.

### Method details

#### `Dependency` `add`(`String` configurationName, `Object` dependencyNotation)

Adds a dependency to the given configuration.

#### `Dependency` `add`(`String` configurationName, `Object` dependencyNotation, `Closure` configureClosure)

Adds a dependency to the given configuration, and configures the dependency using the given closure.

#### `void` `components`(``Action`<? super `ComponentMetadataHandler`>` configureAction)

Note: This method is incubating and may change in a future version of Gradle.

Configures component metadata for this project.

This method executes the given action against the `ComponentMetadataHandler` for this project.

#### `Dependency` `create`(`Object` dependencyNotation)

Creates a dependency without adding it to a configuration.

#### `Dependency` `create`(`Object` dependencyNotation, `Closure` configureClosure)

Creates a dependency without adding it to a configuration, and configures the dependency using the given closure.

#### `ArtifactResolutionQuery` `createArtifactResolutionQuery`()

Note: This method is incubating and may change in a future version of Gradle.

Creates an artifact resolution query.

#### `Dependency` `gradleApi`()

Creates a dependency on the API of the current version of Gradle.

#### `Dependency` `gradleTestKit`()

Note: This method is incubating and may change in a future version of Gradle.

Creates a dependency on the Gradle test-kit API.

#### `Dependency` `localGroovy`()

Creates a dependency on the Groovy that is distributed with the current version of Gradle.

#### `Dependency` `module`(`Object` notation)

Creates a dependency on a client module.

#### `Dependency` `module`(`Object` notation, `Closure` configureClosure)

Creates a dependency on a client module. The dependency is configured using the given closure before it is returned.

#### `void` `modules`(``Action`<? super `ComponentModuleMetadataHandler`>` configureAction)

Note: This method is incubating and may change in a future version of Gradle.

Configures module metadata for this project.

This method executes the given action against the `ComponentModuleMetadataHandler` for this project.

#### `Dependency` `project`(``Map`<`String`, ?>` notation)

Creates a dependency on a project.