Skip to content

RefreshVersions ♥️ Gradle Version Catalog

Jump to bottom
Jean-Michel Fayard edited this page Sep 11, 2022 · 1 revision

refreshVersions Version Catalog

With Gradle 7.4+, you can put your dependencies and versions in a central place: gradle/libs.versions.toml.

refreshVersions is a Gradle plugin that provides two additional (cool) features:

  • it can generate the version catalog and migrate your build files, if you don't use the versions catalog yet
  • it can show available updates for all your dependencies right inside the gradle/libs.versions.toml file

If you already use a Versions Catalog....

Question: how do you find available updates for all your dependencies? There are solutions: lots of googling, Android Studio linting, Ben Manes's plugin, or dependabot. We think those solutions aren't that great. Yes we are biased, but we wouldn't have started refreshVersions otherwise.

When we started refreshVersions, Versions Catalog wasn't a thing. People were storing dependencies in code (Kotlin or Groovy) and that was bad. So we invented an easily parsable file to contain your versions: versions.properties

Gradle Versions Catalogs basically follow the same idea and we are happy to directly support it in refreshVersions.

To do this:

  1. Setup refreshVersions in your build in its latest release (this is pretty new).
  2. Run ./gradlew refreshVersions
  3. Edit the updated gradle/libs.versions.toml file
## File gradle/libs.versions.toml was updated by refreshVersions with available comments

[versions]

junit-junit = "4.12"
##       ⬆ = "4.13"  
##       ⬆ = "4.13.1"

[libraries]

junit = { group = "junit", name = "junit", version.ref = "junit-junit" }

guava = "com.google.guava:guava:30.0-jre"
##                          ⬆ :31.0-android"  
##                          ⬆ :31.0-jre"

␡ Select the text wisely and press the delete key.

Then sync your build.

🎉 your dependencies are updated... provided you actually use libs.guava and libs.junit in your build.

If you want to get rid of the remaining comments, use ./gradlew refreshVersionsCleanup

TL:DR refreshVersions now directly supports the gradle/libs.versions.toml file!

If you don't use a Versions Catalog yet...

Sure, you could read the official docs which contains (too much) details, then try to write your first versions catalog, then try to migrate your build, then sync and see it fail. After lots of trials and errors that should work.

But laziness is one of the 3 great virtues of the programmer so maybe you shouldn't do that yourself manually. Because refreshVersions can do all of this automatically.

  1. Update Gradle with ./gradlew wrapper --gradle-version 7.5.1 (Versions Catalog is relatively new)
  2. Setup refreshVersions in your build or update to its latest release (refreshVersions support for Versions Catalog is very new).
  3. Run ./gradlew refreshVersionsMigrate --mode=VersionCatalogAndVersionProperties
  4. See the generate catalog at gradle/libs.versions.toml
  5. See your git diff to check how your build has been migrated

This is a big and new feature, so if you have issues, please provide feedback here

TLDR: RefreshVersions can now generate your Gradle Versions Catalog and update your build so that you use the dependencies defined here!

Skip the next paragraph if you already know what a Versions Catalog is.

What is a Gradle Version Catalog anyway?

A Version Catalog is Gradle's new official way of centralizing dependencies and versions.

Previously you may have put your dependnecies inside a libraries.gradle or a buildSrc/.../Libs.kt file:

  • compared to the former, you get auto-completion in the IDE.
  • compared to the latter it's more efficient because changing anything inside the buildSrc invalidates your all build.

The official documentation is at https://docs.gradle.org/current/userguide/platforms.html

Since it contains much more information that you need, I will do here the short version :)

Upgrade Gradle

# Versions Catalog are stable in Gradle 7.4 or better
$ ./gradlew wrapper --gradle-version 7.5.1

Create a file gradle/libs.versions.toml 

[versions]

junit-junit = "4.12"

[libraries]

junit = { group = "junit", name = "junit", version.ref = "junit-junit" }

guava = "com.google.guava:guava:30.0-jre"

Sync Gradle

☕️ You can drink your coffee meanwhile.

You can now use the libraries like this in **/build.gradle(.kts) 

// **/build.gradle.kts

implementation {
   implementation(libs.guava)
   testImplementation(libs.junit)
}

There is more to it, but you now know the basics.

FAQ: Are You Giving Up on the versions.properties File ?

No we are not.

We will. Maybe. Later.

For now, we are adding support for Gradle Version Catalog, we are not deprecating anything.

Part of the reason is historical, we were there before Version Catalog was a thing, and we still want to support people on Gradle < 7.4.

But the more important reason is that we want to keep using our embedded Dependency Notations for popular libraries instead of googling stuff and putting it in the libs.versions.toml.

We think our Dependencies Notations are really cool, and if you haven't use them yet, look here:

TLDR: We think that dependencies notations are more convenient for popular libraries. Versions Catalog are a good solution for all the others. Best of both worlds.

Links

C'est tout pour aujourd'hui, merci!

Clone this wiki locally