Ivy 发布插件 - Gradle 中文

Ivy Publish 插件提供了将构建工件发布到 Apache Ivy 格式的能力，通常发布到仓库供其他构建或项目使用。发布的内容是构建创建的一个或多个工件，以及一个 Ivy 模块描述符（通常是 ivy.xml），它描述了工件及其依赖项（如果有）。

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

用法

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

示例 1. 应用 Ivy Publish 插件

build.gradle.kts

plugins {
    `ivy-publish`
}

build.gradle

plugins {
    id 'ivy-publish'
}

Ivy Publish 插件使用项目上名为 publishing 的扩展，类型为 PublishingExtension。此扩展提供了一个命名出版物的容器和一个命名仓库的容器。Ivy Publish 插件与 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)。
自定义工件 — 通过 IvyPublication.artifact(java.lang.Object) 方法。有关自定义 Ivy 工件的可用配置选项，请参阅 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（以及构件的 name、extension 和 classifier）中的任何有效 Unicode 字符。唯一明确禁止的值是 \、/ 和任何 ISO 控制字符。提供的值将在发布期间尽早进行验证。

自定义生成的模块描述符

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

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

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

build.gradle.kts

publications {
    create<IvyPublication>("ivyCustom") {
        descriptor {
            license {
                name = "The Apache License, Version 2.0"
                url = "http://www.apache.org/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 = 'http://www.apache.org/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，但你不能使用它来修改模块标识符（组织、模块、修订）的任何部分。

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

自定义依赖项版本

支持两种发布依赖项的策略

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

解析版本的使用案例

一个项目使用动态版本来管理依赖，但希望在发布时向消费者公开解析后的版本。
结合依赖锁定，你可以发布锁定的版本。
一个项目利用 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 将使用 runtimeClasspath 上解析的版本来处理 api 中声明的依赖项，这些依赖项映射到 Ivy 的 compile 配置。Gradle 还将使用 runtimeClasspath 上解析的版本来处理 implementation 中声明的依赖项，这些依赖项映射到 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 和源代码工件。描述文件被定制为包含每个项目的项目描述。

示例 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.buildDir}/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.buildDir}/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'
}

结果是每个项目将发布以下工件

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

此页面对您有帮助吗？