Ivy 发布插件提供了以 Apache Ivy 格式发布构建制品的能力,通常发布到仓库供其他构建或项目使用。发布的内容是一个或多个由构建创建的制品,以及一个 Ivy 模块描述符(通常是 ivy.xml
),它描述了制品以及制品的依赖关系(如果有的话)。
用法
要使用 Ivy 发布插件,请在您的构建脚本中包含以下内容
plugins {
`ivy-publish`
}
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)。
-
自定义制品 — 通过 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>
元素的子元素添加,如下所示
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"])
}
}
}
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 最常见的方面
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()
}
}
}
}
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 添加到描述符文件,但不能使用它修改模块标识符的任何部分(organization、module、revision)。
有可能以使描述符不再是有效的 Ivy 模块描述符的方式修改它,因此在使用此功能时必须小心。 |
自定义依赖项版本
支持两种发布依赖项的策略
- 声明的版本(默认)
-
此策略发布构建脚本作者在
dependencies
块中通过依赖项声明定义的版本。任何其他类型的处理,例如通过 更改解析版本的规则,将不会被发布考虑在内。 - 已解析的版本
-
此策略发布在构建期间解析的版本,可能通过应用解析规则和自动冲突解决。这具有已发布的版本与已发布制品经过测试的版本相对应的优点。
已解析版本的示例用例
-
项目对依赖项使用动态版本,但更喜欢向其消费者公开给定版本的已解析版本。
-
结合 依赖锁定,您希望发布锁定的版本。
-
项目利用 Gradle 丰富的版本约束,这些约束到 Ivy 的转换是有损的。它不是依赖于转换,而是发布已解析的版本。
这是通过使用 versionMapping
DSL 方法完成的,该方法允许配置 VersionMappingStrategy
publications {
create<IvyPublication>("ivyCustom") {
versionMapping {
usage("java-api") {
fromResolutionOf("runtimeClasspath")
}
usage("java-runtime") {
fromResolutionResult()
}
}
}
}
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 的仓库。要了解如何定义和使用仓库进行发布,请参阅 基本发布 部分。
下面是一个定义发布仓库的简单示例
publishing {
repositories {
ivy {
// change to point to your repo, e.g. http://my.org/repo
url = uri(layout.buildDirectory.dir("repo"))
}
}
}
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 和源代码制品。描述符文件经过定制,以包含每个项目的项目描述。
rootProject.name = "ivy-publish-java"
include("project1", "project2")
plugins {
`kotlin-dsl`
}
repositories {
gradlePluginPortal()
}
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 })
}
}
}
}
plugins {
id("myproject.publishing-conventions")
}
description = "The first project"
dependencies {
implementation("junit:junit:4.13")
implementation(project(":project2"))
}
plugins {
id("myproject.publishing-conventions")
}
description = "The second project"
dependencies {
implementation("commons-collections:commons-collections:3.2.2")
}
rootProject.name = 'ivy-publish-java'
include 'project1', 'project2'
plugins {
id 'groovy-gradle-plugin'
}
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 })
}
}
}
}
plugins {
id 'myproject.publishing-conventions'
}
description = 'The first project'
dependencies {
implementation 'junit:junit:4.13'
implementation project(':project2')
}
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
。