What is a package?
To make a long story short: A package is a unit of distribution. A package may contain models (like event logs, Petri nets), plug-ins (like the alpha-miner or the dotted chart), and required (third-party) libraries. Furthermore, a package may depend on other packages.
Why does ProM 6 have packages?
The main reason for having packages in ProM 6 is to avoid problems with licenses. In ProM 5.2, we used the well-known dot graph layout through the graphviz library. This library is distributed under the CPL license. As a result, we could not include in ProM 5.2 any external library that conflicted with the CPL license, like, for example, the GPL and L-GPL licenses. To prevent this problem with licenses in ProM 6, we split up ProM 6 into a core framework (which uses a GPL license) and a collection of so-called packages. As each package corresponds to a unit of distribution, a package may be distributed under a different (and even a conflicting) license than the core framework or other packages are distributed.
A secondary reason for having packages is that it allows you, being the responsible author of the package, to determine your own strategy for releasing it. Of course we will still release the core framework from time to time, which will link to specific releases of your packages, but it is up to you to release your packages. If you do not release your package, ProM 6 cannot link to it, and ProM 6 users cannot use it.
What are these package dependencies?
A package may depend on other packages for its operation. For example, the Woflan package, which checks a WF-net for soundness, depends on the PetriNets package, which contains the implementation for Petri nets, and on the PNAnalysis package (which contains analysis routines for Petri nets). Typically, these dependencies are not only on compile-time, but also on run-time: If ProM 6 has not loaded the PetriNets package yet, loading the Woflan package will fail as it requires the implementation for Petri nets to be loaded. Nevertheless, it is also possible to have only a run-time dependency to another package.
How do I declare a package dependency?
You declare a dependency by adding a line to the ‘ivy.xml’ file in your package project. For example, the ‘ivy.xml’ file of the Log package has the following dependencies:
<dependency org="prom" name="ProM-Plugins" rev="latest" changing="true" transitive="true" />
<dependency org="prom" name="ApacheUtils" rev="latest" changing="true" transitive="true" />
<dependency org="prom" name="BasicUtils" rev="latest" changing="true" transitive="true" />
<dependency org="prom" name="Widgets" rev="latest" changing="true" transitive="true" />
<dependency org="prom" name="Saxon" rev="latest" changing="true" transitive="true" />
The first dependency is on the ProM framework, the other four on more regular ProM packages. In these lines, the ‘org=”prom”‘ part is important, as this tells Ivy that the dependency is on a ProM package.
It is important that every dependency is on a single line. By adding a line to the ‘ivy.xml’ file, you basically add a compile-time dependency for your package. Before your package is compiled, Ivy will take care that the package you depend on is added to your package. When building your package, any run-time dependencies are automatically generated from these compile-time dependencies, but for this to work properly, the compile-time dependency needs to be on a single line. So, yes, as the ‘ivy.xml’ file is an XML document, you can use multiples lines for a single compile-time dependency, but as a result the run-time dependencies will be incorrect.
How do I declare a dependency on an external library?
In the ‘ivy.xml’ file, you can also declare the dependencies of your package on external (third party) libraries. For example, the ‘ivy.xml’ file of the Log package also has the following dependency:
<dependency conf="lib->default" org="prom-libs" name="OpenXES" rev="20181205" transitive="false" />
This will make Ivy do two things:
- It will download the external ‘OpenXES’ library from the ‘prom-libs’ repository, and make it available in your package.
- It will copy the downloaded library into the lib folder of your package. As a result, the library will also be available in the ProM Nightly Build and upcoming ProM releases.
For the second to work properly, you need to take care of the following lines in your ‘build.xml’ file:
<target name="resolve"> <ivy:retrieve type="jar,bundle" sync="true" /> <ivy:retrieve pattern="lib/[artifact]-[revision].[ext]" conf="lib" type="jar,bundle" sync="false" /> </target>
Especially the third line is important, as in your ‘build.xml’ file it may be commented out (as not every package needs it). If you have any dependencies on external libraries, you need to uncomment this line. Also note the ‘sync=”false”‘ on this third line. THis is needed if your lib folder already contains files. By default, ‘sync=”true”‘ is used, which causes Ivy to remove any existing files from your lib folder, which is undesirable. So: If your lib folder contains files, use ‘sync=”false”‘, otherwise use ‘sync=”true”‘.
How do I build and release a package?
As soon as you push changes into the main branch of the package repository, GitHub will start an action to build and release your package. If this succeeds, the new release can be found in the latestrelease folder of the repository.