Categories with Composite Repos

>> Thursday, May 21, 2009

Categories are groupings of elements that are available for installation in the p2 user ui. For example, the categories in the Eclipse and Equinox site look something like this...

Ensuring that categories are generated in the content.jar has always been a bit tricky. You can generate a buildtime site.xml that's used to specify the categories which is passed as an argument to the generator. However, this site.xml isn't actually used in the repo because that's old update manager technology. So 2007. You can also add the category name in a p2.inf. Again, not the most intuitive approach.

Today, John Arthorne proposed an interesting solution to this issue in bug 277359 that doesn't require changes to the build scripts. The trick is to add a child metadata repository to your composite repository that only specifies your category IUs. The steps are as follows:

Add a "categories" directory to your composite repository

In the categories directory, add a content.jar that specifies the IUs of the of the categories you want to display. For the Eclipse project's SDK category, the content.xml looks something like this...

<unit id="org.eclipse.sdk.ide.categoryIU" version="0.0.0">
<properties size="2">
<property name="" value="Eclipse SDK">
<property name="org.eclipse.equinox.p2.type.category" value="true">
<provides size="1">
<provided namespace="org.eclipse.equinox.p2.iu" name="org.eclipse.sdk.ide.categoryIU" version="0.0.0">
<requires size="1">
<required namespace="org.eclipse.equinox.p2.iu" name="org.eclipse.sdk.ide" range="0.0.0">
<touchpoint id="null" version="0.0.0">

The final task is to add the child repo "categories" to your compositeContent.jar in the root of your composite repository. You can use the p2 ant tasks to add the child repo or modify the CompositeContent.xml directly.

<children size="4">
<child location="I20090518-2000">
<child location="I20090519-2000">
<child location="I20090520-2000">
<child location="categories">

For more information, see bug 277359, the Eclipse and Equinox projects' integration build repo's categories content.jar and compositeContent.jar.


David Carver 6:00 AM  

One question about all this there an XML Schema or an EMF model that describes it? Several reasons to do this:

1. Documentation on what each element means and does.

2. Validation.

3. Data Binding and generating an API to program against to create it.

4. Validation.

Yes, I put validation twice, as it's really important that the XML be valid in these situations. Especially with the size of some of the p2 repositories and meta data.

Kim Moir 6:34 AM  

Dave, I may have given the impression that the xml was handcrafted. It wasn't. All the xml is generated by the p2 APIs. There isn't a schema. We depend on the p2 APIs to generate the correct XML. If there is a problem with the generated XML, it's in the APIs. If you are interested in writing a schema, you could talk to the p2 team about helping out in this regard. However, the XML that describes the metadata and artifacts is subject to change, and often does:-)

Ian Bull 10:31 AM  


For most of p2 there isn't an XML schema and this is by design. There is no requirement that these repositories be backed by XML. In p2, we just provide an interface. You can implement the interface however you like and serialize it to XML, property files, punch cards or a highly scalable database. It doesn't matter.

The default implementations that p2 provides are XML backed, but we don't want people to think that they have to use XML.

Alain Picard 10:05 AM  

We have used the P2 ant task to create a composite repository and we are looking to group all of these features and plugins under a single category to facilitate its deployment.

This is exactly what this article is talking about. But from David's comment it is clear that there is a missing link and it is mentioned that all of the XML was generated by the p2 APIs.

But we have tried to figure out how to do that, first with ant task and then we turned to the p2.publisher.CategoryPublisher
without success (it gives us java.lang.UnsupportedOperationException: Cannot add IUs to a composite repository). This error might be caused by not using the command correctly.

But anyhow, would it be possible to better detail the process carried out in achieving the results described in this article. We are unfortunately not releng experts and we might just be missing some critical and obvious piece to the puzzle.

Thanks for your help.

Kim Moir 1:27 PM  

Alain, I haven't used the category publisher myself. I'd recommend asking this question on the p2-dev mailing list where someone from the p2 team should be able to help you out.

Alain Picard 4:46 PM  

Thanks. I will do, but that makes me even more perplex, what are you using to generate the content.xml that goes in the categories folder?

Kim Moir 12:21 PM  

Alain, one of my p2 committer friends generated the xml :-)

Jörn Guy Süß 11:26 PM  

We have reverse engineered DTDs from existing samples as we need slim maintenance tools based on plain java and the P2 api is not available as Maven dependencies. I would love to use these APIs, especially the new 3.7 BundleProject would be awesome for our quality control, but getting the Eclipse elephant to run in an ant task is just not a quick and easy job... So again, we are hacking the representation. I would love to see a set of APIs for manipulating Eclipse's special files (, .project ...) but it seems rather far away. :(

Post a Comment

  © Blogger template Simple n' Sweet by 2009

Back to TOP