Using the deltapack in Eclipse 3.5

Eclipse Galileo was released yesterday and I have already seen a couple of questions on the newsgroups regarding how to install the delta pack.

What's a delta pack?

For those who don't know what it is, the delta pack is a zip file provided by the Eclipse Platform and it is used for developing RCP applications for multiple platforms. The delta pack archive contains all the platform specific fragments from the Eclipse SDK. It also includes a feature "org.eclipse.equinox.executable" which contains binary launchers for all the platforms. The archive is available for download through the Eclipse Classic "Other downloads" page.

The delta pack is required if you want to do headless product builds, or to export products from the UI:

If you don't have the delta pack installed, then the option to export your product for multiple platforms will not appear in the wizard.

How to install the delta pack

Ian Bull blogged about the improved Target Platform management system as #3 in his Galileo Feature top ten list. This is the recommended method of installing the delta pack.

1. Extract the delta pack archive into its own directory on disk.
2. Open the Target Platform preferences (Window -> Preferences -> Plug-in Development -> Target Platform).
3. Add a new target, or edit the active target.
4. Add the directory where you extracted the delta pack.

Patching Features (Part 2)

In my last post I showed how to create a simple feature patch. However, this patch leaves us in a state where we can no longer upgrade the platform because the patch itself requires a specific version of the feature it is patching.

Making the patch Optional

If we make the inclusion of the patch in our org.example.feature optional, then we no longer block upgrading the platform underneath us.


When a new version of the platform is available, there is a conflict between the version of the p2.user.ui feature required by the patch and the one required by the new platform. By making the patch optional, p2 will not install the patch if there is a conflict.

This is fine if the new version of the platform includes the fix we want. But what if it doesn't? What if we need to have our patch apply to several different versions of the platform?

Relaxing version ranges

Unfortunately, currently the only way to do the following is to edit the metadata by hand. (Paul Webster uses XSLT transforms, I have also raised a bug to allow changing things using the p2.inf file.)

Looking at the metadata for the patch, we see a few interesting sections:

The Patch Scope

The scope section of the patch's metadata specifies which feature(s) the patch applies to:

<patchScope>
<scope>
  <requires size='1'>
    <required namespace='org.eclipse.equinox.p2.iu'
                 name='org.eclipse.equinox.p2.user.ui.feature.group'
                 range='[1.1.0.v20090605-1440-7u6Fb3FbPbJP5MiKiZgpdl,1.1.0.v20090605-1440-7u6Fb3FbPbJP5MiKiZgpdl]'/>
  </requires>
</scope>
</patchScope>

Here we see the patch applies to a specific version of the org.eclipse.equinox.p2.user.ui feature. By relaxing the version range here we can make the patch apply to other versions of the platform. For example, say we knew our bug was fixed on June 11, but there were several version between June 5th and the 10th that still contained the bug. We could instead use a version range like [1.1.0.v20090605-1440,1.1.0.v20090611) (the upper end of the range is open, it includes everything up to but not including v20090611).

Note that the patch Installable Unit also has normal requirements on the feature it is patching. When widening the scope range, the regular requirements should also be widened to match.

Change From / Change To

The 'changes' section of the patch's metadata specifies which plug-in we are patching, and the version to change it to.

<changes>
<change>
  <from>
    <required namespace='org.eclipse.equinox.p2.iu'
                 name='org.eclipse.equinox.p2.touchpoint.eclipse'
                 range='0.0.0'/>
  </from>
  <to>
    <required namespace='org.eclipse.equinox.p2.iu'
                 name='org.eclipse.equinox.p2.touchpoint.eclipse'
                 range='[1.0.101.v20090611,1.0.101.v20090611]'/>
  </to>
</change>
</changes>

In the above example, we are changing the org.eclipse.equinox.p2.touchpoint.eclipse bundle from any version ("0.0.0") to version 1.0.101.v20090611.
We could imagine changing these ranges in the following ways:

• Change the "scope" range to "0.0.0" to match any version of the p2.user.ui feature, and then change the "change from" range to [1.0.101, 1.0.101.v20090611). This would result in patching any version of the p2.user.ui feature that includes any 1.0.101 versioned bundle up to v20090611 (which is the version with the proper fix).
• Change the "change to" range to something like [1.0.101.v20090611, 1.0.102). We know v20090611 contains the fix we want, but the in the future there will be more bug fixes before the maintenance stream is released. By widening the range here, we allow future bug fixes to also be included in our patch.
  

