Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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

(→‎Getting the code)
(warn about git migration)
 
(6 intermediate revisions by 3 users not shown)
Line 2: Line 2:
  
 
== Getting the code ==
 
== Getting the code ==
−
# Get an eclipse 3.5 M4 build or higher (http://download.eclipse.org/eclipse/downloads/)
+
 
 +
'''The p2 sources are being moved to Git (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=345479]) – This information is partially outdated!'''
 +
 
 +
# 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
 
# 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'''
+
# Expand '''HEAD > org.eclipse.equinox > p2'''.
−
# Checkout "org.eclipse.equinox.p2.releng"
+
# 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
 
# 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".
 
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.<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.4 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. 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.  <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 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 ==
 
== Understanding the code ==
Line 23: Line 18:
 
* The [[Equinox p2 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.).
 +
 +
== 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:
 +
 +
<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 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.
 +
 +
# '''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
  
 +
# '''Publisher *''' This allows you to generate p2 metadata from various input
  
 
[[Category:Equinox p2|Getting Started for Developers]]
 
[[Category:Equinox p2|Getting Started for Developers]]

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
Retrieved from "https://wiki.eclipse.org/index.php?title=Equinox_p2_Getting_Started_for_Developers&oldid=263410"

This page was last modified 15:29, 1 August 2011 by Tobias Oberlies. Based on work by Pascal Rapicault, Susan F. McCourt and Pascal Rapicault and others.

Back to the top