Table of Contents
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' // 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') }
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' } } }
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.
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' }
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
.
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
.
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.
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 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 ClientModule
.
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. |
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. |
module(notation) | Deprecated Creates a dependency on a client module. |
module(notation, configureClosure) | Deprecated Creates a dependency on a client module. The dependency is configured using the given closure before it is returned. |
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(notation) | Creates a dependency on a project. |
registerTransform(actionType, registrationAction) | Registers an artifact transform. |
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.
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)
Action
<? super ComponentMetadataHandler
>Configures component metadata for this project.
This method executes the given action against the ComponentMetadataHandler
for this project.
void
constraints
(Action
<? super DependencyConstraintHandler
>
configureAction)
Action
<? super DependencyConstraintHandler
>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.
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)
Action
<? super Dependency
>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)
Provider
<MinimalExternalModuleDependency
>Provider
<MinimalExternalModuleDependency
>Configures this dependency provider to select the enforced-platform variant of the target component
Provider
<MinimalExternalModuleDependency
>
enforcedPlatform
(ProviderConvertible
<MinimalExternalModuleDependency
>
dependencyProviderConvertible)
Provider
<MinimalExternalModuleDependency
>ProviderConvertible
<MinimalExternalModuleDependency
>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.
Dependency
module
(Object
notation)
Note: This method is deprecated and will be removed in the next major version of Gradle.
Creates a dependency on a client module.
Dependency
module
(Object
notation, Closure
configureClosure)
Note: This method is deprecated and will be removed in the next major version of Gradle.
Creates a dependency on a client module. The dependency is configured using the given closure before it is returned.
void
modules
(Action
<? super ComponentModuleMetadataHandler
>
configureAction)
Action
<? super ComponentModuleMetadataHandler
>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)
Action
<? super Dependency
>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)
Provider
<MinimalExternalModuleDependency
>Provider
<MinimalExternalModuleDependency
>Configures this dependency provider to select the platform variant of the target component
Provider
<MinimalExternalModuleDependency
>
platform
(ProviderConvertible
<MinimalExternalModuleDependency
>
dependencyProviderConvertible)
Provider
<MinimalExternalModuleDependency
>ProviderConvertible
<MinimalExternalModuleDependency
>Configures this dependency provider to select the platform variant of the target component
Dependency
project
(Map
<String
, ?>
notation)
Map
<String
, ?>Creates a dependency on a project.
void
registerTransform
(Class
<? extends TransformAction
<T
>>
actionType, Action
<? super TransformSpec
<T
>>
registrationAction)
Class
<? extends TransformAction
<T
>>Action
<? super TransformSpec
<T
>>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") } }