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

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

    • 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