Ivy Publish Plugin

The Ivy Publish Plugin provides the ability to publish build artifacts in the Apache Ivy format, usually to a repository for consumption by other builds or projects. What is published is one or more artifacts created by the build, and an Ivy module descriptor (normally ivy.xml) that describes the artifacts and the dependencies of the artifacts, if any.

A published Ivy module can be consumed by Gradle (see Declaring Dependencies) and other tools that understand the Ivy format. You can learn about the fundamentals of publishing in Publishing Overview.

Usage

To use the Ivy Publish Plugin, include the following in your build script:

Example 1. Applying the Ivy Publish Plugin

GroovyKotlin

build.gradle

plugins {
    id 'ivy-publish'
}

The Ivy Publish Plugin uses an extension on the project named publishing of type PublishingExtension. This extension provides a container of named publications and a container of named repositories. The Ivy Publish Plugin works with IvyPublication publications and IvyArtifactRepository repositories.

Tasks

generateDescriptorFileForPubNamePublication — GenerateIvyDescriptor: Creates an Ivy descriptor file for the publication named PubName, populating the known metadata such as project name, project version, and the dependencies. The default location for the descriptor file is build/publications/$pubName/ivy.xml.
publishPubNamePublicationToRepoNameRepository — PublishToIvyRepository: Publishes the PubName publication to the repository named RepoName. If you have a repository definition without an explicit name, RepoName will be "Ivy".
publish: Depends on: All publishPubNamePublicationToRepoNameRepository tasks

An aggregate task that publishes all defined publications to all defined repositories.

Publications

This plugin provides publications of type IvyPublication. To learn how to define and use publications, see the section on basic publishing.

There are four main things you can configure in an Ivy publication:

A component — via IvyPublication.from(org.gradle.api.component.SoftwareComponent).
Custom artifacts — via the IvyPublication.artifact(java.lang.Object) method. See IvyArtifact for the available configuration options for custom Ivy artifacts.
Standard metadata like module, organisation and revision.
Other contents of the module descriptor — via IvyPublication.descriptor(org.gradle.api.Action).

You can see all of these in action in the complete publishing example. The API documentation for IvyPublication has additional code samples.

Identity values for the published project

The generated Ivy module descriptor file contains an <info> element that identifies the module. The default identity values are derived from the following:

organisation - Project.getGroup()
module - Project.getName()
revision - Project.getVersion()
status - Project.getStatus()
branch - (not set)

Overriding the default identity values is easy: simply specify the organisation, module or revision properties when configuring the IvyPublication. status and branch can be set via the descriptor property — see IvyModuleDescriptorSpec.

The descriptor property can also be used to add additional custom elements as children of the <info> element, like so:

Example 2. customizing the publication identity

GroovyKotlin

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
        }
    }
}

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"])
        }
    }
}

💡	Certain repositories are not able to handle all supported characters. For example, the `:` character cannot be used as an identifier when publishing to a filesystem-backed repository on Windows.

Gradle will handle any valid Unicode character for organisation, module and revision (as well as the artifact’s name, extension and classifier). The only values that are explicitly prohibited are \, / and any ISO control character. The supplied values are validated early during publication.

Customizing the generated module descriptor

At times, the module descriptor file generated from the project information will need to be tweaked before publishing. The Ivy Publish Plugin provides a DSL for that purpose. Please see IvyModuleDescriptorSpec in the DSL Reference for the complete documentation of available properties and methods.

The following sample shows how to use the most common aspects of the DSL:

Example 3. Customizing the module descriptor file

GroovyKotlin

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()
                }
            }
        }
    }

build.gradle.kts

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

In this example we are simply adding a 'description' element to the generated Ivy dependency descriptor, but this hook allows you to modify any aspect of the generated descriptor. For example, you could replace the version range for a dependency with the actual version used to produce the build.

You can also add arbitrary XML to the descriptor file via IvyModuleDescriptorSpec.withXml(org.gradle.api.Action), but you can not use it to modify any part of the module identifier (organisation, module, revision).

⚠	It is possible to modify the descriptor in such a way that it is no longer a valid Ivy module descriptor, so care must be taken when using this feature.

Customizing dependencies versions

By default, the set of dependencies and constraints that are added to the Ivy file will contain the versions declared in the build file. Sometimes it is desirable to publish the resolved version instead.

Example use cases:

