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.

65.1. The “ivy-publish” Plugin

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.

65.2. Publications

If you are not familiar with project artifacts and configurations, you should read Chapter 52, 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.

65.2.1. Publishing a Software Component

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:

In the following example, artifacts and runtime dependencies are taken from the `java` component, which is added by the Java Plugin.

Example 65.2. Publishing a Java module to Ivy

build.gradle

publications {
ivyJava(IvyPublication) {
from components.java
}
}

65.2.2. Publishing custom artifacts

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.

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.

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

65.2.4. Modifying 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 hook to allow such modification.

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.

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.

65.2.5. Publishing multiple modules

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:

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.

65.5. Generating the Ivy module descriptor file without publishing

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”.

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.

65.6. 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.

65.7. Future features

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):