gradle
8.6

# DependencyHandler

interface DependencyHandler : ExtensionAware(source)

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

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

    dependencies {
        configurationNamedependencyNotation
    }

Content copied to clipboard

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')
    }

Content copied to clipboard

## 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){
            configStatement1configStatement2
        }
    }

Content copied to clipboard
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 exclude.
- 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
      }
    }

Content copied to clipboard
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 artifact.

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

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

      //configuring dependency on 'someLib' module
      implementation(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'
        }
      }
    }

Content copied to clipboard

## 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 org.gradle.api.artifacts.Dependency directly:

`configurationName <instance>`

Dependencies can also be declared with a org.gradle.api.provider.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 .

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

Content copied to clipboard

### 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 org.gradle.api.artifacts.ProjectDependency.

### File dependencies

You can also add a dependency using a org.gradle.api.file.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')
    }

Content copied to clipboard

File dependencies are represented using a org.gradle.api.artifacts.SelfResolvingDependency.

### Dependencies to other configurations

You can add a dependency using a org.gradle.api.artifacts.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()
    }

Content copied to clipboard

### Client module dependencies

Client module dependencies are deprecated and will be removed in Gradle 9.0. Use component metadata rules instead.

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

    configurationName module(moduleNotation) {
        module dependencies
    }

Content copied to clipboard
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 org.gradle.api.artifacts.ClientModule.

## Properties

extra
Link copied to clipboard
val ExtensionAware.extra: ExtraPropertiesExtension

The extra properties extension in this object's extension container.

## Functions

add
Link copied to clipboard
@Nullable
abstract fun add(configurationName: String, dependencyNotation: Any): Dependency
Adds a dependency to the given configuration.
@Nullable
abstract fun add(configurationName: String, dependencyNotation: Any, configureClosure: Closure): Dependency
Adds a dependency to the given configuration, and configures the dependency using the given closure.
add
Link copied to clipboard
inline fun <T : ModuleDependency> DependencyHandler.add(configuration: String, dependency: T, dependencyConfiguration: T.() -> Unit): T
inline fun DependencyHandler.add(configuration: String, dependencyNotation: String, dependencyConfiguration: ExternalModuleDependency.() -> Unit): ExternalModuleDependency

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

addProvider
Link copied to clipboard
abstract fun <T> addProvider(configurationName: String, dependencyNotation: Provider<T>)
Adds a dependency provider to the given configuration.
abstract fun <T, U : ExternalModuleDependency?> addProvider(configurationName: String, dependencyNotation: Provider<T>, configuration: Action<out Any>)
Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
addProviderConvertible
Link copied to clipboard
abstract fun <T> addProviderConvertible(configurationName: String, dependencyNotation: ProviderConvertible<T>)
Adds a dependency provider to the given configuration.
abstract fun <T, U : ExternalModuleDependency?> addProviderConvertible(configurationName: String, dependencyNotation: ProviderConvertible<T>, configuration: Action<out Any>)
Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
artifactTypes
Link copied to clipboard
abstract fun artifactTypes(configureAction: Action<out Any>)
Configures the artifact type definitions for this handler.
attributesSchema
Link copied to clipboard
abstract fun attributesSchema(configureAction: Action<out Any>): AttributesSchema
Configures the attributes schema.
components
Link copied to clipboard
abstract fun components(configureAction: Action<out Any>)
Configures component metadata for this project.
configure
Link copied to clipboard
inline fun <T : Any> ExtensionAware.configure(noinline configuration: T.() -> Unit)

Executes the given configuration block against the extension of the specified type.

constraints
Link copied to clipboard
abstract fun constraints(configureAction: Action<out Any>)
Configures dependency constraint for this project.
create
Link copied to clipboard
abstract fun create(dependencyNotation: Any): Dependency
Creates a dependency without adding it to a configuration.
abstract fun create(dependencyNotation: Any, configureClosure: Closure): Dependency
Creates a dependency without adding it to a configuration, and configures the dependency using the given closure.
create
Link copied to clipboard
@Incubating
inline fun DependencyHandler.create(dependencyNotation: String, dependencyConfiguration: ExternalModuleDependency.() -> Unit): ExternalModuleDependency

Creates a dependency without adding it to a configuration.

fun DependencyHandler.create(group: String, name: String, version: String? = null, configuration: String? = null, classifier: String? = null, ext: String? = null): ExternalModuleDependency

Creates a dependency on a module without adding it to a configuration.

createArtifactResolutionQuery
Link copied to clipboard
abstract fun createArtifactResolutionQuery(): ArtifactResolutionQuery
Creates an artifact resolution query.
embeddedKotlin
Link copied to clipboard
fun DependencyHandler.embeddedKotlin(module: String): Any

Builds the dependency notation for the named Kotlin module at the embedded version (currently 1.9.20).

