Equinox p2 Getting Started for Developers

So you are interested in the provisioning code. Great! There are several levels of involvement ranging from calling the API to contributing provisioning code. This page should help you understand how to do all of those.

Getting the code

1. Create a CVS repository connection to ":pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse". Hint: Select the quoted text, open the CVS Repositories view, and select "Paste Connection" or hit Ctrl+V to add the connection
2. Expand HEAD -> equinox-incubator > provisioning
3. Checkout org.eclipse.equinox.prov.releng
4. File > Import > Team Project Set. Select "projectSet.psf" in the releng project checked out above. If you are a committer, and able to make an extssh connection, you can use projectSet-extssh.psf

My first run, running the tests

The easiest way to get a feel for what is going on with the new code base is to run the tests.

1. Generate metadata/artifacts Until the new provisioning story is fully integrated into and delivered with Eclipse, you must add your features and plugins to artifact and metadata repositories before they are available to install. To help with this, we have created a metadata/artifact generator.
   After having checked out the code as described above, run the Metadata Generator SDK launch configuration in the OSGi Framework launch category.
   Note: You may need to alter some of the properties in the launch configuration's Arguments. In particular,
   * "-Declipse.prov.metadataGenerator.eclipseBase=" should point to the location of the Eclipse install you want to add to the repository. The metadata generator will scan this location and generate metadata and artifacts for all discovered features and plugins. For simplicity you can point at the Eclipse 3.3 install that you are currently running.
   When you run the launch configuration progress should be reported in the console. When generation is complete you can terminate the launch by typing "exit" in the console or killing the launch.
2. Install profile' Having generated the metadata and artifact repos, you can create and install a new "profile" by running the Test Director SDK launch configuration in the JUnit Plug-in Test launch configuration category.
   Note: Again, you may need to tweak some of the arguments based on how you generated the metadata (e.g., where the repositories got generated). In particular,
   * "-Declipse.prov.installFolder=" is the location for the new profile. This is where you can find eclipse executable etc. after the install.
   * "-Declipse.prov.autoInstall=" is the IU to install. For the simple case this is the same as the "eclipse.prov.rootIUId" specified during generation.
   Note: You can also run the metadata JUnit tests by running org.eclipse.equinox.prov.metadata.test.AllTests as a JUnit Plug-in Test.
3. Run profile Once the test has run you can go to the installFolder and find the eclipse executable and run it. You should get a complete running Eclipse. Notice that the installFolder does not contain the plugins or features. Just a mess of configuration files. In the new provisioning story the plugins etc. are stored in managed pool and shared between profiles.

Using the console

The org.eclipse.equinox.prov.console bundle adds some provisioning related commands to the standard OSGi console. You can see how this works using the Provisioning Console launch configuration. Type "help" on the console to get a list of available commands (hint: they all start with "prov").

Setting up self-hosting

Self-hosting is the act of running Eclipse from Eclipse typically using some of the bundles that are in projects in your workspace and some from your target platform. Most plug-in developers do this all the time and can continue doing so without any changes. However, developers who are working on the provisioning system or who are looking to call provisioning API from launched configurations will need to follow some additional steps. For those familiar with developing using Update Manager, this is conceptually similar to "Feature-based self-hosting". As with the initial steps related to metadata generation, the steps detailed here are only required until the provisioning team has a chance to work on the tooling and integrate the self-hosting support into the regular builds.

Overview

First you need an Eclipse IDE running that has the provisioning system and the self-hosting tooling. This is like saying that before you can develop C code you need to have CDT installed. Normally you would go to an update site and install the needed binary bundles or unzip an archive into your Eclipse install. Unfortunately, we are at an early stage and the provisioning infrastructure changes very rapidly so making binaries available likely turns out to be more challenging. So, instead, we'll make a workspace that has all the provisioning and self-hosting support loaded and than launch another Eclipse IDE that includes those projects/plug-ins in the launch configuration. This will be the "real" IDE we use to do development.

Steps

We tried to figure out good names for the different running Eclipse instances here but it turns out there are lots of pre-conceived notions around "target", "host", "dev", ... In the end just chose symbolic names that should not have too much embedded meaning.

1. Launch Eclipse and create a workspace that targets your current Eclipse SDK and has all of the projects from the provisioning .psf file checked out (see above). Let's call this workspace "LEFT".
2. Create an Eclipse launch configuration that includes all of the Eclipse SDK and the provisioning projects you just checked out. For fun, call that launch config "MIDDLE". Ensure that the -console command line argument is specified.
3. Run the launch configuration. MIDDLE is where you are going to do your real work so create/identify an appropriate workspace. Note that it is easiest to just set this workspace location in the launch configuration rather than using the workspace chooser.
4. Using the console in LEFT (that is, the console opened when you ran MIDDLE), start the self-hosting bundle: type start org.eclipse.equinox.prov.selfhosting.
   Note: that if you leave the "Clear configuration area" checkbox unchecked in MIDDLE's launch config, you actually only need to start the self-hosting bundle once. If you check the box, you have to start the self-hosting bundle every time you launch MIDDLE.
5. In MIDDLE's workspace, once again, check out all of the provisioning projects you need as well as your projects as appropriate and develop your application/code as normal.
6. When it comes time to run (i.e., self-host) you have to create an OSGi launch configuration (say "RIGHT") that includes the things you want to run and, for simplicity, all of the provisioning related projects. In practice you only need some of the provisioning projects but that list will change over time and is/will be detailed elsewhere.
7. Now when you run RIGHT, the provisioning self-hosting code in your IDE (MIDDLE) kicks in and generates metadata and modifies the launch being executed and hooks everything together. The net result is RIGHT will be running a Profile that has all the proper IUs installed and there will be a metadata repository containing IUs for all the plugins in your workspace and the associated target platform. These IUs can, for example, then be installed into RIGHT using the provisioning console or your application.

Hints/Tips

• You can leave LEFT running for a long time and simply minimize it.
• Consider changing the look of LEFT's workspace so you don't confuse its content with that of other workspaces. Perhaps just set the editor font large. It is also useful to run MIDDLE with -consolelog and -console.
• From time to time there will be a change in the provisioning code that will force you to shutdown RIGHT and MIDDLE and update the projects in LEFT's workspace. This typically happens when the metadata/artifact format/layout/location is changed in the provisioning code.
• TODO: Put more about locations to clear when things go bad and what to look for when repo files are not found etc