自定义发布 - Gradle 中文

修改和添加现有组件的变体以供发布

Gradle 的发布模型基于组件的概念，组件由插件定义。例如，Java 库插件定义了一个java组件，它对应于一个库，但 Java 平台插件定义了另一种类型的组件，名为javaPlatform，它实际上是一种不同类型的软件组件（一个平台）。

有时我们想向现有组件添加更多变体或修改现有变体。例如，如果您为不同平台添加了 Java 库的变体，您可能只想在java组件本身声明此附加变体。通常，声明附加变体通常是发布附加工件的最佳解决方案。

要执行此类添加或修改，AdhocComponentWithVariants接口声明了两个名为addVariantsFromConfiguration和withVariantsFromConfiguration的方法，它们接受两个参数

用作变体源的传出配置
一个自定义操作，允许您过滤要发布的变体。

要使用这些方法，您必须确保您使用的SoftwareComponent本身是AdhocComponentWithVariants，Java 插件（Java、Java 库、Java 平台）创建的组件就是这种情况。添加变体非常简单。

示例 1. 向现有软件组件添加变体

InstrumentedJarsPlugin.kt

val javaComponent = components.findByName("java") as AdhocComponentWithVariants
javaComponent.addVariantsFromConfiguration(outgoing) {
    // dependencies for this variant are considered runtime dependencies
    mapToMavenScope("runtime")
    // and also optional dependencies, because we don't want them to leak
    mapToOptional()
}

InstrumentedJarsPlugin.groovy

AdhocComponentWithVariants javaComponent = (AdhocComponentWithVariants) project.components.findByName("java")
javaComponent.addVariantsFromConfiguration(outgoing) {
    // dependencies for this variant are considered runtime dependencies
    it.mapToMavenScope("runtime")
    // and also optional dependencies, because we don't want them to leak
    it.mapToOptional()
}

在其他情况下，您可能希望修改由某个 Java 插件添加的变体。例如，如果您激活 Javadoc 和源代码的发布，它们将成为java组件的附加变体。如果您只想发布其中一个，例如只发布 Javadoc 但不发布源代码，您可以修改sources变体，使其不发布。

示例 2. 发布带有 Javadoc 但没有源代码的 Java 库

build.gradle.kts

java {
    withJavadocJar()
    withSourcesJar()
}

val javaComponent = components["java"] as AdhocComponentWithVariants
javaComponent.withVariantsFromConfiguration(configurations["sourcesElements"]) {
    skip()
}

publishing {
    publications {
        create<MavenPublication>("mavenJava") {
            from(components["java"])
        }
    }
}

build.gradle

java {
    withJavadocJar()
    withSourcesJar()
}

components.java.withVariantsFromConfiguration(configurations.sourcesElements) {
    skip()
}

publishing {
    publications {
        mavenJava(MavenPublication) {
            from components.java
        }
    }
}

创建和发布自定义组件

在前面的示例中，我们演示了如何扩展或修改现有组件，例如 Java 插件提供的组件。但是 Gradle 还允许您构建自定义组件（不是 Java 库，不是 Java 平台，不是 Gradle 原生支持的组件）。

要创建自定义组件，您首先需要创建一个空的临时组件。目前，这只能通过插件实现，因为您需要获取对SoftwareComponentFactory的句柄。

示例 3. 注入软件组件工厂

InstrumentedJarsPlugin.kt

