Ivy 發佈外掛 - Gradle 建構系統

Ivy 發佈外掛程式提供在 Apache Ivy 格式中發佈建置產出的能力，通常是發佈到儲存庫，以供其他建置或專案使用。發佈的內容是由建置建立的一或多個成品，以及描述這些成品及成品的相依性（如果有的話）的 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)。
自訂成品 — 透過 IvyPublication.artifact(java.lang.Object) 方法。請參閱 IvyArtifact 以取得自訂 Ivy 成品的可用配置選項。
標準中繼資料，例如 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 新增至描述符檔案，但您不能使用它來修改模組識別符的任何部分（organisation、module、revision）。

可以修改描述符，使其不再是有效的 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.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'
}

結果是，將為每個專案發佈以下成品

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。

此頁面是否有幫助？