Gradle7.0.0以上依赖库统一版本号管理
Gradle7.0推出了一个新的特性,使用Catalog统一依赖版本,它支持以下特性:
1、对所有module可见,可统一管理所有module的依赖。
2、支持声明依赖bundles,即总是一起使用的依赖可以组合在一起。
3、支持版本号与依赖名分离,可以在多个依赖间共享版本号。
4、支持在单独的libs.versions.toml文件中配置依赖。
5、支持在项目间共享依赖。
Kotlin 和 Groovy 语言差异
一些简单的 Kotlin 和 Groovy 语言差异可能会使转换脚本变得乏味:
-
Groovy 字符串可以用单引号
'string'
或双引号引起来,"string"
而 Kotlin 需要双引号"string"
。 -
Groovy 允许在调用函数时省略括号,而 Kotlin 总是需要括号。
-
Gradle Groovy DSL 允许
=
在分配属性时省略赋值运算符,而 Kotlin 始终需要赋值运算符。
这里作简单说明,是因为之前配置时kotlin与groovy的配置混用,导致配置不成功。
使用Version Catalog
注意,Catalog仍然是一个孵化中的特性,如需使用,需要在settings.gradle中添加以下内容:
enableFeaturePreview('VERSION_CATALOGS')
从命名上也可以看出,Version Catalog其实就是一个版本的目录,我们可以从目录中选出我们需要的依赖使用。
dependencies {
...
// 小括号可有可无,如下
implementation(libs.retrofit)
implementation libs.groovy.core
...
}
在这种情况下,libs是一个目录,retrofit表示该目录中可用的依赖项。使用Version Catalog具有许多优点:
1、对于每个catalog,Gradle都会生成类型安全的访问器,以便你在IDE中可以自动补全。(注:目前在build.gradle中还不能自动补全,可能是指kts或者开发中?)
2、声明在catalog中的依赖对所有module可见,当修改版本号时,可以统一管理统一修改。
3、catalog支持声明一个依赖bundles,即一些总是一起使用的依赖的组合。
4、catalog支持版本号与依赖名分离,可以在多个依赖间共享版本号。
声明Version Catalog
Version Catalog可以在settings.gradle(.kts)文件中声明。
别名必须由一系列以破折号(-,推荐)、下划线 (_) 或点 (.) 分隔的标识符组成。
标识符本身必须由ascii字符组成,最好是小写,最后是数字。
值得注意的是,groovy-core会被映射成libs.groovy.core。
如果想避免映射可以使用大小写来区分,比如groovyCore会被处理成libs.groovyCore。
dependencyResolutionManagement {
//gradle 有一个默认配置名称为 libs,如果你创建的版本目录名称是 libs,那么你就无需通过 from 方法加载 libs.versions.toml 文件,因为 gradle 会默认此配置,你只需在 ./gradle 路径下创建 libs.versions.toml 文件即可,重复添加会导致编译失败;
// 版本目录配置
versionCatalogs {
// 创建一个名称为 libs 的版本目录
libs {
// groovy单、双引号皆可,kotlin只能双引号,建议都用双引号
version("minSdk","24")
version('compileSdk','30')
version('targetSdk','30')
// 声明 groovy 版本
version("groovy", "3.0.5")
// 声明 groovy 依赖
alias("groovy-core").to("org.codehaus.groovy", "groovy").versionRef("groovy")
// 声明 groovy 依赖
alias("groovy-nio").to("org.codehaus.groovy", "groovy-nio").versionRef("groovy")
// 声明 groovy 依赖使用版本引用
alias("groovy-json").to("org.codehaus.groovy", "groovy-json").versionRef("groovy")
// 多版本约束,strictly可不换行,prefer必须换行,否则编译不通过
alias("commons-lang3").to("org.apache.commons","commons-lang3").version{ strictly'[3.8,4.0['
prefer'3.9'}
// 依赖bundles 声明 groovy 依赖组,三个groovy依赖具有相同的版本号,可以把它们统一起来
bundle("groovy", ["groovy-core", "groovy-json", "groovy-nio"])
//插件版本
alias('jmh').toPluginId('me.champeau.jmh').version('0.6.5')
// Catalog支持通过从Toml文件引入依赖;
// libs.version.toml 放到gradle目录下会自动加载,一是不能在libs的版本目录下引入,可以定义其它目录引入;二是versions定义可以直接使用不需要引入;
//from(files("./gradle/libs.versions.toml"))
}
// 创建一个新的版本目录,可以引入任何toml文件,包括gradle下的libs.version.toml
testLib{
from(files("./gradle/libs.versions.toml"))
}
}
}
使用Version Catalog
plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android'
// Use the plugin `jmh` as declared in the `libs` version catalog
//alias(libs.plugins.jmh)
}
android {
compileSdk libs.versions.compileSdkVersion.get().toInteger()
defaultConfig {
applicationId "com.hollysys.mengniumeishang"
minSdk libs.versions.minSdkVersion.get().toInteger()
targetSdk libs.versions.targetSdkVersion.get().toInteger()
versionCode 1
versionName "1.2"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
}
...
}
dependencies {
implementation libs.bundles.groovy
...
}
单独文件中配置Version Catalog
除了在settings.gradle中声明Catalog外,也可以通过一个单独的文件来配置Catalog。
如果在根构建的gradle目录中找到了libs.versions.toml文件,则将使用该文件的内容自动声明一个Catalog。
TOML文件主要由4个部分组成:
[versions] 部分用于声明可以被依赖项引用的版本。
[libraries]部分用于声明Library的别名。
[bundles]部分用于声明依赖包。
[plugins] 部分用于声明插件。
如定义libs.version.toml文件内容如下:
[versions]
groovy = "3.0.5"
checkstyle = "8.37"
common = "1.4"
compileSdkVersion = '32'
minSdkVersion = "21"
targetSdkVersion = "32"
# versions可以定义成一个字符串,也可以定义成一个范围,详情可参见rich-version
my-lib = { strictly ="[1.0, 2.0[", prefer ="1.2"}
[libraries]
retrofit ="com.squareup.retrofit2:retrofit:2.9.0"
my-lib = "com.mycompany:mylib:1.4"
my-other-lib = { module = "com.mycompany:other", version = "1.4" }
my-other-lib2 = { group = "com.mycompany", name = "alternate", version = "1.4" }
mylib-full-format = { group = "com.mycompany", name = "alternate", version = { require = "1.4" } }
groovy-core = { module = "org.codehaus.groovy:groovy", version.ref = "groovy" }
groovy-json = { module = "org.codehaus.groovy:groovy-json", version.ref = "groovy" }
groovy-nio = { module = "org.codehaus.groovy:groovy-nio", version.ref = "groovy" }
commons-lang3 = { group = "org.apache.commons", name = "commons-lang3", version = { strictly = "[3.8, 4.0[", prefer="3.9" } }
[bundles]
groovy = ["groovy-core", "groovy-json", "groovy-nio"]
[plugins]
jmh = { id = "me.champeau.jmh", version = "0.6.5" }
short-notation = "some.plugin.id:1.4"
long-notation = { id = "some.plugin.id", version = "1.4" }
reference-notation = { id = "some.plugin.id", version.ref = "common" }
如上所示,依赖可以定义成一个字符串,也可以将module与version分离开来。
其中versions可以定义成一个字符串,也可以定义成一个范围,详情可参见rich-version。
[versions]
my-lib = { strictly ="[1.0, 2.0[", prefer ="1.2"}
在项目间共享Version Catalog
Toml文件共享
dependencyResolutionManagement {
versionCatalogs {
libs {
from(files("./libs.versions.toml"))
}
// 声明一个'testLibs'目录, 从'test-libs.versions.toml'文件中
testLibs {
from(files('./gradle/test-libs.versions.toml'))
}
}
}
发布插件共享
通过Catalog插件来发布目录,用户直接引入这个插件即可。
Gradle提供了一个Catalog插件,它提供了声明然后发布Catalog的能力。
1. 首先引入两个插件
plugins {
id 'version-catalog'
id 'maven-publish'
}
然后,此插件将公开可用于声明目录的catalog扩展。
2. 定义目录
使用catalog扩展定义目录。
catalog {
// 定义目录
versionCatalog {
from files('../libs.versions.toml')
}
}
3. 发布目录
publishing {
publications {
maven(MavenPublication) {
groupId ='com.zj.catalog'
artifactId ='catalog'
version ='1.0.0'
from components.versionCatalog
}
}
}
4. 使用目录
# settings.gradle
dependencyResolutionManagement {
//...
repositories {
mavenLocal()
//...
}
}
enableFeaturePreview('VERSION_CATALOGS')
dependencyResolutionManagement {
versionCatalogs {
libs {
from("com.xx.catalog:catalog:1.0.0")
// 我们也可以重写覆盖catalog中的groovy版本
version("groovy","3.0.6")
}
}
}
补充说明
1、经测试发现gradle 7.1.1版本不支持toml中定义的 [plugins] , 但支持 [metadata]。将gradle改为 7.3.3就支持 [plugins]。