Table of Contents
This chapter describes the new incubating Ivy publishing support provided by the “ivy-publish”
plugin. Eventually this new publishing support will replace publishing via the Upload task.
If you are looking for documentation on the original Ivy publishing support using the Upload task please see
Chapter 30, Publishing artifacts.
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 (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 Chapter 23, 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.
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” plugin works with
IvyPublication publications and IvyArtifactRepository repositories.
Applying the “ivy-publish” plugin does the following:
publishing” plugin
GenerateIvyDescriptor
task for each IvyPublication added (see Section 33.2, “Publications”).
PublishToIvyRepository task
for the combination of each IvyPublication added (see Section 33.2, “Publications”),
with each IvyArtifactRepository added (see Section 33.3, “Repositories”).
If you are not familiar with project artifacts and configurations, you should read Chapter 30, Publishing artifacts, which introduces these concepts. This chapter also describes “publishing artifacts” using a different mechanism than what is described in this chapter. The publishing functionality described here will eventually supersede that functionality.
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.
For the “ivy-publish” plugin to have any effect, an IvyPublication must be added to the set of publications.
This publication determines which artifacts are actually published as well as the details included in the associated Ivy module descriptor file.
A publication can be configured by adding components, customizing artifacts, and by modifying the generated module descriptor file directly.
The simplest way to publish a Gradle project to an Ivy repository is to specify a SoftwareComponent to publish.
The components presently available for publication are:
Table 33.1. Software Components
| Name | Provided By | Artifacts | Dependencies |
java |
Java Plugin | Generated jar file | Dependencies from 'runtime' configuration |
web |
War Plugin | Generated war file | No dependencies |
In the following example, artifacts and runtime dependencies are taken from the `java` component, which is added by the Java Plugin.
Example 33.2. Publishing a Java module to Ivy
build.gradle
publications {
ivyJava(IvyPublication) {
from components.java
}
}
It is also possible to explicitly configure artifacts to be included in the publication. Artifacts are commonly supplied as raw files, or as instances of
AbstractArchiveTask (e.g. Jar, Zip).
For each custom artifact, it is possible to specify the name, extension, type, classifier
and conf values to use for publication. Note that each artifacts must have a unique name/classifier/extension combination.
Configure custom artifacts as follows:
Example 33.3. Publishing additional artifact to Ivy
build.gradle
task sourceJar(type: Jar) {
from sourceSets.main.java
classifier "source"
}
publishing {
publications {
ivy(IvyPublication) {
from components.java
artifact(sourceJar) {
type "source"
conf "runtime"
}
}
}
}
See the IvyPublication class in the API documentation for more detailed information on how artifacts can be customized.
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 attributes when configuring the IvyPublication. The status
and branch attributes 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.
Example 33.4. customizing the publication identity
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
}
}
}
Gradle will handle any valid Unicode character for organisation, module and revision (as well as artifact 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.
At times, the module descriptor file generated from the project information will need to be tweaked before publishing. The “ivy-publish”
plugin provides a hook to allow such modification.
Example 33.5. Customizing the module descriptor file
build.gradle
publications {
ivyCustom(IvyPublication) {
descriptor.withXml {
asNode().info[0].appendNode('description',
'A demonstration of ivy descriptor customization')
}
}
}
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.
See IvyModuleDescriptorSpec.withXml(org.gradle.api.Action) in the API documentation for more information.
It is possible to modify virtually any aspect of the created descriptor should you need to. This means that it is also 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.
The identifier (organisation, module, revision) of the published module is an exception; these values cannot be modified in the descriptor using the `withXML` hook.
Sometimes it's useful to publish multiple modules from your Gradle build, without creating a separate Gradle subproject. An example is publishing a separate API and implementation jar for your library. With Gradle this is simple:
Example 33.6. Publishing multiple modules from a single project
build.gradle
task apiJar(type: Jar) {
baseName "publishing-api"
from sourceSets.main.output
exclude '**/impl/**'
}
publishing {
publications {
impl(IvyPublication) {
organisation 'org.gradle.sample.impl'
module 'project2-impl'
revision '2.3'
from components.java
}
api(IvyPublication) {
organisation 'org.gradle.sample'
module 'project2-api'
revision '2'
}
}
}
If a project defines multiple publications then Gradle will publish each of these to the defined repositories. Each publication must be given a unique identity as described above.
Publications are published to repositories. The repositories to publish to are defined by the PublishingExtension.getRepositories()
container.
Example 33.7. Declaring repositories to publish to
build.gradle
repositories {
ivy {
// change to point to your repo, e.g. http://my.org/repo
url "$buildDir/repo"
}
}
The DSL used to declare repositories for publishing is the same DSL that is used to declare repositories for dependencies (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.
The created task is named “publish«PUBNAME»PublicationTo«REPONAME»Repository”,
which is “publishIvyJavaPublicationToIvyRepository” for this example. This task is of type
PublishToIvyRepository.
Example 33.8. Choosing a particular publication to publish
build.gradle
apply plugin: 'java' apply plugin: 'ivy-publish' group = 'org.gradle.sample' version = '1.0' publishing { publications { ivyJava(IvyPublication) { from components.java } } repositories { ivy { // change to point to your repo, e.g. http://my.org/repo url "$buildDir/repo" } } }
Output of gradle publishIvyJavaPublicationToIvyRepository
> gradle publishIvyJavaPublicationToIvyRepository :generateDescriptorFileForIvyJavaPublication :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :jar :publishIvyJavaPublicationToIvyRepository BUILD SUCCESSFUL Total time: 1 secs
The “publish” plugin (that the “ivy-publish” plugin implicitly applies) adds a lifecycle task
that can be used to publish all publications to all applicable repositories named “publish”.
In more concrete terms, executing this task will execute all PublishToIvyRepository tasks in the project.
This is usually the most convenient way to perform a publish.
Example 33.9. Publishing all publications via the “publish” lifecycle task
Output of gradle publish
> gradle publish :generateDescriptorFileForIvyJavaPublication :compileJava UP-TO-DATE :processResources UP-TO-DATE :classes UP-TO-DATE :jar :publishIvyJavaPublicationToIvyRepository :publish BUILD SUCCESSFUL Total time: 1 secs
At times it is useful to generate the Ivy module descriptor file (normally ivy.xml) without publishing your module to an Ivy repository.
Since descriptor file generation is performed by a separate task, this is very easy to do.
The “ivy-publish” plugin creates one GenerateIvyDescriptor task
for each registered IvyPublication,
named “generateDescriptorFileFor«PUBNAME»Publication”, which will be
“generateDescriptorFileForIvyJavaPublication” for the previous example of the “ivyJava” publication.
You can specify where the generated Ivy file will be located by setting the destination property on the generated task.
By default this file is written to “build/publications/«PUBNAME»/ivy.xml”.
Example 33.10. Generating the Ivy module descriptor file
build.gradle
model {
tasks.generateDescriptorFileForIvyCustomPublication {
destination = file("$buildDir/generated-ivy.xml")
}
}
Output of gradle generateDescriptorFileForIvyCustomPublication
> gradle generateDescriptorFileForIvyCustomPublication :generateDescriptorFileForIvyCustomPublication BUILD SUCCESSFUL Total time: 1 secs
The “ivy-publish” plugin leverages some experimental support for late plugin configuration,
and the GenerateIvyDescriptor task will not be constructed until the publishing extension is configured.
The simplest way to ensure that the publishing plugin is configured when you attempt to access the GenerateIvyDescriptor task
is to place the access inside a model block, as the example above demonstrates.
The same applies to any attempt to access publication-specific tasks like PublishToIvyRepository.
These tasks should be referenced from within a model block.
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 33.11. Publishing a Java module
build.gradle
subprojects {
apply plugin: 'java'
apply plugin: 'ivy-publish'
version = '1.0'
group = 'org.gradle.sample'
repositories {
mavenCentral()
}
task sourceJar(type: Jar) {
from sourceSets.main.java
classifier "source"
}
}
project(":project1") {
description = "The first project"
dependencies {
compile 'junit:junit:4.12', project(':project2')
}
}
project(":project2") {
description = "The second project"
dependencies {
compile '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(sourceJar) {
type "source"
conf "runtime"
}
descriptor.withXml {
asNode().info[0].appendNode('description', description)
}
}
}
}
}
The result is that the following artifacts will be published for each project:
ivy-1.0.xml”.project1-1.0.jar”.project1-1.0-source.jar”.
When project1 is published, the module descriptor (i.e. the ivy.xml file) that is produced will look like:
Note that «PUBLICATION-TIME-STAMP» in this example Ivy module descriptor will be the timestamp of when the descriptor was generated.
Example 33.12. Example generated ivy.xml
output-ivy.xml
<?xml version="1.0" encoding="UTF-8"?> <ivy-module version="2.0"> <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="default" visibility="public" extends="runtime"/> <conf name="runtime" visibility="public"/> </configurations> <publications> <artifact name="project1" type="jar" ext="jar" conf="runtime"/> <artifact name="project1" type="source" ext="jar" conf="runtime" m:classifier="source" xmlns:m="http://ant.apache.org/ivy/maven"/> </publications> <dependencies> <dependency org="junit" name="junit" rev="4.12" conf="runtime->default"/> <dependency org="org.gradle.sample" name="project2" rev="1.0" conf="runtime->default"/> </dependencies> </ivy-module>
The “ivy-publish” plugin functionality as described above is incomplete, as the feature is still incubating.
In upcoming Gradle releases, the functionality will be expanded to include (but not limited to):
module, organisation etc.)module descriptor.