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
- Get an eclipse 3.4 M5 build or higher (http://download.eclipse.org/eclipse/downloads/)
- 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 > org.eclipse.equinox > p2
- Checkout "org.eclipse.equinox.p2.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.4 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. You now have two ways to run: One consist in running our Admin UI by starting the ProvAdminUI launch configuration. The Admin UI is a power tool for p2 developers and will allow you to install from the repository you just created. For an overview of this UI see the Equinox p2 Getting Started#Step 2 - Exploring the agent. The other consist in running the director app launch configuration.
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 your installation has completed, 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.