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-library")
}
dependencies {
// Configuring dependency to specific configuration of the module
// This notation should _only_ be used for Ivy dependencies
implementation(group: "org.someOrg", name: "someModule", version: "1.0", configuration: "someConf")
// Configuring dependency on 'someLib' module
implementation(group: 'org.myorg', name: 'someLib', version:'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'
}
}
}
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.
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)
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") } }