// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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.

[[dependency_management_basics]]
= Dependency Management Basics

Gradle has built-in support for *dependency management*.

image::gradle-basic-7.png[]

Dependency management is an automated technique for declaring and resolving external resources required by a project.

Gradle build scripts define the process to build projects that may require external dependencies.
Dependencies refer to JARs, plugins, libraries, or source code that support building your project.

== Version Catalog

Version catalogs provide a way to centralize your dependency declarations in a `libs.versions.toml` file.

The catalog makes sharing dependencies and version configurations between subprojects simple.
It also allows teams to enforce versions of libraries and plugins in large projects.

The version catalog typically contains four sections:

1. [versions] to declare the version numbers that plugins and libraries will reference.
2. [libraries] to define the libraries used in the build files.
3. [bundles] to define a set of dependencies.
4. [plugins] to define plugins.

[source,gradle/libs.versions.toml]
----
[versions]
androidGradlePlugin = "7.4.1"
mockito = "2.16.0"

[libraries]
googleMaterial = { group = "com.google.android.material", name = "material", version = "1.1.0-alpha05" }
mockitoCore = { module = "org.mockito:mockito-core", version.ref = "mockito" }

[plugins]
androidApplication = { id = "com.android.application", version.ref = "androidGradlePlugin" }
----

The file is located in the `gradle` directory so that it can be used by Gradle and IDEs automatically.
The version catalog should be checked into source control: `gradle/libs.versions.toml`.

== Declaring Your Dependencies

To add a dependency to your project, specify a dependency in the dependencies block of your `build.gradle(.kts)` file.

The following `build.gradle.kts` file adds a plugin and two dependencies to the project using the version catalog above:

[source,kotlin]
----
plugins {
   alias(libs.plugins.androidApplication)  // <1>
}

dependencies {
    // Dependency on a remote binary to compile and run the code
    implementation(libs.googleMaterial)    // <2>

    // Dependency on a remote binary to compile and run the test code
    testImplementation(libs.mockitoCore)   // <3>
}
----
<1> Applies the Android Gradle plugin to this project, which adds several features that are specific to building Android apps.
<2> Adds the Material dependency to the project. Material Design provides components for creating a user interface in an Android App. This library will be used to compile and run the Kotlin source code in this project.
<3> Adds the Mockito dependency to the project. Mockito is a mocking framework for testing Java code. This library will be used to compile and run the _test_ source code in this project.

Dependencies in Gradle are grouped by *configurations*.

- The `material` library is added to the `implementation` configuration, which is used for compiling and running _production_ code.
- The `mockito-core` library is added to the `testImplementation` configuration, which is used for compiling and running _test_ code.

NOTE: There are many more configurations available.

== Viewing Project Dependencies

You can view your dependency tree in the terminal using the `./gradlew :app:dependencies` command:

[source,text]
----
$ ./gradlew :app:dependencies

> Task :app:dependencies

------------------------------------------------------------
Project ':app'
------------------------------------------------------------

implementation - Implementation only dependencies for source set 'main'. (n)
\--- com.google.android.material:material:1.1.0-alpha05 (n)

testImplementation - Implementation only dependencies for source set 'test'. (n)
\--- org.mockito:mockito-core:2.16.0 (n)

...
----

Consult the <<glossary.adoc#dependency_management_terminology,Dependency Management chapter>> to learn more.

[.text-right]
**Next Step:** <<task_basics.adoc#task_basics,Learn about Tasks>> >>
