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.
apply plugin: '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.
apply plugin: 'java' //so that I can declare 'implementation' dependencies dependencies { implementation('org.hibernate:hibernate:3.1') { //in case of versions conflict '3.1' version of hibernate wins: force = true //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)
.
apply plugin: '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>
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
.
apply plugin: '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(':someProject')
The notation project(':projectA')
is similar to the syntax you use
when configuring a projectA in a multi-module gradle project.
By default, when you declare dependency to projectA, you actually declare dependency to the 'default' configuration of the projectA. If you need to depend on a specific configuration of projectA, use map notation for projects:
configurationName project(path: ':projectA', configuration: 'someOtherConfiguration')
Project dependencies are represented using a ProjectDependency
.
You can also add a dependency using a FileCollection
:
configurationName files('a file')
apply plugin: '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 SelfResolvingDependency
.
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 apply plugin: '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() }
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 | Incubating The dependency constraint handler for this project. |
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) | Incubating 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) | Incubating 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) | Incubating 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. |
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) | Creates a dependency on a client module. |
module(notation, configureClosure) | 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) | Incubating 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) | Incubating Declares a dependency on a platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library. |
project(notation) | Creates a dependency on a project. |
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.
Note: This property is incubating and may change in a future version of Gradle.
The dependency constraint handler for this project.
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.
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.
Configures component metadata for this project.
This method executes the given action against the ComponentMetadataHandler
for this project.
Note: This method is incubating and may change in a future version of Gradle.
Configures dependency constraint for this project.
This method executes the given action against the DependencyConstraintHandler
for this project.
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.
Creates an artifact resolution query.
Note: This method is incubating and may change in a future version of Gradle.
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
>Note: This method is incubating and may change in a future version of Gradle.
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.
Creates a dependency on the API of the current version of Gradle.
Creates a dependency on the Gradle test-kit API.
Creates a dependency on the Groovy that is distributed with the current version of Gradle.
Creates a dependency on a client module.
Dependency
module
(Object
notation, Closure
configureClosure)
Creates a dependency on a client module. The dependency is configured using the given closure before it is returned.
Configures module metadata for this project.
This method executes the given action against the ComponentModuleMetadataHandler
for this project.
Note: This method is incubating and may change in a future version of Gradle.
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
>Note: This method is incubating and may change in a future version of Gradle.
Declares a dependency on a platform. If the target coordinates represent multiple potential components, the platform component will be selected, instead of the library.
Creates a dependency on a project.