Patching features with p2

The Galileo release of Eclipse is in its final days. The eclipse SDK itself is effectively done and the current build is under consideration to be the final release.

Imagine This...

Say I have a feature that I build, it runs on top of the Eclipse Platform. I know Eclipse Galileo is coming out soon, so I download it and try it out with my feature.

Oh No! It doesn't work! I've found a bug in the platform, and its a major blocker for me. (Oops, maybe I should have tried this a couple of months ago when there still would have been time to fix the bug.)

Meta-Comment: The Eclipse Platform Project has a reputation for shipping on time (even if that means there are unresolved bugs). There is a strict end game plan that is followed for the release, lock down started back at the beginning of May. The further we are along in the plan, the harder it is to get a fix approved for release. A lot of people don't seem to relealize this happens, and perhaps wonder why their important bugs are defered with the comment "Its too late".

Ok, I need to patch the platform. How do I do this?

The Example Feature

To work through the steps of patching the platform, I created my own example feature:

1. Create a New Plug-in Project "org.example.plugin". The plug-in is not a "Rich client Application". On the templates page of the wizard I chose "Plug-in with a view".
2. Create a New Feature "org.example.feature". Add org.example.plugin to the feature.
3. Export the feature, and on the Options tab in the export wizard check "Generate metadata repository".

For the purposes of the example, I'm starting from the Eclipse Platform Runtime 3.5RC4. Because I want to strictly control the upgrade path in the example, I removed the Galileo and Eclipse Project repositories from the available sites (Window -> Preferences -> Install/Update->Available Software Sites).

Unzip the platform, and installed the feature from the exported repository. I didn't create any categories for the feature, so "Group items by category" must be unchecked.

The Patch

For the example, I am inspired by bug 279542 which came in very late and almost was not fixed in 3.5. The bundle org.eclipse.equinox.p2.touchpoint.eclips has the bug and this plugin is included by the feature org.eclipse.equinox.p2.user.ui.

Say we have a fix with touchpoint.eclipse version 1.0.101.v20090611. (When following the eclipse versioning guidelines, the maintenance version of this bundle should be 1.0.101 and the version for the next year's release will probably be 1.0.200).

We can easily create a new Feature Patch with the wizard:
We specify the version of p2.user.ui that we are patching (here the one shipped in 3.5RC4). In the feature patch, include org.eclipse.equinox.p2.touchpoint.eclipse with the specific version containing the fix. Then, add the feature patch as an inclusion in our org.example.feature:

<feature id="org.example.feature" label="Feature" version="1.0.0.qualifier">
 <includes id="org.example.patch" version="0.0.0" /> 
 <plugin id="org.example.plugin" version="0.0.0" unpack="false"/>
</feature>

<feature id="org.example.patch" label="Patch" version="1.0.0">
 <requires>
    <import feature="org.eclipse.equinox.p2.user.ui" version="1.1.0.v20090605-1440-7u6Fb3FbPbJP5MiKiZgpdl" patch="true"/>
 </requires>
 <plugin id="org.eclipse.equinox.p2.touchpoint.eclipse" version="1.0.101.v20090611" unpack="false"/>
</feature>

If we have the bundle containing the fix in our target platform, we can now export a new version of our example feature that includes it. And we can update the platform where our feature is installed to get the new version that brings the patch with it.

The metadata for the Patch installable unit looks like this:

<unit id='org.example.patch.feature.group' version='1.0.0' singleton='false'>
 <patchScope>
   <scope>
     <requires size='1'>
       <required namespace='org.eclipse.equinox.p2.iu' name='org.eclipse.equinox.p2.user.ui.feature.group' range='[1.1.0.v20090605-1440-7u6Fb3FbPbJP5MiKiZgpdl,1.1.0.v20090605-1440-7u6Fb3FbPbJP5MiKiZgpdl]'/>
     </requires>
   </scope>
 </patchScope>
 <changes>
   <change>
     <from>
       <required namespace='org.eclipse.equinox.p2.iu' name='org.eclipse.equinox.p2.touchpoint.eclipse' range='0.0.0'/>
     </from>
     <to>
       <required namespace='org.eclipse.equinox.p2.iu' name='org.eclipse.equinox.p2.touchpoint.eclipse' range='[1.0.101.v20090611,1.0.101.v20090611]'/>
     </to>
   </change>
 </changes>
...
<requires size='2'>
   <required namespace='org.eclipse.equinox.p2.iu' name='org.eclipse.equinox.p2.user.ui.feature.group' range='[1.1.0.v20090605-1440-7u6Fb3FbPbJP5MiKiZgpdl,1.1.0.v20090605-1440-7u6Fb3FbPbJP5MiKiZgpdl]' greedy='false'/>
...  

This says, in org.eclipse.equinox.p2.user.ui.feature.group version 1.1.0.v20090605-1440-7u6Fb3FbPbJP5MiKiZgpdl, change whatever version of org.eclipse.equinox.p2.touchpoint.eclipse is there to version 1.0.101.v20090611.

It works! Except...

It works, except that we notice that the patch IU has hard requirements on the version of the p2.user.ui feature. This would prevent upgrading the underlying platform because the feature patch has locked down the version of the p2.user.ui feature.

p2 is much more flexible about patches than the old Update manager was, so there are a few different ways to address this, and I will write another post covering this soon.

(Right now its Friday after 5pm, and time to go home for the weekend :) )

