// Copyright 2018 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[declaring_dependencies]]
= Declaring Dependencies

Gradle builds can declare dependencies on modules hosted in repositories, files and other Gradle projects. You can find examples for common scenarios in this section. For more information, see the <<dependency_types.adoc#dependency_types,full reference on all types of dependencies>>.

Every dependency needs to be assigned to a configuration when declared in a build script. For more information on the purpose and syntax of configurations, see <<managing_dependency_configurations.adoc#managing_dependency_configurations,Managing Dependency Configurations>>.

[[sec:declaring_dependency_to_module]]
== Declaring a dependency to a module

Modern software projects rarely build code in isolation. Projects reference modules for the purpose of reusing existing and proven functionality. Upon resolution, selected versions of modules are downloaded from dedicated repositories and stored in the <<dependency_cache.adoc#dependency_cache,dependency cache>> to avoid unnecessary network traffic.

.Resolving dependencies from remote repositories
image::dependency-management-dependencies-to-modules.png[]

[[sub:declaring_dependency_with_version]]
=== Declaring a concrete version of a dependency

A typical example for such a library in a Java project is the link:https://projects.spring.io/spring-framework/[Spring framework]. The following code snippet declares a compile-time dependency on the Spring web module by its coordinates: `org.springframework:spring-web:5.0.2.RELEASE`. Gradle resolves the module including its transitive dependencies from the link:https://search.maven.org/[Maven Central repository] and uses it to compile Java source code. The version attribute of the dependency coordinates points to a _concrete version_ indicating that the underlying artifacts do not change over time. The use of concrete versions ensure reproducibility for the aspect of dependency resolution.

.Declaring a dependency with a concrete version
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/concreteVersion/groovy",files="build.gradle[tags=dependencies]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/concreteVersion/kotlin",files="build.gradle.kts[tags=dependencies]"]
====

A Gradle project can define other types of repositories hosting modules. You can learn more about the syntax and API in the section on <<declaring_repositories.adoc#declaring_repositories,declaring repositories>>. Refer to <<java_plugin.adoc#java_plugin, the chapter on the Java Plugin>> for a deep dive on declaring dependencies for a Java project. The resolution behavior for dependencies is <<customizing_dependency_resolution_behavior.adoc#customizing_dependency_resolution_behavior,highly customizable>>.

=== Declaring a dependency without version

A recommended practice for larger projects is to declare dependencies without versions and use <<managing_transitive_dependencies.adoc#sec:dependency_constraints,dependency constraints>> for version declaration. The advantage is that dependency constraints allow you to manage versions of all dependencies, including transitive ones, in one place.

.Declaring a dependency without version
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/withoutVersion/groovy",files="build.gradle[tags=dependencies-without-version]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/withoutVersion/kotlin",files="build.gradle.kts[tags=dependencies-without-version]"]
====

[[sub:declaring_dependency_with_dynamic_version]]
=== Declaring a dynamic version

Projects might adopt a more aggressive approach for consuming dependencies to modules. For example you might want to always integrate the latest version of a dependency to consume cutting edge features at any given time. A _dynamic version_ allows for resolving the latest version or the latest version of a version range for a given module.

[NOTE]
====
Using dynamic versions in a build bears the risk of potentially breaking it. As soon as a new version of the dependency is released that contains an incompatible API change your source code might stop compiling.
====

.Declaring a dependency with a dynamic version
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/dynamicVersion/groovy",files="build.gradle[tags=dependencies]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/dynamicVersion/kotlin",files="build.gradle.kts[tags=dependencies]"]
====

A link:https://scans.gradle.com/[build scan] can effectively visualize dynamic dependency versions and their respective, selected versions.

.Dynamic dependencies in build scan
image::dependency-management-dynamic-dependency-build-scan.png[]

By default, Gradle caches dynamic versions of dependencies for 24 hours. Within this time frame, Gradle does not try to resolve newer versions from the declared repositories. The <<troubleshooting_dependency_resolution.adoc#sub:dynamic_versions_and_changing_modules,threshold can be configured>> as needed for example if you want to resolve new versions earlier.

[[sub:declaring_dependency_with_changing_version]]
=== Declaring a changing version

A team might decide to implement a series of features before releasing a new version of the application or library. A common strategy to allow consumers to integrate an unfinished version of their artifacts early and often is to release a module with a so-called _changing version_. A changing version indicates that the feature set is still under active development and hasn't released a stable version for general availability yet.

In Maven repositories, changing versions are commonly referred to as link:https://maven.apache.org/guides/getting-started/index.html#What_is_a_SNAPSHOT_version[snapshot versions]. Snapshot versions contain the suffix `-SNAPSHOT`. The following example demonstrates how to declare a snapshot version on the Spring dependency.

.Declaring a dependency with a changing version
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/changingVersion/groovy",files="build.gradle[tags=dependencies]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/changingVersion/kotlin",files="build.gradle.kts[tags=dependencies]"]
====

