如有关变体感知匹配的部分所述,属性为变体提供语义,并用于在变体之间进行选择.

作为Gradle的用户,属性通常被隐藏为实现细节. 但是了解Gradle及其核心插件定义的标准属性可能会很有用.

作为插件作者,这些属性及其定义方式可以作为在生态系统插件中构建自己的一组属性的基础.

Standard attributes defined by Gradle

Gradle定义了Gradle核心插件使用的标准属性列表.

Ecosystem-independent standard attributes

表1.与生态系统无关的标准变体属性
属性名称 Description Values 兼容性和消歧规则

org.gradle.usage

表示变体的主要目的

Usage值是根据" 用法"中定义的常量构建的

遵循生态系统语义(例如,可以使用java-runtime代替java-api但不能相反)

org.gradle.category

指示此软件组件的类别

Category从常量内置值定义范畴

遵循生态系统语义(例如,JVM上的library默认设置,否则不兼容)

org.gradle.libraryelements

指示org.gradle.category=library变体的内容

LibraryElements中定义的常量构建的LibraryElements

遵循生态系统语义(例如,在JVM世界中, jar是默认设置,并且与classes兼容)

org.gradle.docstype

指示org.gradle.category=documentation变体的内容

DocsType从定义的常量内置值DocsType

没有默认值,没有兼容性

org.gradle.dependency.bundling

指示如何访问变体的依赖项.

Bundling在定义的常量内置值捆绑

遵循生态系统语义(例如,在JVM世界中, embeddedexternal兼容)

表2.与生态系统无关的标准组件属性
Attribute name Description Values 兼容性和消歧规则

org.gradle.status

组件级别属性,派生

基于状态方案 ,默认情况下基于源存储库.

根据使用的方案

JVM ecosystem specific attributes

除了上面定义的与生态系统无关的属性之外,JVM生态系统还添加了以下属性:

表3. JVM生态系统标准组件属性
属性名称 Description Values 兼容性和消歧规则

org.gradle.jvm.version

指示JVM版本兼容性.

整数,使用Java 1.4之前的版本1.和Java之前的主要版本.

默认为Gradle使用的JVM版本,低级与高级兼容,更倾向于最高兼容.

JVM生态系统还包含许多针对不同属性的兼容性和消歧规则. 希望了解更多信息的读者可以查看org.gradle.api.internal.artifacts.JavaEcosystemSupport的代码.

Native ecosystem specific attributes

除了上面定义的与生态系统无关的属性之外,本机生态系统还添加了以下属性:

表4.本机生态系统标准组件属性
属性名称 Description Values 兼容性和消歧规则

org.gradle.native.debuggable

指示二进制文件是否使用调试符号构建

Boolean

N/A

org.gradle.native.optimized

指示二进制文件是否使用优化标志构建

Boolean

N/A

org.gradle.native.architecture

指示二进制文件的目标体系结构

MachineArchitecture从定义的常量内置值MachineArchitecture

None

org.gradle.native.operatingSystem

指示二进制文件的目标操作系统

OperatingSystemFamily中定义的常量构建的OperatingSystemFamily

None

Declaring custom attributes

如果要扩展Gradle(例如,通过为另一个生态系统编写插件),则要自定义属性,可以在插件中支持变体感知的依赖项管理功能. 但是,如果您还尝试发布库,则应保持谨慎. 新属性的语义通常是通过插件定义的,该插件可以带有兼容性歧义消除规则. 因此,使用消耗为特定生态系统发布的库的构建,也需要应用相应的插件来正确解释属性. 如果您的插件面向更广泛的受众,即如果它是公开可用的,并且库已发布到公共存储库,则定义新属性可以有效地扩展Gradle模块元数据的语义并承担责任. 例如,对已经发布的属性的支持不应再次删除,或者应在插件的未来版本中以某种兼容性层处理.

Creating attributes in a build script or plugin

键入属性. 可以通过Attribute<T>.of方法创建一个属性:

例子1.定义属性
build.gradle
// An attribute of type `String`
def myAttribute = Attribute.of("my.attribute.name", String)
// An attribute of type `Usage`
def myUsage = Attribute.of("my.usage.attribute", Usage)
build.gradle.kts
// An attribute of type `String`
val myAttribute = Attribute.of("my.attribute.name", String::class.java)
// An attribute of type `Usage`
val myUsage = Attribute.of("my.usage.attribute", Usage::class.java)

当前,仅支持String属性类型或任何扩展Named属性. 必须在dependencies处理程序上的属性架构中声明属性

示例2.在属性架构上注册属性
build.gradle
dependencies.attributesSchema {
    // registers this attribute to the attributes schema
    attribute(myAttribute)
    attribute(myUsage)
}
build.gradle.kts
dependencies.attributesSchema {
    // registers this attribute to the attributes schema
    attribute(myAttribute)
    attribute(myUsage)
}

然后可以配置配置以设置属性值:

例子3.在配置上设置属性
build.gradle
configurations {
    myConfiguration {
        attributes {
            attribute(myAttribute, 'my-value')
        }
    }
}
build.gradle.kts
configurations {
    create("myConfiguration") {
        attributes {
            attribute(myAttribute, "my-value")
        }
    }
}

对于类型扩展Named的属性, 必须通过对象工厂创建属性的值:

例子4.命名属性
build.gradle
configurations {
    myConfiguration {
        attributes {
            attribute(myUsage, project.objects.named(Usage, 'my-value'))
        }
    }
}
build.gradle.kts
configurations {
    "myConfiguration" {
        attributes {
            attribute(myUsage, project.objects.named(Usage::class.java, "my-value"))
        }
    }
}

Attribute compatibility rules

属性使引擎可以选择兼容的变体 . 但是,在某些情况下,提供者可能并不完全具有消费者想要的东西,但仍然可以使用它. 例如,如果使用者要求一个库的API,则生产者可能没有这样的变体,而只有运行时变体. 这是在外部存储库上发布的库的典型特征. 在这种情况下,我们知道即使没有完全匹配(API),我们仍然可以针对运行时变体进行编译(它包含的内容超出了我们需要编译的范围,但仍然可以使用). 为了解决这个问题,Gradle提供了属性兼容性规则 . 兼容性规则的作用是解释哪些变体与消费者要求的变体兼容 .

必须通过可从属性架构中获取的属性匹配策略来注册属性兼容性规则.

Attribute disambiguation rules

因为一个属性的多个值可以与请求的属性兼容 ,所以Gradle需要在候选者之间进行选择. 这是通过实现属性消歧规则来完成的.

必须通过可从属性架构中获取的属性匹配策略来注册属性消歧规则.