Occasionally we may want to add modules developed by us to the repository. This chapter explains the Apache Ivy Publish Task which publishes modules to Ivy Repository.

Apache Ivy Publish Task

<ivy:publish> task publishes module’s artifacts and resolved descriptor to a repository. It is used to publish our own modules or even modules developed by others which are not available in any repository.

Install v/s Publish

<ivy:install> copies modules from a source repository to a destination repository. For <ivy:install> to work, module should exist in some repository. In other words, somebody has already published that module to a repository and we use <ivy:install> to copy it from there to another repository.

<ivy:publish> publishes a new module to a repository. It pushes artifacts and ivy file from an external area (like a folder in your file-system) to an Ivy Repository.

To publish a module we require its artifacts and Ivy Descriptor File ivy.xml. It is important to note that, Apache Ivy Publish task never creates the artifacts or ivy files for you. To create the artifacts, we have to use the project’s build system like Ant which creates and packages artifacts into module, source and javadoc jars.

Apache Ivy Publish Example

Let’s go through a step-by-step example to understand Apache Ivy Publish task, In the example, instead of live artifacts, we use some dummy files as artifacts. Go ahead and create some dummy artifacts in work dir.

touch simpleivy-jar.jar simpleivy-javadoc.jar simpleivy-source.jar

Command, touch, creates three zero byte files simpleivy-jar.jar simpleivy-javadoc.jar simpleivy-source.jar as module, javadoc and source artifacts.

Next, Ivy requires some info, description or metadata, to manage the module in the repository. We provide this info about the module in an ivy.xml also known as Ivy Descriptor file. Add the following ivy.xml to work dir.

ivy.xml

<ivy-module version="2.0">
 <info organisation="com.xyz" module="simpleivy" />
 <publications>
  <artifact name="simpleivy" type="jar" ext="jar" />
  <artifact name="simpleivy" type="javadoc" ext="jar" />
  <artifact name="simpleivy" type="source" ext="jar" />
 </publications>
 <dependencies>
  <dependency org="commons-lang" name="commons-lang" rev="2.6" />
 </dependencies>
</ivy-module>

In the descriptor file we provide

  • <info> - organisation and module name.

  • <publications> - artifacts of the publish

  • <artifact> - name, type and ext of the artifact.

  • <dependencies> - list of dependencies of our module. So, our module requires common-lang 2.6.

 
 

Next add Ant build.xml, with a <ivy:publish> task, to work dir.

build.xml

<project name="localrepository" default="publish" xmlns:ivy="antlib:org.apache.ivy.ant">
 <target name="publish" description="Publish this build into repository">
   <ivy:resolve/>
   <ivy:publish pubrevision="1.0" status="release" resolver="local" overwrite="true" >
       <artifacts pattern="[artifact]-[type].[ext]"/>
   </ivy:publish>
 </target>
</project>

Attributes and elements of <ivy:publish> are

  • pubrevision – publication revision. 1.0

  • status – revision status which may be one of these: integration, milestone and release .

  • resolver – name of resolver for the publish

  • artifacts pattern – the pattern to use when search for
    artifacts mentioned in ivy.xml. Dummy artifacts have simple pattern
    [artifact]-[type].[ext] like simpleivy-javadoc.jar. It is important to note that, Ivy uses this pattern only to search the artifacts defined in ivy.xml, but not for placing them in the repository. While placing the artifacts in the repository, Ivy uses the pattern provided in the resolver definition for naming the directories and artifacts.

To recap the steps,

  • place the module artifacts in the work dir

  • add ivy.xml which provides module info to Ivy.

  • add build.xml that contains the <ivy:publish> task

We are ready to publish our simpleivy module to local repository. Run Ant to publish. The console output of Publish is shown in next the screen-shot.

[ivy:publish] :: publishing :: com.xyz#simpleivy
[ivy:publish] published simpleivy to /home/m/.ivy2/local/com.xyz/simpleivy/1.0/jars/simpleivy.jar
[ivy:publish] published simpleivy to /home/m/.ivy2/local/com.xyz/simpleivy/1.0/javadocs/simpleivy.jar
[ivy:publish] published simpleivy to /home/m/.ivy2/local/com.xyz/simpleivy/1.0/sources/simpleivy.jar
[ivy:publish] published ivy to /home/m/.ivy2/local/com.xyz/simpleivy/1.0/ivys/ivy.xml

In $HOME/.ivy2/local, Publish task creates a directory structure com.xyz/simpleivy/1.0 and under this, it has created four sub-folders: jars, javadocs, sources and ivys. Artifacts lands in first three sub-folders and descriptor file goes into ivys sub-folder. If you analyze the repository layout pattern, it is clear that Ivy has used following patterns, from default local resolver definitions in /org/apache/ivy/core/settings/ivysettingslocal.xml , to place the files in the local repository.

[organisation]/[module]/[revision]/[type]s/[artifact].[ext] to place ivy.xml

[organisation]/[module]/[revision]/[type]s/[artifact].[ext] to place artifacts

Delivered Ivy Descriptor File

After a publish, if you check the work dir, you find two Ivy descriptor files.

  • orginal ivy.xml provided by you

  • ivy-ivy.xml generated by the <ivy:publish>

Descriptor file, ivy-ivy.xml generated by <ivy:publish> is the resolved descriptor which is also known as delivered ivy file.

Before the actual publish, <ivy:publish> task internally calls <ivy:deliver> task which generates a resolved descriptor of the module based upon the last resolve done. The resolved ivy file contains updated information about the delivered module, such as revision and status. The original ivy.xml never gets into the repository and the new ivy-ivy.xml is the descriptor file that lands in the repository.

 
 

 

Once a module is published, developers are free to use the new module as a dependency like any other modules in the repository.