Categories with Composite Repos

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…

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.

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

8 comments on “Categories with Composite Repos

  1. One question about all this XML…is 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.


  2. 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:-)


  3. David,

    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.


  4. 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.


  5. 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.



  6. 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?


  7. Alain, one of my p2 committer friends generated the xml 🙂


  8. 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 (build.properties, .project …) but it seems rather far away. 😦


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: