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

• 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
  

• 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

• 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

• 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!
  
• Refer to Bom mapping to understand the corresponding versions
  

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:

• Android developer official documentation
  
• Gradle version catalogs troubleshooting
  
• Version catalog accessors for plugin aliases shown as errors in IDE kotlin script editor #22797