Gradle Version Catalog + Pre-Compiled Scripts

Gradle 7.0 introduced an incubating feature to centrally manage dependencies in your Gradle project.

A version catalog is a list of dependencies, represented as dependency coordinates, that a user can pick from when declaring dependencies in a build script.

Gradle documentaiton

In this post, we will take a look at how to setup the versioning system and implement a workaround to use the catalog in pre-compiled scripts as this is not currently supported.

You can find the demo project here.

Common Dependency Magangement Patterns

There have been different patterns developers have come up with to help with dependency declaration and management.

• Using versions in properties files gradle.properties
• Creating a gradle file. dependencies.gradle
• Kotlin DSL dependencies.kts This is what we will use as an example in this post

Since the rise of Kotlin DSL where you declare libraries in buildSrc, I have never looked back, well until 7.0 😂. Basically declaring dependencies in buildSrc then using type-sage accessors to declare dependencies in the build scripts.

We could then go ahead and use this in our build script like so:

One drawback of this method is any change to the dependencies will trigger recompilation of build scripts and invalidate the build script classpath. This will end up rebuilding a lot more than what you should do for a version change.

Hello Version Catalogs

A version catalog is basically a replacement for all the previous patterns, supported by Gradle, without the drawbacks of the previous approaches.

The version catalog TOML file

Gradle offers a conventional file to declare a catalog. We’ll create a file libs.versions.toml in gradle subdirectory of the root build directory and store all our dependencies and version in there.

The TOML file consists of 3 major sections:

• [versions] used to declare versions that can be referenced by dependencies.
• [libraries] used to declare the aliases to coordinates.
• [bundles] used to declare dependency bundles.

Enable version catalog

To enable the feature to add the below line in your root project’s settings.gradle.kts

Declaring Dependencies & Versions

We can now go ahead and add dependencies to the toml file like so.

Referencing Dependencies

We can now reference dependency in the build.gralde.kts. Instead of referencing the dependency name and version from the dependency file, we had earlier can simply use it in the dependency block libs.dependencyName

One slight thing to note is androidx-appCompat (toml) becomes libs.androidx.appCompat (kts). I find this a good way of nesting/grouping dependencies.

We now have a single place where you can update everything, dependencies, and versions.

Enable version catalog for pre-compiled scripts

So far, this will work if you are just using the version catalog in the root build.gradle.ktsfile. We need to add one more thing to allow us to use the catalog system in our pre-compiled scripts. So let's go ahead and fix that.

Create settings.gradle.kts inside buildSrc directory and add the following piece of code.

This is a known issue and we will probably get rid of this code once the issue is resolved.

That’s it. You can now use the version catalog in your pre-compiled scripts. You can take a look at the documentation for further details

Originally published at Thomas Kioko.