Gradle模块元数据是用于序列化Gradle组件模型的格式. 它类似于Apache Maven™的POM文件Apache Ivy™ivy.xml文件. 元数据文件的目标是向消费者提供存储库中发布内容的合理模型.

Gradle模块元数据是一种独特的格式,旨在通过使其具有多平台和变体感知功能来提高依赖性解析.

特别是,Gradle模块元数据支持:

发布Gradle模块元数据将为您的使用者提供更好的依赖关系管理:

使用Maven Publish插件Ivy Publish插件时,Gradle模块元数据会自动发布 . 旧版mavenivy插件支持此功能.

The specification for Gradle Module Metadata specification can be found here.

Mapping with other formats

Gradle模块元数据会自动发布在Maven或Ivy存储库中. 但是,它不会替换pom.xmlivy.xml文件:它与这些文件一起发布. 这样做是为了最大程度地提高与第三方构建工具的兼容性.

Gradle尽其所能将Gradle特定的概念映射到Maven或Ivy. 当构建文件使用只能在Gradle模块元数据中表示的功能时,Gradle会在发布时警告您. 下表总结了如何将某些Gradle特定功能映射到Maven和Ivy:

表1. Gradle特定概念到Maven和Ivy的映射
Gradle Maven Ivy Description

dependency constraints

<dependencyManagement> dependencies

未发表

Gradle依赖项约束是可传递的 ,而Maven的依赖项管理块不是

rich version constraints

发布需求版本

发布了需求版本

component capabilities

未发表

未发表

组件功能是Gradle独有的

Feature variants

上载了各种工件,依赖性发布为_optional依赖性

已上传变体工件,未发布依赖项

功能变体很好地替代了可选的依赖项

Custom component types

工件已上传,依赖项是映射所描述的依赖项

工件已上传,相关性被忽略

在任何情况下,自定义组件类型都可能无法从Maven或Ivy中使用. 它们通常存在于自定义生态系统中.

Disabling metadata compatibility publication warnings

如果要禁止显示警告,可以使用以下API来禁止显示警告:

例子1.禁用发布警告
build.gradle
    publications {
        maven(MavenPublication) {
            from components.java
            suppressPomMetadataWarningsFor('runtimeElements')
        }
    }
build.gradle.kts
    publications {
        register<MavenPublication>("maven") {
            from(components["java"])
            suppressPomMetadataWarningsFor("runtimeElements")
        }
    }

Interactions with other build tools

由于Gradle模块元数据并未广泛传播,并且其目的是最大程度地提高与其他工具的兼容性 ,因此Gradle做以下几件事:

  • Gradle模块元数据与给定存储库(Maven或Ivy)的常规描述符一起系统发布

  • pom.xmlivy.xml文件将包含标记注释 ,该注释告诉Gradle该模块存在Gradle模块元数据

标记的目的不是其他工具来解析模块元数据:仅用于Gradle用户. 它向Gradle解释说存在更好的模块元数据文件,应该使用它. 这并不意味着Maven或Ivy的消耗也将被打破,只是它可以在降级模式下工作 .

必须将其视为一项性能优化 :不必执行2个网络请求,而是先获取Gradle模块元数据,然后再获取一个POM / Ivy文件,而Gradle将首先查看该文件中最重要的文件.可能存在,则仅在模块与Gradle Module Metadata一起实际发布时才执行第二个请求.

如果您知道依赖的模块始终与Gradle Module Metadata一起发布,则可以优化网络调用,为存储库配置元数据源:

示例2.仅解决Gradle模块元数据
build.gradle
    repositories {
        maven {
            url "http://repo.mycompany.com/repo"
            metadataSources {
                gradleMetadata()
            }
        }
    }
build.gradle.kts
    repositories {
        maven {
            setUrl("http://repo.mycompany.com/repo")
            metadataSources {
                gradleMetadata()
            }
        }
    }

Gradle Module Metadata validation

Gradle模块元数据在发布之前先经过验证.

强制执行以下规则:

这些规则可确保产生的元数据的质量,并有助于确认使用不会有问题.

Making Gradle Module Metadata reproducible

默认情况下,Gradle模块元数据文件包含生成它的构建中的唯一ID. 这意味着文件将始终是不同的.

用户可以选择在publication禁用此唯一标识符:

例子3.配置发布的构建标识符
build.gradle
publishing {
    publications {
        main(MavenPublication) {
            from components.java
            withoutBuildIdentifier()
        }
    }
}
build.gradle.kts
publishing {
    publications {
        create<MavenPublication>("main") {
            from(components["java"])
            withoutBuildIdentifier()
        }
    }
}

通过上述更改,生成的Gradle Module元数据文件将始终相同,从而使下游任务可以将其视为最新文件.

由于实现方式,生成模块元数据文件的任务目前从未被Gradle标记为UP-TO-DATE . 但是,如果跳过了构建标识符,并且未更改构建输入或构建脚本,则该任务实际上是最新的(它始终产生相同的输出).

Disabling Gradle Module Metadata publication

在某些情况下,您可能希望禁用Gradle模块元数据的发布:

  • 您要上传到的存储库将拒绝元数据文件(未知格式)

  • 您正在使用未正确映射到Gradle模块元数据的Maven或Ivy特定概念

在这种情况下,只需禁用生成元数据文件的任务即可禁用Gradle Module元数据的发布:

例子4.禁用发布Gradle模块元数据
build.gradle
    tasks.withType(GenerateModuleMetadata) {
        enabled = false
    }
build.gradle.kts
    tasks.withType<GenerateModuleMetadata> {
        enabled = false
    }