class InstrumentedJarsPlugin @Inject constructor(
    private val softwareComponentFactory: SoftwareComponentFactory) : Plugin<Project> {

InstrumentedJarsPlugin.groovy

private final SoftwareComponentFactory softwareComponentFactory

@Inject
InstrumentedJarsPlugin(SoftwareComponentFactory softwareComponentFactory) {
    this.softwareComponentFactory = softwareComponentFactory
}

声明自定义组件发布什么仍然通过AdhocComponentWithVariants API 完成。对于自定义组件，第一步是创建自定义输出变体，遵循本章中的说明。在此阶段，您应该拥有可以在跨项目依赖项中使用的变体，但现在我们将将其发布到外部存储库。

示例 4. 创建自定义的临时组件

InstrumentedJarsPlugin.kt

// create an adhoc component
val adhocComponent = softwareComponentFactory.adhoc("myAdhocComponent")
// add it to the list of components that this project declares
components.add(adhocComponent)
// and register a variant for publication
adhocComponent.addVariantsFromConfiguration(outgoing) {
    mapToMavenScope("runtime")
}

InstrumentedJarsPlugin.groovy

// create an adhoc component
def adhocComponent = softwareComponentFactory.adhoc("myAdhocComponent")
// add it to the list of components that this project declares
project.components.add(adhocComponent)
// and register a variant for publication
adhocComponent.addVariantsFromConfiguration(outgoing) {
    it.mapToMavenScope("runtime")
}

首先，我们使用工厂创建一个新的 adhoc 组件。然后，我们通过 `addVariantsFromConfiguration` 方法添加一个变体，该方法在上一节中有更详细的描述。

在简单的情况下，`Configuration` 和变体之间存在一对一的映射关系，在这种情况下，您可以发布从单个 `Configuration` 发出的所有变体，因为它们实际上是相同的。但是，在某些情况下，`Configuration` 与额外的配置发布相关联，我们也称之为辅助变体。这种配置在跨项目发布用例中是有意义的，但在外部发布时则没有意义。例如，当您在项目之间共享一个文件目录时，但您无法直接在 Maven 存储库中发布一个目录（只能发布打包好的东西，例如 jar 或 zip）。查看 ConfigurationVariantDetails 类，了解有关如何跳过特定变体发布的详细信息。如果已经为配置调用了 `addVariantsFromConfiguration`，则可以使用 `withVariantsFromConfiguration` 对生成的变体进行进一步修改。

当发布这样的 adhoc 组件时

Gradle 模块元数据将完全表示已发布的变体。特别是，所有传出的变体将继承已发布配置的依赖项、工件和属性。
将生成 Maven 和 Ivy 元数据文件，但您需要声明如何通过 ConfigurationVariantDetails 类将依赖项映射到 Maven 范围。

实际上，这意味着以这种方式创建的组件可以像“本地组件”一样被 Gradle 使用。

向发布添加自定义工件

您应该采用 Gradle 的变体感知模型，而不是考虑工件。预计单个模块可能需要多个工件。但是，这很少就此止步，如果附加工件代表一个可选功能，它们可能也具有不同的依赖项等等。

Gradle 通过 *Gradle 模块元数据* 支持发布 *附加变体*，使这些构件为依赖项解析引擎所知。请参阅文档的变体感知共享部分，了解如何声明此类变体，以及如何发布自定义组件。

如果您直接将额外构件附加到发布，它们将“脱离上下文”发布。这意味着它们根本不会在元数据中引用，因此只能通过依赖项上的分类器直接访问。与 Gradle 模块元数据相比，Maven pom 元数据将不包含有关附加构件的信息，无论它们是通过变体添加还是直接添加，因为变体无法在 pom 格式中表示。

以下部分描述了如果您确定元数据（例如 Gradle 或 POM 元数据）与您的用例无关，如何直接发布构件。例如，如果您的项目不需要被其他项目使用，并且发布的结果只需要构件本身。

一般来说，有两种选择

仅使用构件创建发布
将构件添加到基于具有元数据的组件的发布（不推荐，而是调整组件或使用临时组件发布，这两种方法都会生成适合您的构件的元数据）

要基于构件创建发布，首先定义一个自定义构件并将其附加到您选择的 Gradle 配置。以下示例定义了一个由 rpm 任务（未显示）生成的 RPM 构件，并将该构件附加到 conf 配置

示例 5. 为配置定义自定义构件

build.gradle.kts

configurations {
    create("conf")
}
val rpmFile = layout.buildDirectory.file("rpms/my-package.rpm")
val rpmArtifact = artifacts.add("conf", rpmFile.get().asFile) {
    type = "rpm"
    builtBy("rpm")
}

build.gradle

configurations {
    conf
}
def rpmFile = layout.buildDirectory.file('rpms/my-package.rpm')
def rpmArtifact = artifacts.add('conf', rpmFile.get().asFile) {
    type 'rpm'
    builtBy 'rpm'
}

artifacts.add() 方法（来自 ArtifactHandler）返回一个类型为 PublishArtifact 的构件对象，然后可以在定义发布时使用，如以下示例所示

示例 6. 将自定义 PublishArtifact 附加到发布

build.gradle.kts

publishing {
    publications {
        create<MavenPublication>("maven") {
            artifact(rpmArtifact)
        }
    }
}

build.gradle

publishing {
    publications {
        maven(MavenPublication) {
            artifact rpmArtifact
        }
    }
}

artifact() 方法接受 *发布构件* 作为参数（例如示例中的 rpmArtifact），以及 Project.file(java.lang.Object) 接受的任何类型参数，例如 File 实例、字符串文件路径或存档任务。
发布插件支持不同的构件配置属性，因此请始终查看插件文档以获取更多详细信息。classifier 和 extension 属性由 Maven 发布插件和 Ivy 发布插件都支持。
自定义构件在发布中需要是唯一的，通常通过 classifier 和 extension 的唯一组合来实现。有关具体要求，请参阅您正在使用的插件的文档。
如果您使用 artifact() 与存档任务一起使用，Gradle 会自动使用该任务的 classifier 和 extension 属性填充构件的元数据。

现在您可以发布 RPM。

如果您真的想将构件添加到基于组件的发布，而不是调整组件本身，您可以将 from components.someComponent 和 artifact someArtifact 符号结合起来。

限制发布到特定存储库

当您定义了多个发布或存储库时，您通常希望控制哪些发布发布到哪些存储库。例如，考虑以下示例，它定义了两个发布——一个只包含二进制文件，另一个包含二进制文件和相关源代码——以及两个存储库——一个用于内部使用，另一个用于外部消费者

示例 7. 添加多个发布和存储库

build.gradle.kts

publishing {
    publications {
        create<MavenPublication>("binary") {
            from(components["java"])
        }
        create<MavenPublication>("binaryAndSources") {
            from(components["java"])
            artifact(tasks["sourcesJar"])
        }
    }
    repositories {
        // change URLs to point to your repos, e.g. http://my.org/repo
        maven {
            name = "external"
            url = uri(layout.buildDirectory.dir("repos/external"))
        }
        maven {
            name = "internal"
            url = uri(layout.buildDirectory.dir("repos/internal"))
        }
    }
}

build.gradle

publishing {
    publications {
        binary(MavenPublication) {
            from components.java
        }
        binaryAndSources(MavenPublication) {
            from components.java
            artifact sourcesJar
        }
    }
    repositories {
        // change URLs to point to your repos, e.g. http://my.org/repo
        maven {
            name = 'external'
            url = layout.buildDirectory.dir('repos/external')
        }
        maven {
            name = 'internal'
            url = layout.buildDirectory.dir('repos/internal')
        }
    }
}

发布插件将创建任务，允许您将任何发布发布到任何存储库。它们还将这些任务附加到 publish 聚合任务。但假设您想将仅二进制文件发布到外部存储库，并将包含源代码的二进制文件发布到内部存储库。为此，您需要使发布有条件。

Gradle 允许您通过 Task.onlyIf(String, org.gradle.api.specs.Spec) 方法根据条件跳过任何您想要的任务。以下示例演示了如何实现我们刚刚提到的约束

示例 8. 配置哪些工件应该发布到哪些存储库

build.gradle.kts

tasks.withType<PublishToMavenRepository>().configureEach {
    val predicate = provider {
        (repository == publishing.repositories["external"] &&
            publication == publishing.publications["binary"]) ||
        (repository == publishing.repositories["internal"] &&
            publication == publishing.publications["binaryAndSources"])
    }
    onlyIf("publishing binary to the external repository, or binary and sources to the internal one") {
        predicate.get()
    }
}
tasks.withType<PublishToMavenLocal>().configureEach {
    val predicate = provider {
        publication == publishing.publications["binaryAndSources"]
    }
    onlyIf("publishing binary and sources") {
        predicate.get()
    }
}

build.gradle

tasks.withType(PublishToMavenRepository) {
    def predicate = provider {
        (repository == publishing.repositories.external &&
            publication == publishing.publications.binary) ||
        (repository == publishing.repositories.internal &&
            publication == publishing.publications.binaryAndSources)
    }
    onlyIf("publishing binary to the external repository, or binary and sources to the internal one") {
        predicate.get()
    }
}
tasks.withType(PublishToMavenLocal) {
    def predicate = provider {
        publication == publishing.publications.binaryAndSources
    }
    onlyIf("publishing binary and sources") {
        predicate.get()
    }
}

gradle publish 的输出

> gradle publish
> Task :compileJava
> Task :processResources
> Task :classes
> Task :jar
> Task :generateMetadataFileForBinaryAndSourcesPublication
> Task :generatePomFileForBinaryAndSourcesPublication
> Task :sourcesJar
> Task :publishBinaryAndSourcesPublicationToExternalRepository SKIPPED
> Task :publishBinaryAndSourcesPublicationToInternalRepository
> Task :generateMetadataFileForBinaryPublication
> Task :generatePomFileForBinaryPublication
> Task :publishBinaryPublicationToExternalRepository
> Task :publishBinaryPublicationToInternalRepository SKIPPED
> Task :publish

BUILD SUCCESSFUL in 0s
10 actionable tasks: 10 executed

您可能还想定义自己的聚合任务来帮助您的工作流程。例如，假设您有几个应该发布到外部存储库的发布。一次性发布所有这些发布而不发布内部发布可能非常有用。

以下示例演示了如何通过定义一个聚合任务——publishToExternalRepository——来做到这一点，该任务依赖于所有相关的发布任务

示例 9. 定义您自己的发布简写任务

build.gradle.kts

tasks.register("publishToExternalRepository") {
    group = "publishing"
    description = "Publishes all Maven publications to the external Maven repository."
    dependsOn(tasks.withType<PublishToMavenRepository>().matching {
        it.repository == publishing.repositories["external"]
    })
}

build.gradle

tasks.register('publishToExternalRepository') {
    group = 'publishing'
    description = 'Publishes all Maven publications to the external Maven repository.'
    dependsOn tasks.withType(PublishToMavenRepository).matching {
        it.repository == publishing.repositories.external
    }
}

此特定示例通过使用 TaskCollection.withType(java.lang.Class) 和 PublishToMavenRepository 任务类型自动处理相关发布任务的引入或删除。如果您发布到 Ivy 兼容的存储库，您可以对 PublishToIvyRepository 做同样的事情。

配置发布任务

发布插件在项目评估完成后创建其非聚合任务，这意味着您无法直接从构建脚本中引用它们。如果您想配置任何这些任务，您应该使用延迟任务配置。这可以通过项目中的 tasks 集合以多种方式完成。

例如，假设您想更改 generatePomFileForPubNamePublication 任务写入其 POM 文件的位置。您可以使用 TaskCollection.withType(java.lang.Class) 方法，如以下示例所示

示例 10. 配置发布插件创建的动态命名任务

build.gradle.kts

tasks.withType<GenerateMavenPom>().configureEach {
    val matcher = Regex("""generatePomFileFor(\w+)Publication""").matchEntire(name)
    val publicationName = matcher?.let { it.groupValues[1] }
    destination = layout.buildDirectory.file("poms/${publicationName}-pom.xml").get().asFile
}

build.gradle

tasks.withType(GenerateMavenPom).all {
    def matcher = name =~ /generatePomFileFor(\w+)Publication/
    def publicationName = matcher[0][1]
    destination = layout.buildDirectory.file("poms/${publicationName}-pom.xml").get().asFile
}

上面的示例使用正则表达式从任务名称中提取发布名称。这样可以避免所有可能生成的 POM 文件的文件路径之间发生冲突。如果您只有一个发布，那么您不必担心这种冲突，因为只有一个 POM 文件。

此页面对您有帮助吗？