# DependencyHandler

@ServiceScope(value = Project::class)
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 {
        configurationName(dependencyNotation)
    }

Content copied to clipboard

Example shows a basic way of declaring dependencies.

    plugins {
        id("java-library")
    }

    dependencies {
        // Declare dependency on module components
        // Coordinates are separated by a single colon -- group:name:version
        implementation("org.apache.commons:commons-lang3:3.17.0")
        testImplementation("org.mockito:mockito-core:5.18.0")

        // Declare dependency on arbitrary files
        implementation(files("hibernate.jar", "libs/spring.jar"))

        // Declare dependency on all jars from the 'libs' directory
        implementation(fileTree("libs"))
    }

Content copied to clipboard

## Advanced dependency configuration

To perform advanced configuration on a dependency when it is declared, you can pass an additional configuration closure:

    dependencies {
        configurationName(dependencyNotation){
            configStatement1configStatement2
        }
    }

Content copied to clipboard
Examples of advanced dependency declaration include:

- 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-library")
    }

    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
Below are more examples of advanced configuration, which may be useful when a target component has multiple artifacts:

- Declaring dependency on a specific configuration of the component.
- Declaring explicit artifact requests. 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("org.someOrg:someModule:1.0") {
            targetConfiguration = "someConf"
        }

        // Configuring dependency on 'someLib' module
        implementation("org.myorg:someLib: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"
            }
        }
    }

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

The following notation is used to declare a dependency on an external module:

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

All properties, except name, are optional.

External dependencies are represented by a org.gradle.api.artifacts.ExternalModuleDependency.

    plugins {
        id("java-library")
    }

    dependencies {
        // Declare dependency on module components
        // Coordinates are separated by a single colon -- group:name:version
        implementation("org.apache.commons:commons-lang3:3.17.0")
        testImplementation("org.mockito:mockito-core:5.18.0")
    }

Content copied to clipboard

### Project dependencies

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

`configurationName(project(":some-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-library")
    }

    dependencies {
        // Declare dependency on arbitrary files
        implementation(files("hibernate.jar", "libs/spring.jar"))

        // Declare dependency on all jars from the 'libs' directory
        implementation(fileTree("libs"))
    }

Content copied to clipboard

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

### 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:

    plugins {
        id("groovy")
    }

    dependencies {
        // Declare dependency on the Groovy version that ships with Gradle
        implementation(localGroovy())

        // Declare dependency on the Gradle API interfaces and classes
        implementation(gradleApi())

        // Declare dependency on the Gradle test-kit to test build logic
        testImplementation(gradleTestKit())
    }

Content copied to clipboard

## Functions

add
Link copied to clipboard
@Nullable
abstract fun add(configurationName: String, dependencyNotation: Any): @Nullable Dependency
Adds a dependency to the given configuration.
@Nullable
abstract fun add(configurationName: String, dependencyNotation: Any, configureClosure: Closure): @Nullable Dependency
Adds a dependency to the given configuration, and configures the dependency using the given closure.
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<in U>)
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<in U>)
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<in ArtifactTypeContainer>)
Configures the artifact type definitions for this handler.
attributesSchema
Link copied to clipboard
abstract fun attributesSchema(configureAction: Action<in AttributesSchema>): AttributesSchema
Configures the attributes schema.
components
Link copied to clipboard
abstract fun components(configureAction: Action<in ComponentMetadataHandler>)
Configures component metadata for this project.
constraints
Link copied to clipboard
abstract fun constraints(configureAction: Action<in DependencyConstraintHandler>)
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.
createArtifactResolutionQuery
Link copied to clipboard
abstract fun createArtifactResolutionQuery(): ArtifactResolutionQuery
Creates an artifact resolution query.
enforcedPlatform
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.
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
@Internal
abstract fun getExtensions(): ExtensionContainer
The container of extensions.
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.
localGroovy
Link copied to clipboard
abstract fun localGroovy(): Dependency
Creates a dependency on the Groovy that is distributed with the current version of Gradle.
modules
Link copied to clipboard
abstract fun modules(configureAction: Action<in ComponentModuleMetadataHandler>)
Configures module metadata for this project.
platform
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.
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
@Incubating
abstract fun project(): ProjectDependency
Creates a dependency on the current project.
@Incubating
abstract fun project(projectPath: String): ProjectDependency
Creates a dependency on a project by path.
abstract fun project(notation: Map<String, out Any>): Dependency
Creates a dependency on a project.
registerTransform
Link copied to clipboard
abstract fun <T : TransformParameters?> registerTransform(actionType: Class<out TransformAction<T>>, registrationAction: Action<in TransformSpec<T>>)
Registers an artifact transform.
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<in Dependency>): Dependency
Declares a dependency on the test fixtures of a component and allows configuring the resulting dependency.
variantOf
Link copied to clipboard
abstract fun variantOf(dependencyProvider: Provider<MinimalExternalModuleDependency>, variantSpec: Action<in ExternalModuleDependencyVariantSpec>): Provider<MinimalExternalModuleDependency>
open fun variantOf(dependencyProviderConvertible: ProviderConvertible<MinimalExternalModuleDependency>, variantSpec: Action<in ExternalModuleDependencyVariantSpec>): Provider<MinimalExternalModuleDependency>
Allows fine-tuning what variant to select for the target dependency.