Migrate dependencies.yml to Gradle's version catalogs
#4353
Conversation
Motivation: We can declare dependency versions using `dependencies.yml` and share it across multiple projects. It is useful to manage the versions of various dependencies. However, we can't define different versions of a module. Because the unique keys in `dependencies.yml` are `moduleId:artifactId`. This limitation makes it difficult to manage compatibility between different versions of a library. For example, okhttp v4 is required to test `it:okhttp` and okhttp v3 is required to run `retrofit2` module. Gradle introduced a new way to [share dependency version between projects](https://docs.gradle.org/current/userguide/platforms.html). The unique key of version catalogs is a user-defined alias so we can define multiple versions of a module using different aliases. Version catalogs does not allow extra properies on `libs.versions.toml`. It only allow some properties for versions and modules. `dependencies.yml` not only manages versions, but also manages metadata for a module such as relocations, exclusions and javadoc links. I wanted to take advantage of both. We need a version manager that supports version catalogs based on aliases, and ability to add the metadata. As a result, I implmented to add our own dependency machanism using `dependencies.toml` that is fully compatible with Gradle's version catalogs and understands relocations, exclusions and javadoc links declearations. Modifications: - Migrate `dependencies.yml` to `dependencies.toml` - TBU Result: - Fixes line#4120
Codecov Report
@@ Coverage Diff @@
## master #4353 +/- ##
============================================
- Coverage 73.53% 73.52% -0.01%
+ Complexity 17648 17647 -1
============================================
Files 1500 1500
Lines 66010 66010
Branches 8328 8328
============================================
- Hits 48540 48534 -6
- Misses 13254 13265 +11
+ Partials 4216 4211 -5
Continue to review full report at Codecov.
|
gradle/scripts/README.md
Outdated
| compileOnly 'com.google.code.findbugs:jsr305' | ||
| compile 'com.google.guava:guava' | ||
| compileOnly libs.findbugs | ||
| implementation libs.guava | ||
| } | ||
| } | ||
|
|
||
| // In case you need to get the version number of an artifact: | ||
| println "Guava version: ${managedVersions['com.google.guava:guava']}" |
There was a problem hiding this comment.
better to use libs...get()?
build.gradle
Outdated
| @@ -314,3 +310,32 @@ class TestsReportTask extends DefaultTask { | |||
| } | |||
| } | |||
| } | |||
|
|
|||
| // Prints all versions registered through 'dependencies.toml' | |||
| tasks.register("printVersionCatalogs") { | |||
There was a problem hiding this comment.
Question) Would this task be useful for other gradle-script users as well?
(I think it's fine to leave here for now though)
There was a problem hiding this comment.
This is useful to debug some dependencies. Let me move it to version-catalogs.gradle
| } | ||
| } | ||
|
|
||
| // In case you need to get the version number of an artifact: | ||
| println "Guava version: ${managedVersions['com.google.guava:guava']}" | ||
| // Note that it is not recommended to use `managedVersions` with the module defined multiple times with | ||
| // different aliases. Because if a module is declared with different versions, the version returned by | ||
| // `managedVersions` is determined by how the version catalogs are indexed. |
There was a problem hiding this comment.
I see, so it is possible that the version returned by managedVersions isn't necessarily equal to the eventually resolved version. Am I understanding correctly?
There was a problem hiding this comment.
managedVersions can be safely used when a groupId:artifactId is declared only once in a whole dependencies.toml.
Let's say the following dependencies are defined.
[libraries.jsoup]
module = "org.jsoup:jsoup"
version = "1.15.1"
[libraries.thrift09]
module = "org.apache.thrift:libthrift"
version = "0.9.3-1"
[libraries.thrift012]
module = "org.apache.thrift:libthrift"
version = "0.12.0"We can assume that managedVersions['org.jsoup:jsoup'] returns "1.15.1". However, we can't assert whether managedVersions['org.apache.thrift:libthrift'] returns "0.9.3-1" or "0.12.0".
| tomcat9 = "9.0.62" | ||
|
|
||
| [boms] | ||
| brave = { module = "io.zipkin.brave:brave-bom", version = "5.13.9" } |
There was a problem hiding this comment.
So the convention of specifying version is that
- the version is inlined if it's used only once.
- the version is specified in
[versions]section if it's used more than once.
Is that correct?
There was a problem hiding this comment.
Correct. But we can freely change the convention anytime. 😆
|
We have to also check if https://github.com/line/armeria-examples/blob/master/update-examples.sh is working correctly before merging this. 😉 |
|
|
Let me merge this PR without waiting for CI builds because the last commit only changed |
Motivation:
We can declare dependency versions using
dependencies.ymland share themacross multiple projects. It is useful to manage the versions of various
dependencies. However, we can't define different versions of a module.
Because the unique keys in
dependencies.ymlaremoduleId:artifactId.This limitation makes it difficult to manage compatibility between
different versions of a library. For example, okhttp v4 is required to
test
it:okhttpand okhttp v3 is required to runretrofit2module.Gradle introduced a new way to share dependency versions between projects.
The unique key of version catalogs is a user-defined alias so we can
define multiple versions of a module using different aliases.
Version catalogs do not allow extra properties on
libs.versions.toml.It only allows some properties for versions and modules.
dependencies.ymlnot only manages versions but also manages metadatafor a module such as relocations, exclusions and Javadoc links.
I wanted to take advantage of both. We need a version manager that
supports version catalogs based on aliases, and the ability to add the
metadata. As a result, I implemented to add our own dependency mechanism
using
dependencies.tomlthat is fully compatible with Gradle's versioncatalogs and understands relocations, exclusions and Javadoc links
declarations.
Modifications:
dependencies.ymltodependencies.tomlcommon-dependences.gradletocommon-dependences-lagacy.gradlefor backward compatibility with
dependencies.ymlcommon-dependences.gradlehandles the dependencies declared bydependencies.tomlversion-catalog.gradlethat parsesdependencies.tomland builds:build.gradlefiles to the new version catalog API.Result:
Fixes #4120