By default, Gradle caches changing versions of dependencies for 24 hours. Within this time frame, Gradle does not try to resolve newer versions from the declared repositories. The <<troubleshooting_dependency_resolution.adoc#sub:dynamic_versions_and_changing_modules,threshold can be configured>> as needed for example if you want to resolve new snapshot versions earlier.

Gradle is flexible enough to treat any version as changing version e.g. if you wanted to model snapshot behavior for an Ivy module. All you need to do is to set the property link:{javadocPath}/org/gradle/api/artifacts/ExternalModuleDependency.html#setChanging-boolean-[ExternalModuleDependency.setChanging(boolean)] to `true`.

[[sub:declaring_dependency_rich_version]]
=== Rich version declaration

Gradle supports a rich model for declaring versions, which allows to combine different level of version information.
The terms and their meaning are explained below, from the strongest to the weakest:

`strictly`::
Any version not matched by this version notation will be excluded.
This is the strongest version declaration.
It will cause dependency resolution to fail if no version acceptable by this clause can be selected.
This term supports dynamic versions.
+
When defined, overrides previous `require` declaration and clears previous `reject`.

`require`::
Implies that the selected version cannot be lower than what `require` accepts but could be higher through conflict resolution, even if higher has an exclusive higher bound.
This is what a direct version on a dependency translates to.
This term supports dynamic versions.
+
When defined, overrides previous `strictly` declaration and clears previous `reject`.

`prefer`::
This is a very soft version declaration.
It applies only if there is no stronger non dynamic opinion on a version for the module.
This term does not support dynamic versions.
+
Definition can complement `strictly` or `require`.

There is also an additional term outside of the level hierarchy:

`reject`::
Declares that specific version(s) are not accepted for the module.
This will cause dependency resolution to fail if the only versions selectable are also rejected.
This term supports dynamic versions.

The following table illustrates a number of use cases and how to combine the different terms for rich version declaration:

.Rich version use cases
[%header%autowidth,compact]
|===
| Which version(s) of this dependency are acceptable? | `strictly` | `require` | `prefer` | `rejects` | Selection result

| Tested with version `1.5`, believe all future versions should work
|
| 1.5
|
|
| Any version starting from `1.5`, equivalent of `org:foo:1.5`. An upgrade to `2.4` is accepted.

