Interface DependencyHandler
-
- All Superinterfaces:
ExtensionAware
public interface DependencyHandler extends ExtensionAware
A
DependencyHandler
is used to declare dependencies. Dependencies are grouped into configurations (seeConfiguration
).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' // 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){ configStatement1 configStatement2 } }
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
ModuleDependency.exclude(java.util.Map)
. - 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
ModuleDependency.artifact(groovy.lang.Closure)
.
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' } } }
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
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
ExternalModuleDependency
.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
ProjectDependency
.File dependencies
You can also add a dependency using a
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
FileCollectionDependency
.Dependencies to other configurations
You can add a dependency using a
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 aClientModule
.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description Dependency
add(java.lang.String configurationName, java.lang.Object dependencyNotation)
Adds a dependency to the given configuration.Dependency
add(java.lang.String configurationName, java.lang.Object dependencyNotation, Closure configureClosure)
Adds a dependency to the given configuration, and configures the dependency using the given closure.<T> void
addProvider(java.lang.String configurationName, Provider<T> dependencyNotation)
Adds a dependency provider to the given configuration.<T,U extends ExternalModuleDependency>
voidaddProvider(java.lang.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.<T> void
addProviderConvertible(java.lang.String configurationName, ProviderConvertible<T> dependencyNotation)
Adds a dependency provider to the given configuration.<T,U extends ExternalModuleDependency>
voidaddProviderConvertible(java.lang.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.void
artifactTypes(Action<? super ArtifactTypeContainer> configureAction)
Configures the artifact type definitions for this handler.AttributesSchema
attributesSchema(Action<? super AttributesSchema> configureAction)
Configures the attributes schema.void
components(Action<? super ComponentMetadataHandler> configureAction)
Configures component metadata for this project.void
constraints(Action<? super DependencyConstraintHandler> configureAction)
Configures dependency constraint for this project.Dependency
create(java.lang.Object dependencyNotation)
Creates a dependency without adding it to a configuration.Dependency
create(java.lang.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.Dependency
enforcedPlatform(java.lang.Object notation)
Declares a dependency on an enforced platform.Dependency
enforcedPlatform(java.lang.Object notation, Action<? super Dependency> configureAction)
Declares a dependency on an enforced platform.Provider<MinimalExternalModuleDependency>
enforcedPlatform(Provider<MinimalExternalModuleDependency> dependencyProvider)
Configures this dependency provider to select the enforced-platform variant of the target componentdefault Provider<MinimalExternalModuleDependency>
enforcedPlatform(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)
Configures this dependency provider to select the enforced-platform variant of the target componentArtifactTypeContainer
getArtifactTypes()
Returns the artifact type definitions for this handler.AttributesSchema
getAttributesSchema()
Returns the attributes schema for this handler.ComponentMetadataHandler
getComponents()
Returns the component metadata handler for this project.DependencyConstraintHandler
getConstraints()
Returns the dependency constraint handler for this project.ComponentModuleMetadataHandler
getModules()
Returns the component module metadata handler for this project.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.Dependency
module(java.lang.Object notation)
Deprecated.Please use component metadata rules instead.Dependency
module(java.lang.Object notation, Closure configureClosure)
Deprecated.Please use component metadata rules instead.void
modules(Action<? super ComponentModuleMetadataHandler> configureAction)
Configures module metadata for this project.Dependency
platform(java.lang.Object notation)
Declares a dependency on a platform.Dependency
platform(java.lang.Object notation, Action<? super Dependency> configureAction)
Declares a dependency on a platform.default Provider<MinimalExternalModuleDependency>
platform(Provider<MinimalExternalModuleDependency> dependencyProvider)
Configures this dependency provider to select the platform variant of the target componentdefault Provider<MinimalExternalModuleDependency>
platform(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)
Configures this dependency provider to select the platform variant of the target componentDependency
project(java.util.Map<java.lang.String,?> notation)
Creates a dependency on a project.<T extends TransformParameters>
voidregisterTransform(java.lang.Class<? extends TransformAction<T>> actionType, Action<? super TransformSpec<T>> registrationAction)
Registers an artifact transform.Dependency
testFixtures(java.lang.Object notation)
Declares a dependency on the test fixtures of a component.Dependency
testFixtures(java.lang.Object notation, Action<? super Dependency> configureAction)
Declares a dependency on the test fixtures of a component and allows configuring the resulting dependency.default Provider<MinimalExternalModuleDependency>
testFixtures(Provider<MinimalExternalModuleDependency> dependencyProvider)
Configures this dependency provider to select the test fixtures of the target componentdefault Provider<MinimalExternalModuleDependency>
testFixtures(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible)
Configures this dependency provider to select the test fixtures of the target componentProvider<MinimalExternalModuleDependency>
variantOf(Provider<MinimalExternalModuleDependency> dependencyProvider, Action<? super ExternalModuleDependencyVariantSpec> variantSpec)
Allows fine-tuning what variant to select for the target dependency.default Provider<MinimalExternalModuleDependency>
variantOf(ProviderConvertible<MinimalExternalModuleDependency> dependencyProviderConvertible, Action<? super ExternalModuleDependencyVariantSpec> variantSpec)
Allows fine-tuning what variant to select for the target dependency.-
Methods inherited from interface org.gradle.api.plugins.ExtensionAware
getExtensions
-
-
-
-
Method Detail
-
add
@Nullable Dependency add(java.lang.String configurationName, java.lang.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(java.lang.String configurationName, java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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.
-
module
@Deprecated Dependency module(java.lang.Object notation)
Deprecated.Please use component metadata rules instead. This method will be removed in Gradle 9.0.Creates a dependency on a client module.- Parameters:
notation
- The module notation, in one of the notations described above.- Returns:
- The dependency.
-
module
@Deprecated Dependency module(java.lang.Object notation, Closure configureClosure)
Deprecated.Please use component metadata rules instead. This method will be removed in Gradle 9.0.Creates a dependency on a client module. The dependency is configured using the given closure before it is returned.- Parameters:
notation
- The module notation, in one of the notations described above.configureClosure
- The closure to use to configure the dependency.- Returns:
- The dependency.
-
project
Dependency project(java.util.Map<java.lang.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.- Since:
- 2.0
-
attributesSchema
AttributesSchema attributesSchema(Action<? super AttributesSchema> configureAction)
Configures the attributes schema. The action is passed aAttributesSchema
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(java.lang.Class<? extends TransformAction<T>> actionType, Action<? super TransformSpec<T>> registrationAction)
Registers an artifact transform.The registration action needs to specify the
from
andto
attributes. It may also provide parameters for the transform action by usingTransformSpec.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:
TransformAction
-
platform
Dependency platform(java.lang.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(java.lang.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 platformconfigureAction
- the dependency configuration block- Since:
- 5.0
-
enforcedPlatform
Dependency enforcedPlatform(java.lang.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(java.lang.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 platformconfigureAction
- the dependency configuration block- Since:
- 5.0
-
testFixtures
Dependency testFixtures(java.lang.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(java.lang.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 providervariantSpec
- 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 providervariantSpec
- 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
-
-