Ivy 发布插件 - Gradle 构建系统

Ivy 发布插件提供了以 Apache Ivy 格式发布构建 Artifact 的能力，通常发布到仓库以供其他构建或项目使用。发布的内容包括构建产生的一个或多个 Artifact，以及一个描述这些 Artifact 及其依赖项（如果存在）的 Ivy 模块描述符（通常是 ivy.xml）。

发布的 Ivy 模块可以被 Gradle（参见声明依赖项）以及其他理解 Ivy 格式的工具消费。您可以在发布概述中了解发布的各项基础知识。

用法

要使用 Ivy 发布插件，请在构建脚本中包含以下内容

示例 1. 应用 Ivy 发布插件

build.gradle.kts

plugins {
    `ivy-publish`
}

build.gradle

plugins {
    id 'ivy-publish'
}

Ivy 发布插件在项目上使用了一个名为 publishing 的扩展，其类型为 PublishingExtension。此扩展提供了一个命名发布项的容器和一个命名仓库的容器。Ivy 发布插件适用于 IvyPublication 类型的发布项和 IvyArtifactRepository 类型的仓库。

任务

generateDescriptorFileForPubNamePublication — GenerateIvyDescriptor: 为名为 PubName 的发布项创建 Ivy 描述符文件，填充已知元数据，例如项目名称、项目版本和依赖项。描述符文件的默认位置是 build/publications/$pubName/ivy.xml。
publishPubNamePublicationToRepoNameRepository — PublishToIvyRepository: 将名为 PubName 的发布项发布到名为 RepoName 的仓库。如果您定义了一个没有显式名称的仓库，则 RepoName 将是 "Ivy"。
publish: 依赖于：所有 publishPubNamePublicationToRepoNameRepository 任务

这是一个聚合任务，将所有定义的发布项发布到所有定义的仓库。

发布项

此插件提供发布项，类型为 IvyPublication。要了解如何定义和使用发布项，请参阅有关基本发布的章节。

您可以在 Ivy 发布项中配置四个主要方面

一个组件 — 通过 IvyPublication.from(org.gradle.api.component.SoftwareComponent)。
自定义 Artifact — 通过 IvyPublication.artifact(java.lang.Object) 方法。有关自定义 Ivy Artifact 的可用配置选项，请参阅 IvyArtifact。
标准元数据，例如 module、organisation 和 revision。
模块描述符的其他内容 — 通过 IvyPublication.descriptor(org.gradle.api.Action)。

您可以在完整发布示例中看到所有这些的实际应用。IvyPublication 的 API 文档包含额外的代码示例。

已发布项目的标识值

生成的 Ivy 模块描述符文件包含一个 <info> 元素，用于标识模块。默认标识值派生自以下内容

organisation - Project.getGroup()
module - Project.getName()
revision - Project.getVersion()
status - Project.getStatus()
branch - (未设置)

覆盖默认标识值很简单：只需在配置 IvyPublication 时指定 organisation、module 或 revision 属性。status 和 branch 可以通过 descriptor 属性设置 — 参见 IvyModuleDescriptorSpec。

descriptor 属性也可用于添加额外的自定义元素作为 <info> 元素的子元素，如下所示

示例 2. 自定义发布项标识

build.gradle.kts

publishing {
    publications {
        create<IvyPublication>("ivy") {
            organisation = "org.gradle.sample"
            module = "project1-sample"
            revision = "1.1"
            descriptor.status = "milestone"
            descriptor.branch = "testing"
            descriptor.extraInfo("http://my.namespace", "myElement", "Some value")

            from(components["java"])
        }
    }
}

build.gradle

publishing {
    publications {
        ivy(IvyPublication) {
            organisation = 'org.gradle.sample'
            module = 'project1-sample'
            revision = '1.1'
            descriptor.status = 'milestone'
            descriptor.branch = 'testing'
            descriptor.extraInfo 'http://my.namespace', 'myElement', 'Some value'

            from components.java
        }
    }
}

某些仓库无法处理所有支持的字符。例如，在 Windows 上发布到基于文件系统的仓库时，不能使用 : 字符作为标识符。

Gradle 将处理 organisation、module 和 revision 的任何有效 Unicode 字符（以及 artifact 的 name、extension 和 classifier）。唯一明确禁止的值是 \、/ 和任何 ISO 控制字符。提供的值会在发布早期进行验证。

