Categorize your p2 repository

Categorize your p2 repository

Have you had the experience of creating an interesting application, exporting it, generating a p2 repository, connecting to your repository, and *BAM*, nothing there!  The reason this happens is because you likely didn’t categorize your repository. Consider the following:

I have created three fun games for Cell Phones: Tetris, Snakes and Pong.  Of course, to implement these I used eSWT, eRCP, ECF, GEF, EMF, OCL, BIRT and EclipseLink.  I used PDE Build to build these games and published everything to a p2 repository for cell phone users to install.  Here’s the question, when a cell phone user clicks on “Add new applications” what should they see?  Should the list include EMF, BIRT, OCL, etc…?  In Eclipse 3.5, the p2 team has taken the approach that unless you categorize you features, they will not show up in a repository.  This decision gives you complete control over what your users can see. In Milestone 7, the PDE team released some tooling to make categorization easier.

To make use of the new categorization, first create a category file:


From here you can categorize your features in the category definition editor:


Finally, you can select your category file when you export your feature(s)


Now, when you open  your repository, you Installable Units should show up.

In addition to using the PDE Export wizard, you can also use the CategoryPublisher, to inject category descriptions into your existing repositories.  This can be invoked as follows:

[code lang=”java”]
-console -consolelog -application org.eclipse.equinox.p2.publisher.CategoryPublisher
-metadataRepository file://repository
-categoryDefinition //category.xml

This approach also allows you to separate the categorization of your repository from the Installable Units. This means that you can generate a repository with all your features, and provide different categorizations for different users.

  • Kai
    Posted at 07:36, 2009-05-08

    Thanks Ian!

    This was a missing piece for my RCP apps.

  • Stefan
    Posted at 12:27, 2009-05-08

    Thanks Ian, this is really cool. How about older version, say 3.4 ? How can I do the same for Eclipse 3.4?

  • Posted at 14:57, 2009-05-08

    Hi Ian,

    Thanks! This is very useful. I was wondering how to do something like this!

    One thing I can’t figure out with P2 however, is how the heck to hide things from appearing in the list when the user unchecks the “Group Items By Category” checkbox in the update/install dialog. I have a lot of ‘configuration’ type features that will be included/required by other features and should never be installed on their own but I can see of no way to hide them from the user.
    Ideally I’d like to get rid of the checkbox entirely and force myself to provide categories all the time. Is there a way to structure a P2 repository so everything not in a category is *never* shown to a user in the UI?


  • Posted at 16:19, 2009-05-08

    In 3.4, you can feed a site.xml file to the metadata generator. Whatever features you list in that file will be exposed to the UI; those you don’t should be hidden.

    $vm -cp $launcherJar:$generatorJar:$basebuilderDir/plugins org.eclipse.equinox.launcher.Main
    -application org.eclipse.equinox.p2.metadata.generator.EclipseGenerator
    -updateSite ${targetDir}/ -site file:${targetDir}/site.xml
    -metadataRepository file:${targetDir}/ -metadataRepositoryName “$projectNameVanity Update Site”
    -artifactRepository file:${targetDir}/ -artifactRepositoryName “$projectNameVanity Artifacts”
    -compress -reusePack200Files -vmargs -Xmx128M

  • Posted at 17:01, 2009-05-08

    Thanks, Nick but that doesn’t seem to work anymore in 3.5. If I uncheck the “Group Items By Category” it shows all features, even ones that are not in my original site.xml.

  • Posted at 19:00, 2009-05-08


    Thanks – interesting reading indeed. It seems at least one use case was lost in the noise when that bug was resolved, but I did find a work-around. I recalled discussions about this magical bit in a p2.inf file:

    That’s what the RCP configuration feature does, and it is precisely for this reason. Using that with an M7 or later SDK produces metadata that causes Eclipse to hide my features from the list. That’s what I need.

  • Posted at 19:50, 2009-05-08

    Thanks, Ian. I’ve CC’d myself on that issue. I didn’t realize you could create categories from a p2.inf file as well.