Gradle 模块元数据是一种用于序列化 Gradle 组件模型的格式。它类似于Apache Maven™ 的 POM 文件或Apache Ivy™ ivy.xml文件。元数据文件的目标是向消费者提供存储库上发布内容的合理模型。
Gradle 模块元数据是一种独特的格式,旨在通过使其具有多平台和变体感知能力来改进依赖关系解析。
特别是,Gradle 模块元数据支持:
Gradle 模块元数据的发布将为您的消费者提供更好的依赖管理:
-
通过检测不兼容的模块及早发现问题
-
一致选择特定于平台的依赖项
-
本机依赖版本对齐
-
自动获取库特定功能的依赖项
使用Maven Publish 插件或Ivy Publish 插件时,Gradle 模块元数据会自动发布。
Gradle 模块元数据的规范可以在这里找到。
与其他格式的映射
Gradle 模块元数据自动发布在 Maven 或 Ivy 存储库上。但是,它不会替换pom.xml或ivy.xml文件:它与这些文件一起发布。这样做是为了最大限度地提高与第三方构建工具的兼容性。
Gradle 尽力将 Gradle 特定的概念映射到 Maven 或 Ivy。当构建文件使用只能在 Gradle 模块元数据中表示的功能时,Gradle 将在发布时向您发出警告。下表总结了一些 Gradle 特定功能如何映射到 Maven 和 Ivy:
摇篮 | 梅文 | 常春藤 | 描述 |
---|---|---|---|
|
未发表 |
Gradle 依赖约束是可传递的,而 Maven 的依赖管理块则不是 |
|
发布所需版本 |
发布了需要的版本 |
||
未发表 |
未发表 |
组件功能是 Gradle 独有的 |
|
上传变体工件,将依赖项发布为可选依赖项 |
变体工件已上传,依赖项未发布 |
功能变体是可选依赖项的良好替代品 |
|
工件已上传,依赖项是映射所描述的依赖项 |
工件已上传,依赖项被忽略 |
无论如何,自定义组件类型可能无法从 Maven 或 Ivy 中使用。它们通常存在于自定义生态系统的背景下。 |
禁用元数据兼容性发布警告
如果您想抑制警告,可以使用以下 API 来实现:
-
对于Maven,请参阅MavenPublication
suppress*
中的方法 -
对于Ivy,请参阅IvyPublication
suppress*
中的方法
publications {
register<MavenPublication>("maven") {
from(components["java"])
suppressPomMetadataWarningsFor("runtimeElements")
}
}
publications {
maven(MavenPublication) {
from components.java
suppressPomMetadataWarningsFor('runtimeElements')
}
}
与其他构建工具的交互
由于 Gradle 模块元数据并未广泛传播,并且它旨在最大限度地提高与其他工具的兼容性,因此 Gradle 做了几件事:
-
Gradle 模块元数据与给定存储库(Maven 或 Ivy)的正常描述符一起系统地发布
-
pom.xml
或文件ivy.xml
将包含一个标记注释,告诉 Gradle 该模块存在 Gradle 模块元数据
标记的目标不是让其他工具解析模块元数据:它仅适用于 Gradle 用户。它向 Gradle 解释说存在更好的模块元数据文件,并且应该使用它。这并不意味着 Maven 或 Ivy 的消耗也会被破坏,只是它在降级模式下工作。
这必须被视为一种性能优化:Gradle 将首先查看最重要的文件,而不是必须执行 2 个网络请求,一个获取 Gradle 模块元数据,然后一个获取 POM/Ivy 文件,以防丢失。可能存在,那么如果该模块实际上是使用 Gradle 模块元数据发布的,则仅执行第二个请求。 |
如果您知道您依赖的模块始终使用 Gradle 模块元数据发布,则可以通过配置存储库的元数据源来优化网络调用:
repositories {
maven {
setUrl("http://repo.mycompany.com/repo")
metadataSources {
gradleMetadata()
}
}
}
repositories {
maven {
url "http://repo.mycompany.com/repo"
metadataSources {
gradleMetadata()
}
}
}
Gradle 模块元数据验证
Gradle 模块元数据在发布之前经过验证。
执行以下规则:
-
变体名称必须是唯一的,
-
每个变体必须至少有一个属性,
-
两个变体不可能具有完全相同的属性和功能,
-
如果存在依赖关系,则所有变体中至少有一个必须携带版本信息。
这些规则确保了生成的元数据的质量,并有助于确认消费不会出现问题。
Gradle 模块元数据再现性
UP-TO-DATE
由于其实现方式,生成模块元数据文件的任务目前从未被 Gradle 标记。但是,如果构建输入和构建脚本均未更改,则任务结果实际上是最新的:它始终生成相同的输出。
如果用户希望module
每次构建调用都有一个唯一的文件,则可以将生成的元数据中的标识符链接到创建它的构建。用户可以选择在其以下位置启用此唯一标识符publication
:
publishing {
publications {
create<MavenPublication>("myLibrary") {
from(components["java"])
withBuildIdentifier()
}
}
}
publishing {
publications {
myLibrary(MavenPublication) {
from components.java
withBuildIdentifier()
}
}
}
通过上述更改,生成的 Gradle 模块元数据文件将始终不同,迫使下游任务认为它已过时。
禁用 Gradle 模块元数据发布
在某些情况下,您可能希望禁用 Gradle 模块元数据的发布:
-
您上传到的存储库拒绝元数据文件(未知格式)
-
您正在使用 Maven 或 Ivy 特定概念,这些概念未正确映射到 Gradle 模块元数据
在这种情况下,只需禁用生成元数据文件的任务即可禁用 Gradle 模块元数据的发布:
tasks.withType<GenerateModuleMetadata> {
enabled = false
}
tasks.withType(GenerateModuleMetadata) {
enabled = false
}