Package org.gradle.api.artifacts.dsl

# Interface DependencyHandler

All Superinterfaces:
  `ExtensionAware`

@ServiceScope(org.gradle.internal.service.scopes.Scope.Project.class) public interface DependencyHandler extends ExtensionAware

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 dependencyNotation
     }

Example shows a basic way of declaring dependencies.

     plugins {
         id 'java' // so that we can use 'implementation', 'testImplementation' for dependencies
     }

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

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

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

       //putting all jars from 'libs' onto compile classpath
       implementation 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.

     plugins {
         id 'java' // so that I can declare 'implementation' dependencies
     }

     dependencies {
       implementation('org.hibernate:hibernate') {
         //in case of versions conflict '3.1' version of hibernate wins:
         version {
           strictly('3.1')
         }

         //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)`.

     plugins {
         id("java-library")
     }

     dependencies {
       // Configuring dependency to specific configuration of the module
       // This notation should _only_ be used for Ivy dependencies
       implementation(group: "org.someOrg", name: "someModule", version: "1.0", configuration: "someConf")

       // Configuring dependency on 'someLib' module
       implementation(group: 'org.myorg', name: 'someLib', version:'1.0') {
         // Explicitly adding the dependency artifact:
         // Prefer variant-aware dependency resolution
         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>`

Dependencies can also be declared with a `Provider` that provides any of the other supported dependency notations.

### 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`.

     plugins {
         id 'java' // so that we can use 'implementation', 'testImplementation' for dependencies
     }

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

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

### Project dependencies

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

`configurationName project(':some-project')`

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

Project dependencies are resolved by treating each consumable configuration in the target project as a variant and performing variant-aware attribute matching against them. However, in order to override this process, an explicit target configuration can be specified:

`configurationName project(path: ':project-a', configuration: 'someOtherConfiguration')`

Project dependencies are represented using a `ProjectDependency`.

### File dependencies

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

`configurationName files('a file')`

     plugins {
         id 'java' // so that we can use 'implementation', 'testImplementation' for dependencies
     }

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

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

File dependencies are represented using a `FileCollectionDependency`.

### 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
     plugins {
         id 'groovy'
     }
     // now we can use the 'implementation' configuration for declaring dependencies

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

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

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `@Nullable Dependency`
  `add(String configurationName, Object dependencyNotation)`
  Adds a dependency to the given configuration.
  `@Nullable Dependency`
  `add(String configurationName, Object dependencyNotation, Closure configureClosure)`
  Adds a dependency to the given configuration, and configures the dependency using the given closure.
  `<T> void`
  `addProvider(String configurationName, Provider<T> dependencyNotation)`
  Adds a dependency provider to the given configuration.
  `<T, U extends ExternalModuleDependency>
  void`
  `addProvider(String configurationName, Provider<T> dependencyNotation, Action<? super U> configuration)`
  Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
  `<T> void`
  `addProviderConvertible(String configurationName, ProviderConvertible<T> dependencyNotation)`
  Adds a dependency provider to the given configuration.
  `<T, U extends ExternalModuleDependency>
  void`
  `addProviderConvertible(String configurationName, ProviderConvertible<T> dependencyNotation, Action<? super U> configuration)`
  Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
  `void`
  `artifactTypes(Action<? super ArtifactTypeContainer> configureAction)`
  Configures the artifact type definitions for this handler.
  `AttributesSchema`
  `attributesSchema(Action<? super AttributesSchema> configureAction)`
  Configures the attributes schema.
  `void`
  `components(Action<? super ComponentMetadataHandler> configureAction)`
  Configures component metadata for this project.
  `void`
  `constraints(Action<? super DependencyConstraintHandler> configureAction)`
  Configures dependency constraint 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()`
  Creates an artifact resolution query.
  `Dependency`
  `enforcedPlatform(Object notation)`
  Declares a dependency on an enforced platform.
  `Dependency`
  `enforcedPlatform(Object notation, Action<? super Dependency> configureAction)`
  Declares a dependency on an enforced platform.
  `Provider<MinimalExternalModuleDependency>`
  `enforcedPlatform(Provider<MinimalExternalModuleDependency> dependencyProvider)`
  Configures this dependency provider to select the enforced-platform variant of the target component
  `default Provider<MinimalExternalModuleDependency>`
  `enforcedPlatform(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)`
  Configures this dependency provider to select the enforced-platform variant of the target component
  `ArtifactTypeContainer`
  `getArtifactTypes()`
  Returns the artifact type definitions for this handler.
  `AttributesSchema`
  `getAttributesSchema()`
  Returns the attributes schema for this handler.
  `ComponentMetadataHandler`
  `getComponents()`
  Returns the component metadata handler for this project.
  `DependencyConstraintHandler`
  `getConstraints()`
  Returns the dependency constraint handler for this project.
  `ComponentModuleMetadataHandler`
  `getModules()`
  Returns the component module metadata handler for this project.
  `Dependency`
  `gradleApi()`
  Creates a dependency on the API of the current version of Gradle.
  `Dependency`
  `gradleTestKit()`
  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.
  `void`
  `modules(Action<? super ComponentModuleMetadataHandler> configureAction)`
  Configures module metadata for this project.
  `Dependency`
  `platform(Object notation)`
  Declares a dependency on a platform.
  `Dependency`
  `platform(Object notation, Action<? super Dependency> configureAction)`
  Declares a dependency on a platform.
  `default Provider<MinimalExternalModuleDependency>`
  `platform(Provider<MinimalExternalModuleDependency> dependencyProvider)`
  Configures this dependency provider to select the platform variant of the target component
  `default Provider<MinimalExternalModuleDependency>`
  `platform(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)`
  Configures this dependency provider to select the platform variant of the target component
  `Dependency`
  `project(Map<String,?> notation)`
  Creates a dependency on a project.
  `<T extends TransformParameters>
  void`
  `registerTransform(Class<? extends TransformAction<T>> actionType, Action<? super TransformSpec<T>> registrationAction)`
  Registers an artifact transform.
  `Dependency`
  `testFixtures(Object notation)`
  Declares a dependency on the test fixtures of a component.
  `Dependency`
  `testFixtures(Object notation, Action<? super Dependency> configureAction)`
  Declares a dependency on the test fixtures of a component and allows configuring the resulting dependency.
  `default Provider<MinimalExternalModuleDependency>`
  `testFixtures(Provider<MinimalExternalModuleDependency> dependencyProvider)`
  Configures this dependency provider to select the test fixtures of the target component
  `default Provider<MinimalExternalModuleDependency>`
  `testFixtures(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)`
  Configures this dependency provider to select the test fixtures of the target component
  `Provider<MinimalExternalModuleDependency>`
  `variantOf(Provider<MinimalExternalModuleDependency> dependencyProvider, Action<? super ExternalModuleDependencyVariantSpec> variantSpec)`
  Allows fine-tuning what variant to select for the target dependency.
  `default Provider<MinimalExternalModuleDependency>`
  `variantOf(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible, Action<? super ExternalModuleDependencyVariantSpec> variantSpec)`
  Allows fine-tuning what variant to select for the target dependency.

  ### Methods inherited from interface org.gradle.api.plugins.ExtensionAware

  `getExtensions`

- ## Method Details

  - ### add

    @Nullable Dependency add(String configurationName, Object dependencyNotation)
    Adds a dependency to the given configuration.
    Parameters:
      `configurationName` - The name of the configuration.
      `dependencyNotation` - The dependency notation, in one of the notations described above.
    Returns:
      The dependency, or null if dependencyNotation is a provider.

  - ### add

    @Nullable Dependency add(String configurationName, Object dependencyNotation, Closure configureClosure)
    Adds a dependency to the given configuration, and configures the dependency using the given closure.
    Parameters:
      `configurationName` - The name of the configuration.
      `dependencyNotation` - The dependency notation, in one of the notations described above.
      `configureClosure` - The closure to use to configure the dependency.
    Returns:
      The dependency, or null if dependencyNotation is a provider.

  - ### addProvider

    <T, U extends ExternalModuleDependency> void addProvider(String configurationName, Provider<T> dependencyNotation, Action<? super U> configuration)
    Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
    Parameters:
      `configurationName` - The name of the configuration.
      `dependencyNotation` - The dependency provider notation, in one of the notations described above.
      `configuration` - The action to use to configure the dependency.
    Since:
      6.8

  - ### addProvider

    <T> void addProvider(String configurationName, Provider<T> dependencyNotation)
    Adds a dependency provider to the given configuration.
    Parameters:
      `configurationName` - The name of the configuration.
      `dependencyNotation` - The dependency provider notation, in one of the notations described above.
    Since:
      7.0

  - ### addProviderConvertible

    <T, U extends ExternalModuleDependency> void addProviderConvertible(String configurationName, ProviderConvertible<T> dependencyNotation, Action<? super U> configuration)
    Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
    Parameters:
      `configurationName` - The name of the configuration.
      `dependencyNotation` - The dependency provider notation, in one of the notations described above.
      `configuration` - The action to use to configure the dependency.
    Since:
      7.4

  - ### addProviderConvertible

    <T> void addProviderConvertible(String configurationName, ProviderConvertible<T> dependencyNotation)
    Adds a dependency provider to the given configuration.
    Parameters:
      `configurationName` - The name of the configuration.
      `dependencyNotation` - The dependency provider notation, in one of the notations described above.
    Since:
      7.4

  - ### create

    Dependency create(Object dependencyNotation)
    Creates a dependency without adding it to a configuration.
    Parameters:
      `dependencyNotation` - The dependency notation, in one of the notations described above.
    Returns:
      The dependency.

  - ### create

    Dependency create(Object dependencyNotation, Closure configureClosure)
    Creates a dependency without adding it to a configuration, and configures the dependency using the given closure.
    Parameters:
      `dependencyNotation` - The dependency notation, in one of the notations described above.
      `configureClosure` - The closure to use to configure the dependency.
    Returns:
      The dependency.

  - ### project

    Dependency project(Map<String,?> notation)
    Creates a dependency on a project.
    Parameters:
      `notation` - The project notation, in one of the notations described above.
    Returns:
      The dependency.

  - ### gradleApi

    Dependency gradleApi()
    Creates a dependency on the API of the current version of Gradle.
    Returns:
      The dependency.

  - ### gradleTestKit

    Dependency gradleTestKit()
    Creates a dependency on the Gradle test-kit API.
    Returns:
      The dependency.
    Since:
      2.6

  - ### localGroovy

    Dependency localGroovy()
    Creates a dependency on the Groovy that is distributed with the current version of Gradle.
    Returns:
      The dependency.

  - ### getConstraints

    DependencyConstraintHandler getConstraints()
    Returns the dependency constraint handler for this project.
    Returns:
      the dependency constraint handler for this project
    Since:
      4.5

  - ### constraints

    void constraints(Action<? super DependencyConstraintHandler> configureAction)
    Configures dependency constraint for this project.

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

    Parameters:
      `configureAction` - the action to use to configure module metadata
    Since:
      4.5

  - ### getComponents

    ComponentMetadataHandler getComponents()
    Returns 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.
    Returns:
      the component metadata handler for this project
    Since:
      1.8

  - ### components

    void components(Action<? super ComponentMetadataHandler> configureAction)
    Configures component metadata for this project.

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

    Parameters:
      `configureAction` - the action to use to configure module metadata
    Since:
      1.8

  - ### getModules

    ComponentModuleMetadataHandler getModules()
    Returns 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.
    Returns:
      the component module metadata handler for this project
    Since:
      2.2

  - ### modules

    void modules(Action<? super ComponentModuleMetadataHandler> configureAction)
    Configures module metadata for this project.

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

    Parameters:
      `configureAction` - the action to use to configure module metadata
    Since:
      2.2

  - ### createArtifactResolutionQuery

    ArtifactResolutionQuery createArtifactResolutionQuery()
    Creates an artifact resolution query.

    This is a legacy API and is in maintenance mode. In future versions of Gradle, this API will be deprecated and removed. New code should not use this API. Prefer `ArtifactView.ViewConfiguration.withVariantReselection()` for resolving sources and javadoc.

    Since:
      2.0

  - ### attributesSchema

    AttributesSchema attributesSchema(Action<? super AttributesSchema> configureAction)
    Configures the attributes schema. The action is passed a `AttributesSchema` instance.
    Parameters:
      `configureAction` - the configure action
    Returns:
      the configured schema
    Since:
      3.4

  - ### getAttributesSchema

    AttributesSchema getAttributesSchema()
    Returns the attributes schema for this handler.
    Returns:
      the attributes schema
    Since:
      3.4

  - ### getArtifactTypes

    ArtifactTypeContainer getArtifactTypes()
    Returns the artifact type definitions for this handler.
    Since:
      4.0

  - ### artifactTypes

    void artifactTypes(Action<? super ArtifactTypeContainer> configureAction)
    Configures the artifact type definitions for this handler.
    Since:
      4.0

  - ### registerTransform

    <T extends TransformParameters> void registerTransform(Class<? extends TransformAction<T>> actionType, Action<? super TransformSpec<T>> registrationAction)
    Registers an artifact transform.

    The registration action needs to specify the `from` and `to` attributes. It may also provide parameters for the transform action by using `TransformSpec.parameters(Action)`.

    For example:

         // You have a transform action like this:
         abstract class MyTransform implements TransformAction<Parameters> {
             interface Parameters extends TransformParameters {
                 @Input
                 Property<String> getStringParameter();
                 @InputFiles
                 ConfigurableFileCollection getInputFiles();
             }

             void transform(TransformOutputs outputs) {
                 // ...
             }
         }

         // Then you can register the action like this:

         def artifactType = Attribute.of('artifactType', String)

         dependencies.registerTransform(MyTransform) {
             from.attribute(artifactType, "jar")
             to.attribute(artifactType, "java-classes-directory")

             parameters {
                 stringParameter.set("Some string")
                 inputFiles.from("my-input-file")
             }
         }

    Since:
      5.3
    See Also:
      - `TransformAction`

  - ### platform

    Dependency platform(Object notation)
    Declares a dependency on a platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library.
    Parameters:
      `notation` - the coordinates of the platform
    Since:
      5.0

  - ### platform

    Dependency platform(Object notation, Action<? super Dependency> configureAction)
    Declares a dependency on a platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library.
    Parameters:
      `notation` - the coordinates of the platform
      `configureAction` - the dependency configuration block
    Since:
      5.0

  - ### enforcedPlatform

    Dependency enforcedPlatform(Object notation)
    Declares a dependency on an enforced platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library. An enforced platform is a platform for which the direct dependencies are forced, meaning that they would override any other version found in the graph.
    Parameters:
      `notation` - the coordinates of the platform
    Since:
      5.0

  - ### enforcedPlatform

    Dependency enforcedPlatform(Object notation, Action<? super Dependency> configureAction)
    Declares a dependency on an enforced platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library. An enforced platform is a platform for which the direct dependencies are forced, meaning that they would override any other version found in the graph.
    Parameters:
      `notation` - the coordinates of the platform
      `configureAction` - the dependency configuration block
    Since:
      5.0

  - ### testFixtures

    Dependency testFixtures(Object notation)
    Declares a dependency on the test fixtures of a component.
    Parameters:
      `notation` - the coordinates of the component to use test fixtures for
    Since:
      5.6

  - ### testFixtures

    Dependency testFixtures(Object notation, Action<? super Dependency> configureAction)
    Declares a dependency on the test fixtures of a component and allows configuring the resulting dependency.
    Parameters:
      `notation` - the coordinates of the component to use test fixtures for
    Since:
      5.6

  - ### variantOf

    Provider<MinimalExternalModuleDependency> variantOf(Provider<MinimalExternalModuleDependency> dependencyProvider, Action<? super ExternalModuleDependencyVariantSpec> variantSpec)
    Allows fine-tuning what variant to select for the target dependency. This can be used to specify a classifier, for example.
    Parameters:
      `dependencyProvider` - the dependency provider
      `variantSpec` - the variant specification
    Returns:
      a new dependency provider targeting the configured variant
    Since:
      6.8

  - ### variantOf

    default Provider<MinimalExternalModuleDependency> variantOf(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible, Action<? super ExternalModuleDependencyVariantSpec> variantSpec)
    Allows fine-tuning what variant to select for the target dependency. This can be used to specify a classifier, for example.
    Parameters:
      `dependencyProviderConvertible` - the dependency provider convertible that returns the dependency provider
      `variantSpec` - the variant specification
    Returns:
      a new dependency provider targeting the configured variant
    Since:
      7.3

  - ### platform

    default Provider<MinimalExternalModuleDependency> platform(Provider<MinimalExternalModuleDependency> dependencyProvider)
    Configures this dependency provider to select the platform variant of the target component
    Parameters:
      `dependencyProvider` - the dependency provider
    Returns:
      a new dependency provider targeting the platform variant of the component
    Since:
      6.8

  - ### platform

    default Provider<MinimalExternalModuleDependency> platform(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)
    Configures this dependency provider to select the platform variant of the target component
    Parameters:
      `dependencyProviderConvertible` - the dependency provider convertible that returns the dependency provider
    Returns:
      a new dependency provider targeting the platform variant of the component
    Since:
      7.3

  - ### enforcedPlatform

    Provider<MinimalExternalModuleDependency> enforcedPlatform(Provider<MinimalExternalModuleDependency> dependencyProvider)
    Configures this dependency provider to select the enforced-platform variant of the target component
    Parameters:
      `dependencyProvider` - the dependency provider
    Returns:
      a new dependency provider targeting the enforced-platform variant of the component
    Since:
      7.3

  - ### enforcedPlatform

    default Provider<MinimalExternalModuleDependency> enforcedPlatform(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)
    Configures this dependency provider to select the enforced-platform variant of the target component
    Parameters:
      `dependencyProviderConvertible` - the dependency provider convertible that returns the dependency provider
    Returns:
      a new dependency provider targeting the enforced-platform variant of the component
    Since:
      7.3

  - ### testFixtures

    default Provider<MinimalExternalModuleDependency> testFixtures(Provider<MinimalExternalModuleDependency> dependencyProvider)
    Configures this dependency provider to select the test fixtures of the target component
    Parameters:
      `dependencyProvider` - the dependency provider
    Returns:
      a new dependency provider targeting the test fixtures of the component
    Since:
      6.8

  - ### testFixtures

    default Provider<MinimalExternalModuleDependency> testFixtures(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)
    Configures this dependency provider to select the test fixtures of the target component
    Parameters:
      `dependencyProviderConvertible` - the dependency provider convertible that returns the dependency provider
    Returns:
      a new dependency provider targeting the test fixtures of the component
    Since:
      7.3