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

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

### Advanced dependency configuration

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

    dependencies {
        configurationName(dependencyNotation){
            configStatement1
            configStatement2
        }
    }

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 `ModuleDependency.exclude(java.util.Map)`.
- 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
        }
    }

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 `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("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"
            }
        }
    }

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

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

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

#### File dependencies

You can also add a dependency using a `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"))
    }

File dependencies are represented using a `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())
    }

### Properties

Property | Description
`components` | 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.
`constraints` | The dependency constraint handler for this project.
`extensions` | The container of extensions.
`modules` | 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)` | Configures component metadata for this project.
`constraints(configureAction)` | Configures dependency constraint 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()` | Creates an artifact resolution query.
`enforcedPlatform(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.
`enforcedPlatform(notation, 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.
`enforcedPlatform(dependencyProvider)` | Configures this dependency provider to select the enforced-platform variant of the target component
`enforcedPlatform(dependencyProviderConvertible)` | Configures this dependency provider to select the enforced-platform variant of the target component
`gradleApi()` | Creates a dependency on the API of the current version of Gradle.
`gradleTestKit()` | 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.
`modules(configureAction)` | Configures module metadata for this project.
`platform(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.
`platform(notation, 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.
`platform(dependencyProvider)` | Configures this dependency provider to select the platform variant of the target component
`platform(dependencyProviderConvertible)` | Configures this dependency provider to select the platform variant of the target component
`project()` | Incubating Creates a dependency on the current project.
`project(notation)` | Creates a dependency on a project.
`registerTransform(actionType, registrationAction)` | Registers an artifact transform.

### Script blocks

No script blocks

### Property details

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

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.

#### `DependencyConstraintHandler` `constraints` (read-only)

The dependency constraint handler for this project.

#### `ExtensionContainer` `extensions` (read-only)

The container of extensions.

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

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)

Configures component metadata for this project.

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

#### `void` `constraints`(``Action`<? super `DependencyConstraintHandler`>` configureAction)

Configures dependency constraint for this project.

This method executes the given action against the `DependencyConstraintHandler` 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.

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 <UNHANDLED-LINK>ArtifactView.ViewConfiguration#withVariantReselection()</UNHANDLED-LINK> for resolving sources and javadoc.

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

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

#### ``Provider`<`MinimalExternalModuleDependency`>` `enforcedPlatform`(``Provider`<`MinimalExternalModuleDependency`>` dependencyProvider)

Configures this dependency provider to select the enforced-platform variant of the target component

#### ``Provider`<`MinimalExternalModuleDependency`>` `enforcedPlatform`(``ProviderConvertible`<`MinimalExternalModuleDependency`>` dependencyProviderConvertible)

Configures this dependency provider to select the enforced-platform variant of the target component

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

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

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

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

#### ``Provider`<`MinimalExternalModuleDependency`>` `platform`(``Provider`<`MinimalExternalModuleDependency`>` dependencyProvider)

Configures this dependency provider to select the platform variant of the target component

#### ``Provider`<`MinimalExternalModuleDependency`>` `platform`(``ProviderConvertible`<`MinimalExternalModuleDependency`>` dependencyProviderConvertible)

Configures this dependency provider to select the platform variant of the target component

#### `Dependency` `project`()

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

Creates a dependency on the current project.

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

Creates a dependency on a project.

#### `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(org.gradle.api.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")
        }
    }