自定义生成的模块描述符

有时，从项目信息生成的模块描述符文件在发布前需要进行调整。Ivy 发布插件为此提供了一个 DSL。请查阅 DSL 参考中的 IvyModuleDescriptorSpec，以获取可用属性和方法的完整文档。

以下示例展示了如何使用 DSL 最常见的方面

示例 3. 自定义模块描述符文件

build.gradle.kts

publications {
    create<IvyPublication>("ivyCustom") {
        descriptor {
            license {
                name = "The Apache License, Version 2.0"
                url = "https://apache.ac.cn/licenses/LICENSE-2.0.txt"
            }
            author {
                name = "Jane Doe"
                url = "http://example.com/users/jane"
            }
            description {
                text = "A concise description of my library"
                homepage = "http://www.example.com/library"
            }
        }
        versionMapping {
            usage("java-api") {
                fromResolutionOf("runtimeClasspath")
            }
            usage("java-runtime") {
                fromResolutionResult()
            }
        }
    }
}

build.gradle

publications {
    ivyCustom(IvyPublication) {
        descriptor {
            license {
                name = 'The Apache License, Version 2.0'
                url = 'https://apache.ac.cn/licenses/LICENSE-2.0.txt'
            }
            author {
                name = 'Jane Doe'
                url = 'http://example.com/users/jane'
            }
            description {
                text = 'A concise description of my library'
                homepage = 'http://www.example.com/library'
            }
        }
        versionMapping {
            usage('java-api') {
                fromResolutionOf('runtimeClasspath')
            }
            usage('java-runtime') {
                fromResolutionResult()
            }
        }
    }
}

在此示例中，我们只是简单地向生成的 Ivy 依赖描述符添加一个 'description' 元素，但此钩子允许您修改生成描述符的任何方面。例如，您可以将依赖项的版本范围替换为用于生成构建的实际版本。

您还可以通过 IvyModuleDescriptorSpec.withXml(org.gradle.api.Action) 向描述符文件添加任意 XML，但不能使用它来修改模块标识符的任何部分（organisation、module、revision）。

有可能以某种方式修改描述符，使其不再是有效的 Ivy 模块描述符，因此在使用此功能时必须小心谨慎。

自定义依赖项版本

支持两种依赖项发布策略

声明的版本（默认）: 此策略发布的是构建脚本作者在 dependencies 块中通过依赖声明定义的版本。任何其他类型的处理，例如通过更改解析版本的规则，都不会在发布时考虑。
解析的版本: 此策略发布的是在构建过程中解析的版本，可能通过应用解析规则和自动冲突解决。这样做的好处是，发布的版本与已发布 Artifact 经过测试所使用的版本相符。

解析版本的示例用例

一个项目对依赖项使用动态版本，但偏好向其消费者暴露给定发布的已解析版本。
结合依赖锁定，您希望发布锁定的版本。
一个项目利用了 Gradle 丰富的版本约束，这些约束转换为 Ivy 会有信息丢失。与其依赖这种转换，不如发布已解析的版本。

这通过使用 versionMapping DSL 方法完成，该方法允许配置 VersionMappingStrategy

示例 4. 使用已解析的版本

build.gradle.kts

publications {
    create<IvyPublication>("ivyCustom") {
        versionMapping {
            usage("java-api") {
                fromResolutionOf("runtimeClasspath")
            }
            usage("java-runtime") {
                fromResolutionResult()
            }
        }
    }
}

build.gradle

publications {
    ivyCustom(IvyPublication) {
        versionMapping {
            usage('java-api') {
                fromResolutionOf('runtimeClasspath')
            }
            usage('java-runtime') {
                fromResolutionResult()
            }
        }
    }
}

在上面的示例中，Gradle 将对在 api 中声明的依赖项使用在 runtimeClasspath 上解析的版本，这些依赖项映射到 Ivy 的 compile 配置。Gradle 还会对在 implementation 中声明的依赖项使用在 runtimeClasspath 上解析的版本，这些依赖项映射到 Ivy 的 runtime 配置。fromResolutionResult() 表示 Gradle 应使用变体的默认类路径，而 runtimeClasspath 是 java-runtime 的默认类路径。