enforcedPlatform
Link copied to clipboard
abstract fun enforcedPlatform(notation: Any): Dependency
abstract fun enforcedPlatform(notation: Any, configureAction: Action<out Any>): Dependency
Declares a dependency on an enforced platform.
abstract fun enforcedPlatform(dependencyProvider: Provider<MinimalExternalModuleDependency>): Provider<MinimalExternalModuleDependency>
open fun enforcedPlatform(dependencyProviderConvertible: ProviderConvertible<MinimalExternalModuleDependency>): Provider<MinimalExternalModuleDependency>
Configures this dependency provider to select the enforced-platform variant of the target component
getArtifactTypes
Link copied to clipboard
abstract fun getArtifactTypes(): ArtifactTypeContainer
Returns the artifact type definitions for this handler.
getAttributesSchema
Link copied to clipboard
abstract fun getAttributesSchema(): AttributesSchema
Returns the attributes schema for this handler.
getComponents
Link copied to clipboard
abstract fun getComponents(): ComponentMetadataHandler
Returns the component metadata handler for this project.
getConstraints
Link copied to clipboard
abstract fun getConstraints(): DependencyConstraintHandler
Returns the dependency constraint handler for this project.
getExtensions
Link copied to clipboard
abstract fun getExtensions(): ExtensionContainer
getModules
Link copied to clipboard
abstract fun getModules(): ComponentModuleMetadataHandler
Returns the component module metadata handler for this project.
gradleApi
Link copied to clipboard
abstract fun gradleApi(): Dependency
Creates a dependency on the API of the current version of Gradle.
gradleTestKit
Link copied to clipboard
abstract fun gradleTestKit(): Dependency
Creates a dependency on the Gradle test-kit API.
kotlin
Link copied to clipboard
fun DependencyHandler.kotlin(module: String, version: String? = null): Any

Builds the dependency notation for the named Kotlin module at the given version.

localGroovy
Link copied to clipboard
abstract fun localGroovy(): Dependency
Creates a dependency on the Groovy that is distributed with the current version of Gradle.
module
Link copied to clipboard
abstract fun module(notation: Any): Dependency
abstract fun module(notation: Any, configureClosure: Closure): Dependency
Creates a dependency on a client module.
module
Link copied to clipboard
fun DependencyHandler.module(notation: Any, clientModuleConfiguration: ClientModuleScope.() -> Unit): ClientModule
fun DependencyHandler.module(group: String, name: String, version: String? = null, configuration: String? = null, classifier: String? = null, ext: String? = null): ClientModule
fun DependencyHandler.module(group: String, name: String, version: String? = null, configuration: String? = null, classifier: String? = null, ext: String? = null, clientModuleConfiguration: ClientModuleScope.() -> Unit): ClientModule

Creates a dependency on a client module without adding it to a configuration.

modules
Link copied to clipboard
abstract fun modules(configureAction: Action<out Any>)
Configures module metadata for this project.
platform
Link copied to clipboard
abstract fun platform(notation: Any): Dependency
abstract fun platform(notation: Any, configureAction: Action<out Any>): Dependency
Declares a dependency on a platform.
open fun platform(dependencyProvider: Provider<MinimalExternalModuleDependency>): Provider<MinimalExternalModuleDependency>
open fun platform(dependencyProviderConvertible: ProviderConvertible<MinimalExternalModuleDependency>): Provider<MinimalExternalModuleDependency>
Configures this dependency provider to select the platform variant of the target component
project
Link copied to clipboard
abstract fun project(notation: Map<String, out Any>): Dependency
Creates a dependency on a project.
project
Link copied to clipboard
inline fun DependencyHandler.project(vararg notation: Pair<String, Any?>): Dependency

Kotlin extension function for org.gradle.api.artifacts.dsl.DependencyHandler.project.

fun DependencyHandler.project(path: String, configuration: String? = null): ProjectDependency

Creates a dependency on a project without adding it to a configuration.

registerTransform
Link copied to clipboard
abstract fun <T : TransformParameters?> registerTransform(actionType: Class<out TransformAction<T>>, registrationAction: Action<out Any>)
Registers an artifact transform.
registerTransform
Link copied to clipboard
inline fun <T : TransformParameters> DependencyHandler.registerTransform(actionType: KClass<out TransformAction<T>>, registrationAction: Action<in TransformSpec<T>>)

Kotlin extension function taking kotlin.reflect.KClass for org.gradle.api.artifacts.dsl.DependencyHandler.registerTransform.

testFixtures
Link copied to clipboard
abstract fun testFixtures(notation: Any): Dependency
Declares a dependency on the test fixtures of a component.
open fun testFixtures(dependencyProvider: Provider<MinimalExternalModuleDependency>): Provider<MinimalExternalModuleDependency>
open fun testFixtures(dependencyProviderConvertible: ProviderConvertible<MinimalExternalModuleDependency>): Provider<MinimalExternalModuleDependency>
Configures this dependency provider to select the test fixtures of the target component
abstract fun testFixtures(notation: Any, configureAction: Action<out Any>): Dependency
Declares a dependency on the test fixtures of a component and allows configuring the resulting dependency.
the
Link copied to clipboard
inline fun <T : Any> ExtensionAware.the(): T

Returns the extension of the specified type.

fun <T : Any> ExtensionAware.the(extensionType: KClass<T>): T

Returns the extension of the specified extensionType.

variantOf
Link copied to clipboard
abstract fun variantOf(dependencyProvider: Provider<MinimalExternalModuleDependency>, variantSpec: Action<out Any>): Provider<MinimalExternalModuleDependency>
open fun variantOf(dependencyProviderConvertible: ProviderConvertible<MinimalExternalModuleDependency>, variantSpec: Action<out Any>): Provider<MinimalExternalModuleDependency>
Allows fine-tuning what variant to select for the target dependency.