KC Blog

Issues Encountered When Migrating Android Projects to Version Catalogs Using .toml

4 min read
AndroidDev#Kotlin
Introduction
* Since the previous project switched to `.kts` for building the project

the official documentation also released an article aimed at migrating projects to version catalogs

After adding it, you can see it displayed at the bottom when viewing the project directory in Android Studio

This saves a step (no need to double Shift to search XD)

You can see the content by clicking

  • Previously, creating a Dependence.kt might require double Shift to search

or looking under ../Dependence.kt

Applicable AGP Versions
  • Because newer versions of Android Studio

can directly configure new projects through the IDE

But if you encounter older projects

you might wonder if you need to update the AGP version during manual migration

And usually, older projects might be quite old

requiring time to update or lacking the budget to optimize in a short time

so maintaining the original version might be considered

  • So I did some research

and randomly took an AGP configured with toml created by AS

which was directly version 8.4.0

  • According to the Gradle official documentation, in the 7.0 documentation it mentions that version catalogs were supported as an experimental feature in the 7.0 release

Refer to Gradle 7.0 release So toml can be used in 7.x

Issues You Might Encounter During Migration
* Some projects use this method to introduce libraries
implement("com.orhanobut:dialogplus:1.11@aar")

There is an @aar at the end

But toml does not support adding @aar at the end in versions

causing the build to fail

You can change it to the following

  • In the past, kotlin objects were used to configure version parameters, as shown below

If you want to switch everything to .toml Testing shows that accessing versions configured in .toml externally

cannot be done directly like libs.xx.xx.xxx to get the version

You can only use get() to get the value of Versions in .toml

For example: libs.versions.minSdk.get().toInt()

However, if you set it this way

you cannot see where it is used in .toml

Use aapt dump badging appName.apk to verify that the build output matches the libs.versions.minSdk.get() setting

  • Configurations below AGP 8.1.0 need to add @Suppress("DSL_SCOPE_VIOLATION") above plugin{}

The reason is due to an issue with the IDE Version catalog accessors for plugin aliases shown as errors in IDE kotlin script editor #22797

  • Next is the version.ref under [plugins]

It cannot be set to null or empty

Because some projects use plugin + classpath to set up

This causes conflicts when directly using plugins settings

Why some libraries can build without setting version.ref
* The first time you use `.toml`, you might wonder why some libraries can build normally without setting version.ref

This is because when you introduce composeBom

and then import other related libraries without setting versions

it will automatically map the related library versions based on the composeBom version you set

So, by just setting composeBom, it can automatically set compatible versions for the supported libraries

Very convenient!

Migration method for version catalogs

Migration explanation

Create lib.version.toml under the ../gradle directory

Add [versions], [libraries], and [plugins] according to your needs

The official recommended naming convention is kebab case

It helps with better code completion

For example, the code below:

Actual usage

After adding the toml file, click sync now to synchronize

Then you can directly use it in build.gradle.kts

For example, the code below:

References
- Android developer official documentation