A project uses dynamic versions for dependencies but prefers exposing the resolved version for a given release to its consumers.
In combination with dependency locking, you want to publish the locked versions.
A project leverages the rich versions constraints of Gradle, which have a lossy conversion to Ivy. Instead of relying on the conversion, it publishes the resolved versions.

This is done by using the versionMapping DSL method which allows to configure the VersionMappingStrategy:

Example 4. Using resolved versions

GroovyKotlin

build.gradle

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

build.gradle.kts

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

In the example above, Gradle will use the versions resolved on the runtimeClasspath for dependencies declared in api, which are mapped to the compile configuration of Ivy. Gradle will also use the versions resolved on the runtimeClasspath for dependencies declared in implementation, which are mapped to the runtime configuration of Ivy. fromResolutionResult() indicates that Gradle should use the default classpath of a variant and runtimeClasspath is the default classpath of java-runtime.

Repositories

This plugin provides repositories of type IvyArtifactRepository. To learn how to define and use repositories for publishing, see the section on basic publishing.

Here’s a simple example of defining a publishing repository:

Example 5. Declaring repositories to publish to

GroovyKotlin

build.gradle

publishing {
    repositories {
        ivy {
            // change to point to your repo, e.g. http://my.org/repo
            url = "$buildDir/repo"
        }
    }
}

The two main things you will want to configure are the repository’s:

URL (required)
Name (optional)

You can define multiple repositories as long as they have unique names within the build script. You may also declare one (and only one) repository without a name. That repository will take on an implicit name of "Ivy".

You can also configure any authentication details that are required to connect to the repository. See IvyArtifactRepository for more details.

Complete example

The following example demonstrates publishing with a multi-project build. Each project publishes a Java component and a configured additional source artifact. The descriptor file is customized to include the project description for each project.

Example 6. Publishing a Java module

GroovyKotlin

build.gradle

subprojects {
    apply plugin: 'java'
    apply plugin: 'ivy-publish'

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

    repositories {
        mavenCentral()
    }
    task sourcesJar(type: Jar) {
        from sourceSets.main.java
        archiveClassifier = 'sources'
    }
}

project(':project1') {
    description = 'The first project'

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

project(':project2') {
    description = 'The second project'

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

subprojects {
    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
                artifact(sourcesJar) {
                    type = 'sources'
                    conf = 'compile'
                }
                descriptor.description {
                    text = description
                }
            }
        }
    }
}

build.gradle.kts

subprojects {
    apply(plugin = "java")
    apply(plugin = "ivy-publish")

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

    repositories {
        mavenCentral()
    }
    task<Jar>("sourcesJar") {
        from(project.the<SourceSetContainer>()["main"].java)
        archiveClassifier.set("sources")
    }
}

project(":project1") {
    description = "The first project"

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

project(":project2") {
    description = "The second project"

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

subprojects {
    configure<PublishingExtension>() {
        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"])
                artifact(tasks["sourcesJar"]) {
                    type = "sources"
                    conf = "compile"
                }
                descriptor.description {
                    text.set(description)
                }
            }
        }
    }
}

The result is that the following artifacts will be published for each project:

The Ivy module descriptor file: ivy-1.0.xml.
The primary JAR artifact for the Java component: project1-1.0.jar.
The source JAR artifact that has been explicitly configured: project1-1.0-source.jar.

When project1 is published, the module descriptor (i.e. the ivy.xml file) that is produced will look like:

Example: Generated ivy.xml

output-ivy.xml

<!-- This file is an example of the Ivy module descriptor that this build will produce -->
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0" xmlns:m="http://ant.apache.org/ivy/maven">
  <info organisation="org.gradle.sample" module="project1" revision="1.0" status="integration" publication="«PUBLICATION-TIME-STAMP»">
    <description>The first project</description>
  </info>
  <configurations>
    <conf name="compile" visibility="public"/>
    <conf name="default" visibility="public" extends="compile,runtime"/>
    <conf name="runtime" visibility="public"/>
  </configurations>
  <publications>
    <artifact name="project1" type="sources" ext="jar" conf="compile" m:classifier="sources"/>
    <artifact name="project1" type="jar" ext="jar" conf="compile"/>
  </publications>
  <dependencies>
    <dependency org="junit" name="junit" rev="4.12" conf="runtime-&gt;default"/>
    <dependency org="org.gradle.sample" name="project2" rev="1.0" conf="runtime-&gt;default"/>
  </dependencies>
</ivy-module>

💡	Note that `«PUBLICATION-TIME-STAMP»` in this example Ivy module descriptor will be the timestamp of when the descriptor was generated.