Building p2 RCP products in Eclipse 3.5M6

We can also call this "Building for the Cloud" just to take advantage of the newest buzz word.

Susan Franklin McCourt put together a nice wiki page covering how to add p2 self-updating support to your RCP application. One of those examples was called "Updating from the Cloud".

As part of preparing for EclipseCon, I put together a simple releng product build that builds this cloud product for p2. The cloud bundle "org.eclipse.equinox.p2.examples.rcp.cloud" is available in CVS together with a releng project that I created.

To run this example, check both projects out into your workspace, and read the rcp.cloud.releng/readme.txt.

Builder Setup

The releng project serves at the builder for a headless build. The build.properties file is a copy of the template provided by PDE/Build with some things we don't need removed. We modified the following properties:

• product : This defines the .product file which specifies how to create the cloud product. The first segment of this path is the plug-in id for the cloud project that contains the file.
• configs : Here we define the platforms we are building for. This is currently set to build windows, other platforms can be added. (The default here is *,*,* which is platform independent pieces, which doesn't make sense for a product).
• J2SE-1.5 : The cloud project has a Bundle-RequiredExecutionEnvironment of 1.5. We set this property to be the bootclasspath to use for compiling 1.5. See the eclipse help for more details on these properties. We also set CDC-1.1/Foundation-1.1 because we had the org.eclipse.osgi bundle in our workspace (and so were compiling it for the product) and osgi requires that EE defined in order to compile properly.
• p2.gathering : We set this to true to use the new support for publishing metadata directly from source. This will also automatically install the product using the p2 director. More details on this below.
• p2.metadata.repo, p2.artifact.repo : In addition to the installed product, we also want a p2 repository.

We also provide a simple ant script named "buildProduct.xml". This is a very simple script that does the following:

1. Set the baseLocation. This is the location of your target binaries against which you want to compile. In the script we set it to ${eclipse.home} which is a property that is automatically set to be the eclipse that is running the build.
2. Find the delta pack. The delta pack is required for headless product builds because it contains all the platform specific fragments, and org.eclipse.equinox.executable feature which contains launchers for all the platforms. Download the 3.5M6 deltapack from here. The deltapack location will be added to the pluginPath property.
   
3. builder : the location of the build configuration files (ie: build.properties). We set it to be the directory containing the buildProduct.xml script.
   
4. buildDirectory: the directory where everything happens, set it to a subfolder of our builder.
5. pluginPath: the location to find more plugins and features. Here we add the workspace (one level up from the builder), and the deltapack.
6. Run the build. The property ${eclipse.pdebuild.scripts} is automatically set to the location of the PDE/Build scripts directory. Here we call the product build.
7. Victory! : copy the resulting archive into the root of the releng product.

The results of this build is a fully provisioned, p2 enabled product with an accompanying repository.

p2.gathering

In 3.4, p2 metadata was generated by running the metadata generator on the binary jars that were the result of the build. At the end of the build you were left with a repository and you need to perform a director install for get a fully p2-enabled product.

In 3.5 we have this new property p2.gathering. Setting this to true does a couple of things:

• Generate metadata from source. PDE/Build extends the p2 publisher to publish metadata and artifacts directly from source (and the compiled .class files) into a repository. There are no intermediate steps. (This also has the side effect of increased performance).
• Feature Builds result in a repository that is a group of all the platforms that were built. (This is an implicit groupConfigurations=true).
• Product Builds result in a fully installed p2 enabled product. This removes the need for a manual director call after the build is complete. The product build can also create a repository containing the IUs required to install the product.

The 3.4 properties still work for doing the old style generation.

Installing and running plugins in Eclipse applications

A common question on the newsgroups is: "I copied new plug-ins into my RCP application but they are getting ignored, what's the problem?". The answer to this is really quite fundamental and is something I think every RCP developer should understand.

My answer here is about the Equinox runtime which is used in Eclipse and is the reference implementation of the OSGi spec.

Installing into the OSGi Runtime

Every plug-in (or bundle, I use the terms interchangeably), must be installed into the OSGi runtime before you can even think about it running. There are two main ways to install a bundle: programmatically through the BundleContext API, or declaratively through the osgi.bundles property in the config.ini file.

The osgi.bundles property is read at startup. It is a list of bundles that are automatically installed and optionally started once the framework is up and running. The format of each entry is

<URL | simple bundle location>[@ [<start-level>] [":start"]]

Starting your bundles

It is not enough to simply have your plug-in installed, it must also be started. When the OSGi framework starts up, it increments through the start levels starting bundles as it goes. A bundle won't be started until its start level is reached, and to get started it must be marked as such, or be marked as lazy start. A lazy start bundle will be started when something tries to load a class from that bundle (and once the start level has been reached for that bundle).

[Edit:] In most cases, marking a bundle as Lazy-Start is sufficient and one need not worry about starting bundles explicitly. See Neil's comment attached to this post.

The default start level for bundles is 4.

Managing installed bundles

There are 2 strategies here, one is to list all of your bundles on the osgi.bundles list, the other is to list only a few bundles that can bootstrap the rest of the application. I will call this kind of bootstrap bundle a "configurator".

If you list all your plug-ins on the osgi.bundles property, then it can be painful to maintain and add new plug-ins to your application. I won't try to make arguments for or against any particular way of managing your system, but it a large way it often comes back to the differences between the old update manager and the new p2 provisioning system.

Update Configurator

In Eclipse 3.3 and earlier, there was the update configurator (org.eclipse.update.configurator). It was installed on the osgi.bundles list and started at level 3. It would scan the plugins directory and automatically install everything it found there.

This is where the magic ability to just copy things into the plugins directory and have them work came from. However, update configurator is essentially forcing the found bundles into the framework with no regard to any conflicts or unresolved dependencies that may result.

Simple Configurator

In Eclipse 3.4, with the advent of p2, update configurator is replace with simple configurator (org.eclipse.equinox.simpleconfigurator). As the name suggests, it is quite simple: it installs everything it finds listed in its configuration file (specified by the org.eclipse.equinox.simpleconfigurator.configUrl property, usually bundles.info).

Editing the bundles.info file to add plug-ins to your product is not really any easier than editing the osgi.bundles list. The difference here is that p2 manages bundles.info for you. In fact, if your product is p2 enabled for updating and installing plug-ins, then any changes made manually are likely to be lost when p2 updates or installs new software.

Dropins

Whatever the other problems update has with respect to avoiding conflicts and ensuring that dependencies are satisfied, it is hard to ignore the simplicity of just copying new bundles into your install. p2 has support for dropins (provided by org.eclipse.equinox.p2.reconciler.dropins).

Like the update configurator, the dropins reconciler will automatically watch a directory and install things it finds there. However, unlike the update configurator, it will ensure that the bundles found will not conflict with others in the system and that all dependencies are satisfied.

Headless build problems with Grouped Configurations

PDE/Build has a property named groupConfigurations. If you set this property, build will group all the configurations (ie win32,win32,x86 & gtk,linux,x86) into one archive instead of creating a separate archive per configuration.

Kim & I, while working to get the performance baselines going, found a couple of gotchas/bugs around the use of this property.

Unexpected archive format for the group

The first thing we noticed was that the group archive was being created using ant's zip task instead of using the native zip as expected. Our builder's build.properties specified the following:

configs = *,*,*
archivesFormat = *,*,*-zip
groupConfigurations = true

If we had read the documentation, we would have seen that the archivesFormat is ignored for groups. However, this is not strictly true, and we can instead set a format for the group directly:

configs=*,*,*
archivesFormat = group,group,group-zip
groupConfigurations = true

This results in the zip format as desired.

The directory group.group.group does not exist

We also ran into the following error:

/builds/src/assemble.org.eclipse.sdk.tests.group.group.group.xml:257: The directory
/builds/src/tmp/eclipse/group.group.group does not exist

This turns out to be a rather old bug. The problem is that when features gather together the rootfiles they contribute, they copy them into platform specific folders. In this case, building the *,*,* configuration, the rootfiles were copied into tmp/ANY.ANY.ANY. However, because of the way the grouped configurations feature is implemented, the assembly scripts end up looking for the rootfiles in the group.group.group folder.

There are a few workarounds to this problem. One is to stick a mkdir in your customTarget/allElements assemble.<feature-id>.group.group.group target. This avoids the error, but you don't get the rootfiles in your group archive.

If you are using 3.4, then you can use the pre.archive target in customAssembly.xml to collect all the rootfiles into the correct folder:

   <target name="pre.archive">
      <!-- for each config being built -->
      <move file="${eclipse.base}/ANY.ANY.ANY/${collectingFolder}"
               todir="${rootFolder}" failonerror="false"/>
      <move file="${eclipse.base}/win32.win32.x86/${collectingFolder}"
               todir="${rootFolder}" failonerror="false" />
      <move file="${eclipse.base}/linux.gtk.x86/${collectingFolder}"
               todir="${rootFolder}" failonerror="false" />
   </target>

The ${rootFolder} property is defined by the caller of the pre.archive target, and in this case will be ${eclipse.base}/group.group.group/${collectingFolder}.

As usual, I have not actually tried running the above ant, the details may be different.

Sorting Bundles and Parallel Compilation in PDE/Build

In PDE/Build the compile order for bundles has always been based on the feature structure. Features are visited depth first, and for each feature the included bundles are sorted according to their dependencies. Dependencies outside the given feature are not considered, and must be included in a previously visited feature.

This can lead to some less than ideal feature structures as releng teams try to ensure that everything that a bundle depends on is included in a "deeper" feature.

This has been fixed for 3.5 M3. You can now define a property "flattenDependencies=true" in your build configuration build.properties file. This will result in bundles being sorted across feature boundaries.

Previously, bundles got compiled by delegation through the build.xml scripts for the containing features. When using the new flattenDependencies option, a new compilation xml script will be generated in the build directory. This only affects compilation, other build stages (ie gather.bin.parts) will still be delegated through the feature structure.

Parallel Compilation

With the above changes in compile order, it turns out to be a small step to get parallel compilation. Set both flattenDependencies and "parallelCompilation=true" in your build configuration. The result is that the compilation xml script will then group bundles using ant's parallel task. The result is something that looks something like this:

<target name="main">
  <parallel threadsPerProcessor="3">
     <ant antfile="build.xml" dir="plugins/org.eclipse.swt" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.swt.win32.win32.x86" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.osgi" target="build.jars"/>
  </parallel>
 
  <parallel threadsPerProcessor="3">
     <ant antfile="build.xml" dir="plugins/org.eclipse.osgi.util" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.transforms.xslt" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.supplement" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.simpleconfigurator" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.p2.jarprocessor" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.launcher" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.launcher.win32.win32.x86" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.common" target="build.jars"/>
  </parallel>
 
  <parallel threadsPerProcessor="3">
     <ant antfile="build.xml" dir="plugins/org.eclipse.update.configurator" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.equinox.frameworkadmin" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.cvs" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.core.runtime.compatibility.auth" target="build.jars"/>
     <ant antfile="build.xml" dir="plugins/org.eclipse.core.jobs" target="build.jars"/>
  </parallel>
....

Each group depends only only bundles that appeared in a previous group. You can control the ant threading attributes by setting parallelThreadCount and parallelThreadsPerProcessor.

We tested this by using it to compile the Eclipse SDK. Compile time dropped from 6:53 to 4:54, while this is only a 2 minute savings, it is a 29% improvement.