DependencyHandler

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
}

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

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

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

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

Client module dependencies

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

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

Properties

Link copied to clipboard

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

Functions

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

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<in U>)
Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
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<in U>)
Adds a dependency provider to the given configuration, eventually configures the dependency using the given action.
Link copied to clipboard
abstract fun artifactTypes(configureAction: Action<in ArtifactTypeContainer>)
Configures the artifact type definitions for this handler.
Link copied to clipboard
abstract fun attributesSchema(configureAction: Action<in AttributesSchema>): AttributesSchema
Configures the attributes schema.
Link copied to clipboard
abstract fun components(configureAction: Action<in ComponentMetadataHandler>)
Configures component metadata for this project.
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.

Link copied to clipboard
abstract fun constraints(configureAction: Action<in DependencyConstraintHandler>)
Configures dependency constraint for this project.
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.
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.

Link copied to clipboard
Creates an artifact resolution query.
Link copied to clipboard

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

Link copied to clipboard
abstract fun enforcedPlatform(notation: Any): Dependency
abstract fun enforcedPlatform(notation: Any, configureAction: Action<in Dependency>): Dependency
Declares a dependency on an enforced platform.
Configures this dependency provider to select the enforced-platform variant of the target component
Link copied to clipboard
Returns the artifact type definitions for this handler.
Link copied to clipboard
Returns the attributes schema for this handler.
Link copied to clipboard
Returns the component metadata handler for this project.
Link copied to clipboard
Returns the dependency constraint handler for this project.
Link copied to clipboard
Link copied to clipboard
Returns the component module metadata handler for this project.
Link copied to clipboard
abstract fun gradleApi(): Dependency
Creates a dependency on the API of the current version of Gradle.
Link copied to clipboard
abstract fun gradleTestKit(): Dependency
Creates a dependency on the Gradle test-kit API.
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.

Link copied to clipboard
abstract fun localGroovy(): Dependency
Creates a dependency on the Groovy that is distributed with the current version of Gradle.
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.
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.

Link copied to clipboard
abstract fun modules(configureAction: Action<in ComponentModuleMetadataHandler>)
Configures module metadata for this project.
Link copied to clipboard
abstract fun platform(notation: Any): Dependency
abstract fun platform(notation: Any, configureAction: Action<in Dependency>): Dependency
Declares a dependency on a platform.
Configures this dependency provider to select the platform variant of the target component
Link copied to clipboard
abstract fun project(notation: Map<String, out Any>): Dependency
Creates a dependency on a 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.

Link copied to clipboard
abstract fun <T : TransformParameters?> registerTransform(actionType: Class<out TransformAction<T>>, registrationAction: Action<in TransformSpec<T>>)
Registers an artifact transform.
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.

Link copied to clipboard
abstract fun testFixtures(notation: Any): Dependency
Declares a dependency on the test fixtures of a component.
Configures this dependency provider to select the test fixtures of the target component
abstract fun testFixtures(notation: Any, configureAction: Action<in Dependency>): Dependency
Declares a dependency on the test fixtures of a component and allows configuring the resulting dependency.
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.

Link copied to clipboard
Allows fine-tuning what variant to select for the target dependency.