Wednesday, September 15, 2010

How p2 based targets work

Software Site locations in Target Definitions, typically described as "p2 based targets" are targets that get their bundles from an update site or p2 repository. This article will go over some of the implementation details of these targets. Knowing how the bundles are downloaded and added to the target can help to reproduce bugs and find workarounds.

For more general information on Target Platforms, see my previous article. The Eclipse help doc also explains a lot about how to create p2 based targets and add content to them.

The Basics:

Target definitions are created using the preference page or the editor. To create a p2 based target, at least one 'software site' location must be added to the target. The actual site location is abstracted from PDE. A local zipped repo, a remote site or a local profile will all be treated the same. A software site location specifies a site (or a category such as "all available sites") as well as one or more Root IUs. The root IUs describe what is being downloaded from the site, they are often high level features that effectively group a collection of bundles.

Target definitions must be resolved to modify the bundle list on the content tab or to set one as the active target platform. The resolve operation runs for each location independently. For most locations the resolve simply scans the location to get a list of file locations for bundles. In the case of a software site location, a more complex operation must be run.

Resolving Software Sites:

For each software site location, the following steps are taken:

  1. Load the repositories. This will create a queryable repository object. p2 will often request a repo's contents.xml file.
  2. Get the root IUs. If the location didn't already have actual installable units for the root units, the root IUs will be obtained from the site.
  3. Setup the planner or slicer. More on this later.
  4. Create a profile.
  5. Run the operation. Downloads and installs the units into the profile.
  6. Collect bundle locations for the target platform.
Note: In 3.7 a new performance enhancement was added that will skip the above steps and instead attempt to get a list of bundles from the stored profile. If the profile doesn't contain all the expected bundles or a problem occurs, the operation reverts to following the above steps.

Important Locations:

The following directories describe where PDE/p2 stores information related to the target resolution. Those familiar with p2 can modify the contents of the directories to force things to be recreated or to use the contents for a special purpose.

Target Definition Files:
Where PDE stores the targets it creates from the preference page.

Profile Location:
Where profiles are created and persisted

Bundle Pool:
Where p2 will download the bundles to during the operation

Planning vs Slicing

Once we have one or more sites and root IUs, we run a provisioning operation to download the required bundles and install them into a profile. The operation can be done using a slicer, which is typically used for mirroring a site or a planner, which is used by Eclipse to safely install and update itself.

Which one to use is determined by the options at the bottom of the wizard when editing a software site location. If "Include required software" is checked the planner is used. If unchecked the slicer is used. The include all environments setting determines if environment properties are set on the slicer.

The planner behaves the same as though we were installing the root IUs into an application. Therefore it checks that the complete set of required IUs are available to be downloaded and installed. If any IU is missing, the planner will report an error saying that a requirement is missing. This can be convenient as you may not realize some important piece is missing from your target. However, the target does not need to be a complete, runnable install, so forcibly requiring everything may be optimal.

The slicer uses an operation that copies IUs from a remote site to a local location. The slicer does create a list of required IUs, however it does not fail if the requirements are missing. Instead it will download all requirements it can from the site or sites that have been provided. This is a lot more flexible than the planner as all available IUs (even IUs that don't apply to the current environment settings) will be downloaded.


After the resolve operation is complete, a list of bundles will be returned (pointing to the local copies in the bundle pool). PDE will use the local bundles as the target.


  1. Hey Curtis. Nice article. I have a couple of questions and some recommendations at this stage.
    1. What is a safe way to flush the bundle pool? I used to delete the directory but that causes some strangeness in Eclipse until many restarts later.
    2. Only planners pull down the features! If I use a slicer the plugins are pulled down; however the feature.xml is not. Why is that?
    3. We have some P2 repos that contain a lot of 3rd party bundles. If I specify a list of bundles, save and come back at a later time to add a new bundle I have to respecify all the bundles instead of just adding one!
    4. Can some repos be planner repos (as I need the features) and others be slicers. It seems that with the UI once one repo is a planner repo all become planner repos. I even tried to modify the XML directly but I am not getting very far.
    5. In the contents section it would be nice to know where certain bundles are coming from (and related feature if available).


  2. Hi Alexadre

    1) Deleting the bundle pool directory (entirely) is the only option right now. I would expect p2 to be able to handle a non-existing bundle pool (as it does in a new workspace). If it causes some flakiness that can be reproduced, a bug should be filed against p2 (though it could be a pde problem).

    2) You can file a bug/enhancement request to get the slicer working that way. I thought that both downloaded the features, but the slicer is an internal application without documentation so getting it to do what you want is difficult.

    3) Do you just mean your having problems when editing an existing p2 location? Not everything is selected when the wizard opens? That's a known bug, a limitation of the p2 UI we reuse. Not sure if we'll get to look at it in 3.7.

    4) No, you can only have one style currently as the ius must be installed into a profile. Switching between the two apps requires a new profile which would throw away the other locations. There might be a bug for this too. It might be possible to fix, but I'm not sure how difficult it would be.

    5) Have you been talking to Jeff? He brought up this issue along with (3) and other related issues on a call today. Yes, this would be a nice touch. We don't know how hard/slow it is to look up related feature information on the fly (we don't want to store the dependency tree). There isn't a bug for this (just a comment I added to the pde wishlist).