| Tested with `1.5`, soft constraint upgrades according to semantic versioning
|
| [1.0, 2.0[
| 1.5
|
| Any version between `1.0` and `2.0`, `1.5` if nobody else cares. An upgrade to `2.4` is accepted. +
🔒

| Tested with `1.5`, but follows semantic versioning
| [1.0, 2.0[
|
| 1.5
|
| Any version between `1.0` and `2.0` excluded, `1.5` if nobody else cares. +
🔒

| Same as above, with `1.4` known broken
| [1.0, 2.0[
|
| 1.5
| 1.4
| Any version between `1.0` and `2.0` excluded except for `1.4`, `1.5` if nobody else cares. +
🔒

| No opinion, works with `1.5`
|
|
| 1.5
|
| `1.5` if no other opinion, any otherwise

| No opinion, prefer latest release
|
|
| `latest.release`
|
| The latest release at build time +
🔒

| On the edge, latest release, no downgrade
|
| `latest.release`
|
|
| The latest release at build time +
🔒

| No other version than 1.5
| 1.5
|
|
|
| 1.5, or failure if another `strict` or higher `require` constraint disagrees

| `1.5` or a patch version of it exclusively
| [1.5,1.6[
|
|
|
| Latest `1.5.x` patch release, or failure if another `strict` or higher `require` constraint disagrees +
🔒
|===

Lines annotated with a lock (🔒) indicate that leveraging <<dependency_locking.adoc#,dependency locking>> makes sense in this context.
Another concept that relates with rich version declaration is the ability to publish <<publishing_maven.adoc#publishing_maven:resolved_dependencies,resolved versions>> instead of declared ones.


Using `strictly`, especially for a library, must be a well thought process as it can have a serious impact on downstream consumers.
At the same time, used correctly, it will help consumers understand what combination of libraries do not work together in their context.


[NOTE]
====
Rich version information will be preserved when using the Gradle metadata format.
However conversion to Ivy or Maven metadata formats will be lossy.
The highest level will be published, that is `strictly` or `require` over `prefer`.
In addition, any `reject` will be ignored.
====

Rich version declaration is accessed through the `version` DSL method on a dependency or constraint declaration which gives access to link:{javadocPath}/org/gradle/api/artifacts/MutableVersionConstraint.html[MutableVersionConstraint].

.Rich version declaration
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/concreteVersion/groovy",files="build.gradle[tags=rich-version]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/concreteVersion/kotlin",files="build.gradle.kts[tags=rich-version]"]
====

[[sec:declaring_file_dependency]]
== Declaring a file dependency

Projects sometimes do not rely on a binary repository product e.g. JFrog Artifactory or Sonatype Nexus for hosting and resolving external dependencies. It's common practice to host those dependencies on a shared drive or check them into version control alongside the project source code. Those dependencies are referred to as _file dependencies_, the reason being that they represent a file without any <<dependency_management_terminology.adoc#sub:terminology_module_metadata,metadata>> (like information about transitive dependencies, the origin or its author) attached to them.

.Resolving file dependencies from the local file system and a shared drive
image::dependency-management-file-dependencies.png[]

The following example resolves file dependencies from the directories `ant`, `libs` and `tools`.

.Declaring multiple file dependencies
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/fileDependencies/groovy",files="build.gradle[tags=file-dependencies]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/fileDependencies/kotlin",files="build.gradle.kts[tags=file-dependencies]"]
====

As you can see in the code example, every dependency has to define its exact location in the file system.
The most prominent methods for creating a file reference are
link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:files(java.lang.Object++[]++)[Project.files(java.lang.Object...)],
link:{javadocPath}/org/gradle/api/file/ProjectLayout.html#files-java.lang.Object++...++-[ProjectLayout.files(java.lang.Object...)]
and link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:fileTree(java.lang.Object)[Project.fileTree(java.lang.Object)]
Alternatively, you can also define the source directory of one or many file dependencies in the form of a <<repository_types.adoc#sec:flat_dir_resolver,flat directory repository>>.

[[sec:declaring_project_dependency]]
== Declaring a project dependency

Software projects often break up software components into modules to improve maintainability and prevent strong coupling. Modules can define dependencies between each other to reuse code within the same project.

Gradle can model dependencies between modules. Those dependencies are called _project dependencies_ because each module is represented by a Gradle project. At runtime, the build automatically ensures that project dependencies are built in the correct order and added to the classpath for compilation. The chapter <<multi_project_builds.adoc#multi_project_builds,Authoring Multi-Project Builds>> discusses how to set up and configure multi-project builds in more detail.

.Dependencies between projects
image::dependency-management-project-dependencies.png[]

The following example declares the dependencies on the `utils` and `api` project from the `web-service` project. The method link:{groovyDslPath}/org.gradle.api.Project.html#org.gradle.api.Project:project(java.lang.String)[Project.project(java.lang.String)] creates a reference to a specific subproject by path.

.Declaring project dependencies
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/projectDependencies/groovy",files="build.gradle[tags=project-dependencies]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/projectDependencies/kotlin",files="build.gradle.kts[tags=project-dependencies]"]
====

[[sub:resolve_specific_artifacts_from_dependency]]
== Resolving specific artifacts from a module dependency

Whenever Gradle tries to resolve a module from a Maven or Ivy repository, it looks for a metadata file and the default artifact file, a JAR. The build fails if none of these artifact files can be resolved. Under certain conditions, you might want to tweak the way Gradle resolves artifacts for a dependency.

- The dependency only provides a non-standard artifact without any metadata e.g. a ZIP file.
- The module metadata declares more than one artifact e.g. as part of an Ivy dependency descriptor.
- You only want to download a specific artifact without any of the transitive dependencies declared in the metadata.

Gradle is a polyglot build tool and not limited to just resolving Java libraries. Let's assume you wanted to build a web application using JavaScript as the client technology. Most projects check in external JavaScript libraries into version control. An external JavaScript library is no different than a reusable Java library so why not download it from a repository instead?

link:https://developers.google.com/speed/libraries/[Google Hosted Libraries] is a distribution platform for popular, open-source JavaScript libraries. With the help of the artifact-only notation you can download a JavaScript library file e.g. JQuery. The `@` character separates the dependency's coordinates from the artifact's file extension.

.Resolving a JavaScript artifact for a declared dependency
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/artifactOnly/groovy",files="build.gradle[tags=artifact-only-dependency-declaration]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/artifactOnly/kotlin",files="build.gradle.kts[tags=artifact-only-dependency-declaration]"]
====

Some modules ship different "flavors" of the same artifact or they publish multiple artifacts that belong to a specific module version but have a different purpose. It's common for a Java library to publish the artifact with the compiled class files, another one with just the source code in it and a third one containing the Javadocs.

In JavaScript, a library may exist as uncompressed or minified artifact. In Gradle, a specific artifact identifier is called _classifier_, a term generally used in Maven and Ivy dependency management.

Let's say we wanted to download the minified artifact of the JQuery library instead of the uncompressed file. You can provide the classifier `min` as part of the dependency declaration.

.Resolving a JavaScript artifact with classifier for a declared dependency
====
include::sample[dir="userguide/dependencyManagement/declaringDependencies/artifactOnlyWithClassifier/groovy",files="build.gradle[tags=artifact-only-dependency-declaration]"]
include::sample[dir="userguide/dependencyManagement/declaringDependencies/artifactOnlyWithClassifier/kotlin",files="build.gradle.kts[tags=artifact-only-dependency-declaration]"]
====

