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. If you are actually looking to get started as an end-user of the provisioning facilities then check out the getting started guide for users.
Getting the code
- Create a CVS repository location for ":pserver:firstname.lastname@example.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
- Expand HEAD > equinox-incubator > provisioning
- Checkout "org.eclipse.equinox.prov.releng"
- Import the "projectSet.psf" project set using File > Import > Team Project Set in the releng project you just checked out. If you are a committer, and able to make an extssh connection, you can use projectSet-extssh.psf
You will get a mess of projects added to you workspace and you are "good to go".
My first run
Note that there are also a bunch of launch configurations that come in the various projects. We can't explain them all here but looking at the launch configs (and the code they run) is one interesting starting point. To get a feel for how things work the section below walks you through using a few of the launch configs to setup a working provisioning system.
- 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 arguments in the launch configuration's Arguments tab. In particular,
* the "-source" argument 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.
- Install profile Having run the generator you now have what is essentially an update site in its new form (i.e., the metadata and artifact repos). Unlike update sites, these repos contain everything you need to create an Eclipse install. The director app launch configuration can help you here.
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,
* "-destination" is the location where you want the new Eclipse. That is, where you can find eclipse executable etc. after the install.
* "-installIU" is the IU to install. For the simple case this is the same as the "root" specified during generation.
- Run profile Once the director has run, you can go to the destination folder you specified and find the eclipse executable. Run it. You should get a complete running Eclipse. Notice that the destination does not contain the plugins or features. Just a set of configuration files. In the new provisioning story the plugins etc. are stored in managed pool and shared between profiles.
Understanding the code
While it would be extremely hard to capture essence of all the different code areas here, we can give you a few starting points and places to look.
- The Equinox p2 Concepts document sets out much of the terminology for and relationships between the different elements of the Equinox provisioning system.
- ProvisioningHelper in the console bundle. This is a helper class that has lots of useful methods and is useful as an example of how to do various operations. Note that this class is currently not API and is sadly misplaced to be widely useful (in the console bundle?!), but overall, it is very educational.
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.
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.
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.
- 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".
- 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.
- 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.
- Using the console in LEFT (that is, the console opened when you ran MIDDLE), start the self-hosting bundle: type
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.
- 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.
- 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.
- 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.
- 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