仓库

此插件提供仓库，类型为 IvyArtifactRepository。要了解如何定义和使用用于发布的仓库，请参阅有关基本发布的章节。

以下是一个定义发布仓库的简单示例

示例 5. 声明要发布的仓库

build.gradle.kts

publishing {
    repositories {
        ivy {
            // change to point to your repo, e.g. http://my.org/repo
            url = uri(layout.buildDirectory.dir("repo"))
        }
    }
}

build.gradle

publishing {
    repositories {
        ivy {
            // change to point to your repo, e.g. http://my.org/repo
            url = layout.buildDirectory.dir("repo")
        }
    }
}

您想要配置的两个主要方面是仓库的

URL（必需）
名称（可选）

您可以定义多个仓库，只要它们在构建脚本中具有唯一的名称。您也可以声明一个（且只能声明一个）没有名称的仓库。该仓库将获得一个隐式名称 "Ivy"。

您还可以配置连接到仓库所需的任何认证详情。有关更多详细信息，请参见 IvyArtifactRepository。

完整示例

以下示例演示了使用多项目构建进行发布。每个项目都发布一个 Java 组件，该组件配置为同时构建和发布 Javadoc 和源代码 Artifact。描述符文件经过自定义，包含每个项目的项目描述。

示例 6. 发布 Java 模块

settings.gradle.kts

rootProject.name = "ivy-publish-java"
include("project1", "project2")

buildSrc/build.gradle.kts

plugins {
    `kotlin-dsl`
}

repositories {
    gradlePluginPortal()
}

buildSrc/src/main/kotlin/myproject.publishing-conventions.gradle.kts

plugins {
    id("java-library")
    id("ivy-publish")
}

version = "1.0"
group = "org.gradle.sample"

repositories {
    mavenCentral()
}

java {
    withJavadocJar()
    withSourcesJar()
}

publishing {
    repositories {
        ivy {
            // change to point to your repo, e.g. http://my.org/repo
            url = uri(rootProject.layout.buildDirectory.dir("repo"))
        }
    }
    publications {
        create<IvyPublication>("ivy") {
            from(components["java"])
            descriptor.description {
                text = providers.provider({ description })
            }
        }
    }
}

project1/build.gradle.kts

plugins {
    id("myproject.publishing-conventions")
}

description = "The first project"

dependencies {
    implementation("junit:junit:4.13")
    implementation(project(":project2"))
}

project2/build.gradle.kts

plugins {
    id("myproject.publishing-conventions")
}

description = "The second project"

dependencies {
    implementation("commons-collections:commons-collections:3.2.2")
}

settings.gradle

rootProject.name = 'ivy-publish-java'
include 'project1', 'project2'

buildSrc/build.gradle

plugins {
    id 'groovy-gradle-plugin'
}

buildSrc/src/main/groovy/myproject.publishing-conventions.gradle

plugins {
    id 'java-library'
    id 'ivy-publish'
}

version = '1.0'
group = 'org.gradle.sample'

repositories {
    mavenCentral()
}

java {
    withJavadocJar()
    withSourcesJar()
}

publishing {
    repositories {
        ivy {
            // change to point to your repo, e.g. http://my.org/repo
            url = rootProject.layout.buildDirectory.dir('repo')
        }
    }
    publications {
        ivy(IvyPublication) {
            from components.java
            descriptor.description {
                text = providers.provider({ description })
            }
        }
    }
}

project1/build.gradle

plugins {
    id 'myproject.publishing-conventions'
}

description = 'The first project'

dependencies {
    implementation 'junit:junit:4.13'
    implementation project(':project2')
}

project2/build.gradle

plugins {
    id 'myproject.publishing-conventions'
}

description = 'The second project'

dependencies {
    implementation 'commons-collections:commons-collections:3.2.2'
}

结果是，每个项目将发布以下 Artifact

Gradle 模块元数据文件：project1-1.0.module。
Ivy 模块元数据文件：ivy-1.0.xml。
Java 组件的主要 JAR Artifact：project1-1.0.jar。
Java 组件的 Javadoc 和源代码 JAR Artifact（因为我们配置了 withJavadocJar() 和 withSourcesJar()）：project1-1.0-javadoc.jar, project1-1.0-source.jar。

此页面是否有帮助？