ProM and Ivy

hverbeek

At the moment of writing, all RunnerUp and Established packages in ProM are required to use Ivy for managing:

1. The dependency of the package on the ProM framework.
2. The dependencies of the package on other ProM packages.
3. The dependencies of the package on third-part libraries.
   

the dependencies on other ProM packages and the dependencies on third-part libraries. This post provides an explanation on how Ivy is used in the development of ProM. As running example, we will use the well-known Log package.

The structure of the ivy.xml file

The ivy.xml file of the Log package looks like follows (for sake of reference, we added line numbers):

 1 <ivy-module version="2.0">
 2    <info organisation="prom" module="Log" revision="latest">
 3        <description>
 4            Version VERSION
 5        </description>
 6    </info>
 7    <configurations>
 8           <conf name="default" extends="lib" />
 9           <conf name="lib" />
10    </configurations>  
11    <dependencies defaultconf="default">
12       <dependency org="prom" name="ProM-Plugins" rev="latest" changing="true" transitive="true" />
13       <dependency org="prom" name="ApacheUtils" rev="latest" changing="true" transitive="true" />
14       <dependency org="prom" name="BasicUtils" rev="latest" changing="true" transitive="true" />
15       <dependency org="prom" name="Widgets" rev="latest" changing="true" transitive="true" />
16       <dependency org="prom" name="Saxon" rev="latest" changing="true" transitive="true" />
17       <dependency conf="lib->default" org="prom-libs" name="OpenXES" rev="20160212" transitive="false" />
18       <dependency conf="lib->default" org="prom-libs" name="OpenXES-XStream" rev="20160212" transitive="false" />
19    </dependencies>
20 </ivy-module>

Line 12 states the dependency on the ProM framework, lines 13 to 16 state dependencies on four other ProM packages (ApacheUtils, BasicUtils, Widgets, and Saxon), and lines 17 and 18 state dependencies on two third-party libraries. Typically, you will only need to change the part between the dependencies start and end tags.

Dependency on the ProM framework

See line 12 above. Please use a single line for this dependency (do not spread this dependency over multiple lines).

Dependency on another ProM package

See lines 13 to 16 above. Replace the name of the package by the one you need. Please use a single line for each of these dependency (do not spread a dependency over multiple lines).

Possibly, you might introduce a cyclic dependency. For example, if the Widgets package would be dependent on the Log package, the above dependencies would result in a cyclic dependency between Log and Widgets. Ivy will warn for this when resolving the dependencies. You should prevent any cyclic dependency.

The reason you should use a single line for each dependency on the ProM framework or on a ProM package is that the dependencies at run-time will be generated from this ivy.xml file automatically. Run-time, that is, when ProM starts, it  needs to know these dependencies to know in which order it should load the packages. A package can only be loaded successfully if all packages it depends on have already been loaded. (Note that this is a good reason why you should not introduce cyclic dependencies...) This automatic generation assumes each of these dependencies to be on a single line.

Dependency on a third-party library

See lines 17 and 18 above. Please use the following procedure when having to add a dependency on a third-party library:

1. Check the Libs view on Hudson whether the library is already in some package. For example, the line "antlr-2.7.7.jar Uma" indicates that version 2.7.7 of the antlr library is already included in the Uma package. You can then simply add a dependency on the Uma package instead of having to add a dependency on the library itself. Please do not introduce different versions of the same library into ProM. Run-time, there is no way to tell which of these different version swill be used by ProM. If you really have to use a different version, please contact the developer of the package that already contains the library, and check whether you and the developer can agree on some version.
   
2. Check the Maven repository for the third-party library you need. If you find the library here, there is an "Apache Ivy" information field that provides you with an initial dependency line to be inserted in the ivy.xml file. What you still need to do is to add "conf=lib->default" on the line, as this takes care that the library will be available at run-time.
3. Check the Libraries folder in our repository whether the library is already there. If so, you can use a line like is used above for the OpenXES library. Please update the name and the revision number of the library.
   
4. If this all fails, and you have downloaded the library from the internet, we can add the library to this Libraries folder. Please contact us for this. Then you can successfully follow step 3.

Before asking us to add a library to the Libraries folder, please check whether the library does not come with other libraries bundled in it. These bundled libraries may very well conflict with a library already in the ProM landscape. Again, at run-time it is hard to say which one will be loaded.