4 minute guide on adding dependencies using Version Catalogs
If you have created a new EmptyActivity project in Android Studio recently, you will notice that the build.gradle.kts files look a lot like this.
And we have a new file called libs.versions.toml .
Introducing Version Catalogs
This is because gradle introduced Version Catalogs in version 7.0 and this has become a default for new Android Studio projects. Gradle version catalogs helps you to add and maintain dependencies and plugins in a more scalable way.
Version catalogs are used to keep all of our dependency declarations in a single place. This allows us to share dependencies and version configurations between modules and projects. So instead of hardcoding dependency names and versions in individual build files across multiple modules/libraries, we define them in the catalog and use them in all of our modules/projects. This flexibility also supports third-party plugins to automatically update the versions for the latest ones, only if we want.
Let’s take a look at how to add a remote library or a remote plugin as a dependency to our Android project.
Adding a remote binary dependency
In this example, let’s add the Room library to our project. It only takes 2 steps 🎉
Step 1: Configure the libs.version.toml file
TOML stands for Tom’s Obvious Minimal Language and it is a configuration file format that’s easy to read due to obvious semantics. On Android, you can find the libs.version.toml file in all Android Studio projects by default. For existing projects, we just need to create one under gradle/libs.version.toml.
This file can contain three sections:
- [versions] — define variables that hold the versions of your dependencies and plugins. You use these variables in the subsequent blocks.
- [libraries] — define the libraries that will be accessed in our Gradle files.
- [plugins] — define the plugin dependencies that will be accessed in our Gradle files.
In order to add Room library to the app, open the libs.version.toml file, under the versions section, follow the below syntax for adding the latest version of Room.
# libs.versions.toml file
# <dependency_or_plugin_name> = "<dependency_or_plugin_version>"
[versions]
roomVersion = "2.6.1"Next, under the libraries section, follow the below syntax for adding the Room dependency.
# libs.version.toml
# Old method to add Room dependency
# implementation "androidx.room:room-runtime:$roomVersion"
# Here, you can consider the colon as delimeter and get the follwoing,
# group of dependency: androidx.room
# name of dependency: room-runtime
# version: the version variable you defined in the previous step
# <dependency_name> = { group = "<dependency_group>", name = "<dependency_name>", version.ref = "<version_reference>" }
[libraries]
room-android = { group = "androidx.room", name = "room-runtime", version.ref = "roomVersion" }Note: Make sure to sync your project before moving on to the next step.
Step 2: Update the dependencies block in `app/build.gradle` file
Open app/build.gradle.kts file and add the following syntax.
# app/build.gradle.kts
# implementation(libs.<dependency_name>)
implementation(libs.room.android)Note that if the library names include `—` , when we refer them in our build.gradle.kts file, we have to change them to `.` there. For example, we have defined the dependency name as room-android so when calling it from the build.gradle.kts file, it will become libs.room.android .
Now sync your project and that’s it!
Adding a plugin dependency
For this example, let’s add the KSP plugin to our app. KSP stands for Kotlin Symbol Processing, similar to KAPT (Kotlin Annotation Processing Tool). Both are annotation-processing tools that are used for code generation. KAPT is the old way which is Java-based and KSP is the new way which is Kotlin-based, and it builds (generates codes) a lot faster than the KAPT. Some libraries that use KSP are Room and Hilt dependency injection.
Now that we know what KSP is, let’s add KSP to our app. Again, it only takes 2 steps 🎉
Step 1: Configure the libs.version.toml file
Similar to adding a remote binary dependency, we will need to add a version declaration under the version section of the libs.version.toml . In addition to that, we will also add a plugin declaration under the plugins section of the TOML file.
# libs.versions.toml
[versions]
kspVersion = "1.9.0-1.0.13"
# <plugin_name> = { id = "<plugin_id>", version.ref = "plugin_version" }
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "kspVersion" }
Now sync your project once before moving on to the next step.
Step 2: Add KSP Plugin to your build.gradle file
Add a reference to the ksp dependency alias to the build section of all the build.gradle files that require the ksp dependency.
# build.gradle.kts (module level)
plugins {
# alias(libs.plugins.<plugin_name>) apply false
alias(libs.plugins.ksp) apply false
}# app/build.gradle.kts
plugins {
# alias(libs.plugins.<plugin_name>)
alias(libs.plugins.ksp)
}
dependencies {
# Here we are using KSP to declare the hilt compiler lib
ksp(libs.hilt.android.compiler)
}Now Sync your project and that’s it!
Here is a full example gist for adding Hilt, Room and KSP to our app.
Happy coding!
