How does ivy:publish work?

Question

I'm completely at loss how the ant task ivy:publish is supposed to work.

I would expect that I do my normal build, which creates a bunch of jar files, then I would push those jars to the (local) repository.

How can I specify from where to retrieve the built jars, and how would those end up in the repository?

Update:

<target name="publish-local" description="--> Publish Local">
 <ivy:retrieve />
 <ivy:publish resolver="local" pubrevision="${release.version}" status="release" update="true" overwrite="true">
  <artifacts pattern="${dist.dir}/[organisation]-[module].[ext]" />
 </ivy:publish>
</target>

this actually works, I didn't include the retrieve before.

But I still have some problems, suppose I want to publish 3 jars, openscada-utils.jar, openscada-utils-sources.jar and openscada-utils-javadocs.jar as openscada-utils-0.9.2.jar, openscada-utils-0.9.2-sources.jar and openscada-utils-0.9.2-javadocs.jar

It isn't entirely clear to me, how the actual names are assembled, and where I can specify which names they should get. (Using the fragment above, the jars are always called only utils.jar).

Update 1:

I got it to work (a bit), but it still doesn't feel right. Somehow all tutorials focus on dependencies from 3rd party projects, but an equally important point for me is to handle project specific dependencies.

I have a bunch of sub projects which depend on each other in various ways. Considering ivy:publish it is not clear to me how to start.

1.) How do I handle the first version? I have a common version number for all sub projects to indicate that they belong together (lets say 0.9). Therefore the first revision should be 0.9.0, but so far nothing of my projects is in my repository. How do I get Ivy to assign this revision number.

2.) In the course of developing I want to publish the built files again, without changing the revision number so far.

3.) If I'm finished with my work I want to push it to a shared repository (and increase the revision number lets say from 0.9.0 to 0.9.1), what is the recommended approach to do so?

4.) For an actual release, I want to make distributions with dependencies and without, somehow I guess I can use different configurations for that. How can I use that to my advantage?

Answer 1

You need to specify the "resolver". Something like:

<ivy:publish resolver="local" pubrevision="1.0"/>

It's controlled by the pattern. This page covers it pretty well. It looks like you want yours to be:

<artifacts pattern="${dist.dir}/[organisation]-[module]-[revision]-[type].[ext]" />

And you'll need to identify the three jars as artifacts in the ivy.xml file. Something like this:

<publications>
    <artifact name="utils"/>
    <artifact name="utils" type="source"/>
    <artifact name="utils" type="javadocs"/>
</publications>

Answer 2

It's important to realize what ivy is doing here. It is NOT simply copying your artifact jars into the ivy repository - it is also generating the relevant ".ivy.xml" files that specify all the dependents of each of your artifacts.

Under the covers, the ivy:retrieve task is actually also triggering an ivy:resolve. When that ivy:resolve occurs, a file is written to your local ivy cache (in the .ivy folder in user.home) that specifies how the resolution happened (which revisions of which modules were required to complete the resolution.) When ivy:publish is encountered, that resolution record is retrieved from cache and used to generate the ivy.xml for your artifacts.

The largest pitfall I've found in doing this is the requirement that the ivy:resolve and ivy:publish tasks both be loaded by the same classloader when they are executed by ant. The easiest way to make sure this happens is to use the loaderRef on your taskdef tasks. For example (note the matching loaderRef tags):

<taskdef name="ivy-retrieve" 
     classname="org.apache.ivy.ant.IvyRetrieve" 
     classpathref="ivy.lib" 
     loaderRef="ivy.loader"/>
<taskdef name="ivy-publish" 
     classname="org.apache.ivy.ant.IvyPublish" 
     classpathref="ivy.lib" 
     loaderRef="ivy.loader"/>