An important part of an Ivy publication is the descriptor file. We already saw that Gradle added a generateDescriptorFile<publicationName> task to our project. Furthermore, we can define some properties of the descriptor file inside a publication configuration. Gradle also offers a hook to customize the generated descriptor file even further.
Gradle uses the project's version, group, name, and status properties for the info element in the Ivy descriptor file generated. We will create a new example build file where we define the project properties, so they will be included in the file:
apply plugin: 'ivy-publish'
apply plugin: 'java'
// Defined project properties, that are
// used in the generated descriptor file.
// The name of the project is by default
// the directory name, but we can
// change it via a settings.gradle file
// and the rootProject.name property.
version = '2.1.RELEASE'
group = 'book.gradle'
repositories {
jcenter()
}
dependencies {
compile 'org.springframework:spring-context:4.1.4.RELEASE'
}
publishing {
publications {
sample(IvyPublication) {
from components.java
}
}
}Now, we execute the generateDescriptorFileForSamplePublication task. An ivy.xml file is created in the build/publications/sample directory. If we open the file, we can see that the info element attributes are filled with the values from our Gradle build file. The following code shows this:
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0">
<info organisation="book.gradle" module="sample" revision="2.1.RELEASE" status="integration" publication="20150424051601"/>
<configurations>
<conf name="default" visibility="public" extends="runtime"/>
<conf name="runtime" visibility="public"/>
</configurations>
<publications>
<artifact name="sample" type="jar" ext="jar" conf="runtime"/>
</publications>
<dependencies>
<dependency org="org.springframework" name="spring-context" rev="4.1.4.RELEASE" conf="runtime->default"/>
</dependencies>
</ivy-module>We can override the values for organisation, module, revision, status, and branch inside a publication configuration. We need to set the properties in the configuration block of IvyPublication. The status and branch properties need to be set via the
descriptor property. Via the descriptor property, we can also add new child elements to the info element in the Ivy descriptor file. In the next example build file, we will use these methods to set the values:
apply plugin: 'ivy-publish'
apply plugin: 'java'
version = '2.1.DEVELOPMENT'
group = 'book.gradle'
repositories {
jcenter()
}
dependencies {
compile 'org.springframework:spring-context:4.1.4.RELEASE'
}
publishing {
publications {
sample(IvyPublication) {
organisation = 'book.sample.gradle'
module ='bookSample'
version = '2.1'
descriptor.status = 'published'
descriptor.branch = 'n/a'
// Add extra element as child
// for info.
descriptor.extraInfo '', 'ivyauthor', 'Hubert Klein Ikkink'
from components.java
}
}
}We execute the generateDescriptorFileForSamplePublication task again, as shown in the following code, and we see the new values in the generated Ivy descriptor file:
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0">
<info organisation="book.sample.gradle" module="bookSample" branch="n/a" revision="2.1.DEVELOPMENT" status="published" publication="20150424053039">
<ns:ivyauthor xmlns:ns="">Hubert Klein Ikkink</ns:ivyauthor>
</info>
<configurations>
<conf name="default" visibility="public" extends="runtime"/>
<conf name="runtime" visibility="public"/>
</configurations>
<publications>
<artifact name="bookSample" type="jar" ext="jar" conf="runtime"/>
</publications>
<dependencies>
<dependency org="org.springframework" name="spring-context" rev="4.1.4.RELEASE" conf="runtime->default"/>
</dependencies>
</ivy-module>The dependencies of our project are added as dependencies in the generated descriptor file. This happens because we use the from method with the components.java value inside our publication configuration. The Java software component not only adds the jar archive tasks as an artifact, but also turns the project dependencies into dependencies in the descriptor file. If we use an archive task to define an artifact, the dependencies element is not added to the file.
In the following example build file, we use the artifact method to define the publication:
apply plugin: 'ivy-publish'
apply plugin: 'java'
// Defined project properties, that are
// used in the generated descriptor file.
// The name of the project is by default
// the directory name, but we can
// change it via a settings.gradle file
// and the rootProject.name property.
version = '2.1.RELEASE'
group = 'book.gradle'
repositories {
jcenter()
}
dependencies {
compile 'org.springframework:spring-context:4.1.4.RELEASE'
}
publishing {
publications {
sample(IvyPublication) {
artifact jar
}
}
}When we run the generateDescriptorFileForSamplePublication task from the command line, the Ivy descriptor file is generated. The contents of the file are now as follows:
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0">
<info organisation="book.gradle" module="sample" revision="2.1.RELEASE" status="integration" publication="20150424053351"/>
<configurations/>
<publications>
<artifact name="sample" type="jar" ext="jar"/>
</publications>
<dependencies/>
</ivy-module>In the next section, you will learn how we can customize the descriptor using the withXml method of the descriptor property. We can then, for example, also change the dependency scope of our project dependencies.
To add extra elements to the generated file, we must use the descriptor property that is part of IvyPublication. This returns an IvyModuleDescriptorSpec object, and we will invoke the withXml method from this object to add extra elements to the descriptor file. We use a closure with the withXml method to access an XmlProvider object. With the XmlProvider object, we can get a reference to a DOM element with the asElement method, a Groovy node object with the asNode method, or a StringBuilder object with the asString method to extend the descriptor XML.
In the following example build file, we add the description and issueMangement elements to the generated descriptor file:
apply plugin: 'ivy-publish'
apply plugin: 'java'
version = '2.1.RELEASE'
group = 'book.gradle'
repositories {
jcenter()
}
dependencies {
compile 'org.springframework:spring-context:4.1.4.RELEASE'
}
publishing {
publications {
sample(IvyPublication) {
from components.java
// Customize generated descriptor XML.
descriptor.withXml {
asNode()
.appendNode('description',
'Sample Gradle project')
asNode()
.appendNode('issueManagement')
.with {
appendNode('system', 'Jenkins')
appendNode('url', 'http://buildserver/')
}
}
}
}
}If we generate the Ivy descriptor file, we can see our newly created elements in the XML version:
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0">
<info organisation="book.gradle" module="sample" revision="2.1.RELEASE" status="integration" publication="20150424053914"/>
<configurations>
<conf name="default" visibility="public" extends="runtime"/>
<conf name="runtime" visibility="public"/>
</configurations>
<publications>
<artifact name="sample" type="jar" ext="jar" conf="runtime"/>
</publications>
<dependencies>
<dependency org="org.springframework" name="spring-context" rev="4.1.4.RELEASE" conf="runtime->default"/>
</dependencies>
<description>Sample Gradle project</description>
<issueManagement>
<system>Jenkins</system>
<url>http://buildserver/</url>
</issueManagement>
</ivy-module>In the previous section, you already learned that if we use the from method with the components.java value, all project dependencies are added as runtime dependencies in the generated descriptor file. This might not be what we always want. Using the withXml method, we can not only add new elements, but also change values.
Let's add a hook where we change the module attribute of the info element. In the next build file, we will implement this:
apply plugin: 'ivy-publish'
apply plugin: 'java'
version = '2.1.RELEASE'
group = 'book.gradle'
repositories {
jcenter()
}
dependencies {
compile 'org.springframework:spring-context:4.1.4.RELEASE'
}
publishing {
publications {
sample(IvyPublication) {
from components.java
descriptor.withXml {
// Replace value for module attribute
// in info element.
new StringBuilder(
asString()
.replaceAll(
/module="sample"/,
'module="ivyChapter"'))
}
}
}
}The generated descriptor file now has the following contents:
<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0">
<info organisation="book.gradle" module="ivyChapter" revision="2.1.RELEASE" status="integration" publication="20150424055754"/>
<configurations>
<conf name="default" visibility="public" extends="runtime"/>
<conf name="runtime" visibility="public"/>
</configurations>
<publications>
<artifact name="sample" type="jar" ext="jar" conf="runtime"/>
</publications>
<dependencies>
<dependency org="org.springframework" name="spring-context" rev="4.1.4.RELEASE" conf="runtime->default"/>
</dependencies>
</ivy-module>