Chapter 58. Ivy Publishing (new)

This chapter describes how 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 that describes the artifacts and the dependencies of the artifacts, if any.

A published Ivy module can be consumed by Gradle (see Chapter 44, Dependency Management) and other tools that understand the Ivy format.

The ability to publish in the Ivy format is provided by the “ivy-publish” plugin.

apply plugin: 'ivy-publish'

This plugin does the following:

The “publishing” plugin creates 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” works with IvyPublication publications and IvyArtifactRepository repositories.

Publication objects describe the structure/configuration of a publication to be created. Publications are published to repositories via tasks, and the configuration of the publication object determines exactly what is published. All of the publications of a project are defined in the PublishingExtension.getPublications() container. Each publication has a unique name within the project.

At this time, it is not possible to create arbitrary publication objects. When the “ivy-publish” plugin is applied it creates a single publication named “ivy”. This publication will publish all of artifacts of all of the project's visible configurations, and any configurations that they extend from.

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

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

dependencies {
   compile 'junit:junit:4.8.2', project(':subproject')
}

repositories {
    mavenCentral()
}

task sourceJar(type: Jar) {
    baseName = 'ivypublishSource'
    from sourceSets.main.java
    classifier = 'src'
}

artifacts {
    archives sourceJar
}

publishing {
    publications {
        ivy {
            descriptor {
                withXml {
                    asNode().dependencies.dependency.find { it.@org == "junit" }.@rev = "4.10"
                }
            }
        }
    }
}

The “publishing.publications.ivy” publication that was added to the “publishing.publications” container of the project will be configured to publish two artifacts:

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

<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0">
  <info organisation="org.gradle.test" module="ivypublish" revision="1.0" status="integration" publication="«PUBLICATION-TIME-STAMP»"/>
  <configurations>
    <conf name="archives" visibility="public" description="Configuration for archive artifacts."/>
    <conf name="compile" visibility="private" description="Classpath for compiling the main sources."/>
    <conf name="default" visibility="public" description="Configuration for default artifacts." extends="runtime"/>
    <conf name="runtime" visibility="private" description="Classpath for running the compiled main classes." extends="compile"/>
    <conf name="testCompile" visibility="private" description="Classpath for compiling the test sources." extends="compile"/>
    <conf name="testRuntime" visibility="private" description="Classpath for running the compiled test classes." extends="runtime,testCompile"/>
  </configurations>
  <publications>
    <artifact name="ivypublish" type="jar" ext="jar" conf="archives,runtime"/>
    <artifact name="ivypublishSource" type="jar" ext="jar" conf="archives" m:classifier="src" xmlns:m="http://ant.apache.org/ivy/maven"/>
  </publications>
  <dependencies>
    <dependency org="junit" name="junit" rev="4.10" conf="compile-&gt;default"/>
    <dependency org="ivypublish" name="subproject" rev="unspecified" conf="compile-&gt;default"/>
  </dependencies>
</ivy-module>

The attributes of the <info> tag identify the module. These values are derived from the following project properties:

Note that you can set the value of these project properties in your build script, with the exception of name.

publishing {
    publications {
        ivy {
            descriptor {
                withXml {
                    asNode().dependencies.dependency.find { it.@org == "junit" }.@rev = "4.10"
                }
            }
        }
    }
}

Publications are published to repositories. The repositories to publish to are defined by the PublishingExtension.getRepositories() container.

publishing {
    repositories {
        ivy {
            url "http://mycompany.com/repo" // change to point to your repo
            credentials {
                username "user1"
                password "secret"
            }
        }
    }
}

The DSL used to declare repositories to publish to is the same DSL that is used to declare repositories to consume dependencies from, RepositoryHandler. However, in the context of Ivy publication only the repositories created by the ivy() methods can be used as publication destinations. You cannot publish an IvyPublication to a Maven repository for example.

The “ivy-publish” plugin automatically creates a PublishToIvyRepository task for each IvyPublication and IvyArtifactRepository combination in the publishing.publications and publishing.repositories containers respectively.

In the example we have been working with so far, given that the publication that the “ivy-publish” plugin creates is named “ivy” and that the default name for repositories created using the ivy() methods of the publishing.repositories container is also “ivy”, a publish task will be created with the name “publishIvyPublicationToIvyRepository”. The naming pattern is “publish«NAME OF PUBLICATION»PublicationTo«NAME OF REPOSITORY»Repository”.

Executing this task will build all of the artifacts to be published, and transfer them to the repository.

Output of gradle publishIvyPublicationToIvyRepository

:subproject:compileJava
:subproject:processResources UP-TO-DATE
:subproject:classes
:subproject:jar
:compileJava
:processResources UP-TO-DATE
:classes
:jar
:sourceJar
:publishIvyPublicationToIvyRepository

BUILD SUCCESSFUL

Total time: 1 sec

:subproject:compileJava
:subproject:processResources UP-TO-DATE
:subproject:classes
:subproject:jar
:compileJava
:processResources UP-TO-DATE
:classes
:jar
:sourceJar
:publishIvyPublicationToIvyRepository
:publish

BUILD SUCCESSFUL

Total time: 1 sec

The “ivy-publish” functionality as described above is incomplete, as the feature is still incubating. Over the coming Gradle releases, the functionality will be expanded to include (but not limited to):