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」。
發佈: 依賴於：所有 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 的任何有效 Unicode 字元（以及人工製品的 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 = "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 相依性描述符，但這個掛鉤讓您可以修改產生的描述符的任何面向。例如，您可以將相依性的版本範圍替換為用於產生建置的實際版本。

您也可以透過 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。

此頁面有幫助嗎？