Skip to main content
Jump to: navigation, search

Difference between revisions of "Equinox p2 Getting Started for Developers"

(warn about git migration)
 
(25 intermediate revisions by 6 users not shown)
Line 1: Line 1:
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 [[Equinox Provisioning Getting Started | getting started guide for users]].
+
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 [[Equinox p2 Getting Started | getting started guide for users]].
  
 
== Getting the code ==
 
== Getting the code ==
  
# Create a CVS repository location for ":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
+
'''The p2 sources are being moved to Git (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=345479]) – This information is partially outdated!'''
# 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".   
+
# Get the most recent 3.7 build available (http://download.eclipse.org/eclipse/downloads/)
 +
# Create a CVS repository location for ":pserver:anonymous@dev.eclipse.org:/cvsroot/rt". 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". Should you need to work on a maintenance stream (e.g. 3.6.x), you can find a branch of this project.
 +
# Import the "projectSet.psf" project set by right clicking on the file in the Package Explorer and clicking '''Import 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
  
== My first run ==
+
You will get a mess of projects added to you workspace and you are "good to go".
 
+
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.<br>After having checked out the code as described above, run the '''Metadata Generator SDK''' launch configuration in the '''OSGi Framework''' launch category. <br>'''Note:''' You may need to alter some of the arguments in the launch configuration's '''Arguments''' tab.  In particular, <br>* 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.<br>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.  <br>'''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, <br>* "-destination" is the location where you want the new Eclipse.  That is, where you can find eclipse executable etc. after the install.<br>* "-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 ==
 
== 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.
 
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 Provisioning Concepts]] document sets out much of the terminology for and relationships between the different elements of the Equinox provisioning system.
+
* 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
+
* 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.
 +
* Also it worth nothing that the code you check out contains two kinds of bundles. First are the runtime bundles (you will deploy a subset of those when you want to use p2 as a provisioning system, e.g. engine, director, etc.), second are the bundles related to tooling (e.g. publisher, metadata.generator, repo tools, etc.).
  
== Setting up self-hosting ==
+
== 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.
+
* Since 3.6 (Helios) PDE has introduced limited support for self-hosting p2. This means that on startup PDE will generate a profile from the set of bundles that you have selected. To enable this functionality, select the "Support software installation" option in the configuration tab of the launch configuration. Note though that this has some limitations and may not represent the reality of your deployed application to a 100%.
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 ===
+
* Another approach, useful when you want to work against an existing p2 profile, is to set the p2 data area of the launched workbench to point to the p2 directory of the profile that you want to debugThese arguments can be added to the launch configuration of your workbenchFor example, if the eclipse install you wish to work with is in "c:/testBuild" then your launch config arguments look like this:
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 installedNormally you would go to an update site and install the needed binary bundles or unzip an archive into your Eclipse installUnfortunately, 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 configurationThis will be the "real" IDE we use to do development.
+
<pre>
 +
-Declipse.p2.data.area=C:/testBuild/eclipse/p2/
 +
-Declipse.p2.profile=SDKProfile
 +
</pre>
 +
 
 +
It's not such a good idea to point the launch config at the host eclipse, since you could potentially trash your host profile while debugging new code.
 +
 
 +
== 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 pointTo 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.
  
=== Steps ===
+
# '''director app''' This allows you to run the director application, which is a headless way to install and uninstall using p2. http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_director.html
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".
+
# '''Publisher *''' This allows you to generate p2 metadata from various input
# 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 <code>start org.eclipse.equinox.prov.selfhosting</code>.  <br>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.
+
  
=== Hints/Tips ===
+
[[Category:Equinox p2|Getting Started for Developers]]
* 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
+

Latest revision as of 15:29, 1 August 2011

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

The p2 sources are being moved to Git (see [1]) – This information is partially outdated!

  1. Get the most recent 3.7 build available (http://download.eclipse.org/eclipse/downloads/)
  2. Create a CVS repository location for ":pserver:anonymous@dev.eclipse.org:/cvsroot/rt". Hint: Select the quoted text, open the CVS Repositories view, and select Paste Connection or hit Ctrl+V to add the connection
  3. Expand HEAD > org.eclipse.equinox > p2.
  4. Checkout "org.eclipse.equinox.p2.releng". Should you need to work on a maintenance stream (e.g. 3.6.x), you can find a branch of this project.
  5. Import the "projectSet.psf" project set by right clicking on the file in the Package Explorer and clicking Import 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".

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.
  • Also it worth nothing that the code you check out contains two kinds of bundles. First are the runtime bundles (you will deploy a subset of those when you want to use p2 as a provisioning system, e.g. engine, director, etc.), second are the bundles related to tooling (e.g. publisher, metadata.generator, repo tools, etc.).

Self hosting

  • Since 3.6 (Helios) PDE has introduced limited support for self-hosting p2. This means that on startup PDE will generate a profile from the set of bundles that you have selected. To enable this functionality, select the "Support software installation" option in the configuration tab of the launch configuration. Note though that this has some limitations and may not represent the reality of your deployed application to a 100%.
  • Another approach, useful when you want to work against an existing p2 profile, is to set the p2 data area of the launched workbench to point to the p2 directory of the profile that you want to debug. These arguments can be added to the launch configuration of your workbench. For example, if the eclipse install you wish to work with is in "c:/testBuild" then your launch config arguments look like this:
-Declipse.p2.data.area=C:/testBuild/eclipse/p2/
-Declipse.p2.profile=SDKProfile

It's not such a good idea to point the launch config at the host eclipse, since you could potentially trash your host profile while debugging new code.

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.

  1. director app This allows you to run the director application, which is a headless way to install and uninstall using p2. http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_director.html
  1. Publisher * This allows you to generate p2 metadata from various input

Back to the top