Skip to main content
Jump to: navigation, search

Difference between revisions of "Equinox/p2/Getting Started"

< Equinox‎ | p2
(Step 2 - Exploring the agent)
(Bundle pooling)
 
(109 intermediate revisions by 14 users not shown)
Line 1: Line 1:
__TOC__
+
As of Eclipse project build I20080305 (shortly before Eclipse 3.4/[[Ganymede]] M6), the Eclipse SDK contains a new provisioning system called [[Equinox/p2]]. p2 replaces Update Manager as a mechanism for managing your Eclipse install, searching for updates, and installing new functionality. This document will help you getting started with p2.  If you want to explore some of the capabilities of p2 that are not exposed to end users in the Eclipse SDK, see also [[Equinox_p2_Getting_Started_Admin_UI|Equinox/p2/Getting Started Admin UI]].
  
== Getting Started with Equinox Provisioning (M1) ==
+
== p2 user interface ==
  
What is the first thing that you would expect to do with some provisioning code - install something, of course! This section is to guide you through a happy-path using equinox provisioning to install an Eclipse SDK.
+
In the workbench, p2 replaces the '''Help > Software Updates''' menu entry from Update Manager. The resulting dialog shows the features that are installed, and the features that are available to install. You can add additional update sites by clicking '''Manage sites''' in the '''Available features''' pane.  Or, simply drag and drop a URL link in a browser to the '''Available features''' pane.  For example, dragging this link (http://download.eclipse.org/eclipse/testUpdates) will add the eclipse test updates site.  Select any set of available features and click '''Install''' to install them into the current running system.
  
There are four basic concepts that will help you understand the install:
+
[[Equinox/p2/Update UI Users Guide]] provides more information about how the UI works.
  
* '''Agent''' - the program that will perform the install. In general, the provisioning agent could appear in various forms - a standalone application, a silent install demon, a perspective in the ide. We will use the [[Equinox Provisioning Admin UI Users Guide | Admin UI application]] to do our install.
+
You must modify the p2 UI code if you want to [[Equinox/p2/Getting Started#Running the p2 UI from a self-hosted workbench|Run the p2 UI in a self-hosted workbench]].
* '''Metadata''' - the information about what can be installed. The metadata is used by the agent to analyze dependencies and perform the installation steps. Metadata lives in one or more repositories.
+
* '''Artifacts''' - the actual bits that will be installed. There are various kinds of artifacts that are processed differently during the install. Associated metadata determines how a given artifact is processed. Artifacts live in one or more repositories. The metadata and artifacts generally come from different repositories and may be widely distributed.
+
* '''Profile''' - in the most simple form, a profile is the location where the bits will be installed. The term 'profile' is not a very good term and probably will disappear from end user concepts (there's a bug about this), but it is the term we are using for now.
+
+
== Steps to Install an Eclipse SDK ==
+
  
This week we will be installing a 3.3 SDK, but at the end of 3.4M1 we will generate metadata for that and support that SDK instead or, better yet, as well. The current install is only supported for Windows but eventually we will build and test the other supported platforms.
+
== p2 basics ==
  
=== Step 1 - Exploring the agent ===
+
=== Disk layout ===
  
The agent is available from an eclipse download site [http://download.eclipse.org/eclipse/equinox/provisioning/builds/equinox-prov-agent-M1-win32.zip Admin application] - click the link and you should see (Firefox)
+
Before [[Equinox/p2|p2]], many Eclipse users circumvented Update Manager and installed new plug-ins by dumping them in the ''eclipse/plugins/'' directory and restarting with the -clean command line argument. There are many drawbacks to this "wild west" approach that we won't get into here, but suffice it to say that this approach to installation is not recommended. Although p2 will detect plug-ins added directly to the ''plugins'' folder (with an associated startup performance cost), alterations to plug-ins installed by p2 in this directory is '''not''' supported. If you manually remove a plug-in installed by p2, or attempt to replace with a different version, p2 will not detect it and may be broken. 
  
    [[Image:AgentDownload.jpg]]
+
The short rule of thumb is: if you added something manually, you can remove it manually. If you installed via p2, you should uninstall via p2. The shorter rule of thumb is: don't mess with the plugins folder if you can avoid it. p2 provides a new dropins folder that is much more powerful and allows separation of content managed by p2 from content managed by other means (described below).
  
The zip file is ~15 MB. You can download and '''unzip into the root of your C: drive''' (right, that's C:) or select Open with and '''copy into the root of your C: drive'''. At some point the Admin application will be or will have a bootstrap installer that allows you to choose where to install, but at the moment we have some embedded absolute paths. (Don't have a C: drive?  Sorry.)
+
When you install a p2-enabled Eclipse application, you will notice some new files and directories that didn't exist before. Here is a subset of a typical Eclipse install tree with some of this new content highlighted:
  
The result of this step is that you will have a directory C:\equinox.prov:
+
  eclipse/
 +
    configuration/
 +
      config.ini
 +
      '''org.eclipse.equinox.simpleconfigurator/'''
 +
        '''bundles.info'''
 +
    '''dropins/'''
 +
    features/
 +
    '''p2/'''
 +
    plugins/
 +
    eclipse.exe
 +
    eclipse.ini
 +
    ...
  
    [[Image:ProvDirectory.jpg]]
+
The file '''bundles.info''' contains a list of all the plug-ins installed in the current system.  On startup, all the plug-ins listed in this file are given to OSGi as the exact set of plug-ins to run with.
  
The meaning of the Flavor property is an advanced topic, so don't play with that unless you want to explore error conditions! In fact, once it has been set in a profile and something has been installed using that flavor, the Flavor property should be non-modifiable (bug).
+
Any extra plug-ins in the ''plugins'' directory or elsewhere are ignored. If you really want to force Eclipse to startup with a particular set of bundles installed, you could manually edit this file to have the contents you need. However, unless you're just hacking around or testing, editing this file is '''not recommended'''. However, it's useful to know about this file so you can see exactly what is installed in the system you are running. Typically, p2 is the interface between this file and the rest of the world. Clients initiate provisioning requests to p2 via API, the GUI or some of the facilities described below, and as a result p2 may install or uninstall bundles from the OSGi runtime by updating the bundles.info file.
  
=== Step 2 - Exploring the agent ===
+
The new '''dropins''' folder is where you can drop in extra plug-ins if you don't want to use the p2 user interface.  See the [[Equinox/p2/Getting_Started#Dropins|dropins]] section for more details.  For backwards compatibility, p2 will also detect extra plug-ins dropped into the ''plugins'' directory, and install any discovered bundles into the system.
  
Double-click on C:\equinox.prov\eclipse.exe and the Admin UI will come up looking like ''(resized to fit here)'':
+
Note that the above tree is just a sample layout of an Eclipse-based application. Very little of this structure is actually guaranteed to take this shape.  The configuration directory can be stored separately from the rest of the install using the -configuration command line argument.  The bundles and features may be in a shared [[Equinox/p2/Getting_Started#Bundle pooling|bundle pool]] elsewhere on disk. The eclipse.ini and eclipse.exe files may be branded with different names. The p2 directory may also be stored elsewhere when a single management agent is configuring multiple applications. In short, you should never write code that makes assumptions about the relative placement of files and directories in an Eclipse install.
  
    [[Image:AgentInitial.jpg]]
+
=== Dropins ===
  
Note that you see here all four concepts:
+
Provisioning operations should generally occur using the p2 UI, or by invoking [http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_director.html p2 tools] or APIs. However, there are situations where scripts need to install plugins and features via file system operations, and have the new content dynamically discovered by the system either at startup, or while running.  To support this kind of low-level manipulation of the system, p2 supports the notion of ''watched directories''. A watched directory is a  place where a user or script can drop files and have them discovered by p2. Various policies can be applied to watched directories to configure when they are checked for new content, and whether to eagerly install discovered content.
  
# Agent - the main window.
+
The Eclipse platform ships with a default watched directory called ''dropins''. The dropins folder is configured to be scanned during startup, and for changes to be immediately applied to the running system. Thus the dropins folder can be used much like the ''plugins'' directory was used in the past.  
# Metadata - the exposed '''Metadata Repositories''' view.
+
# Artifacts - the hidden '''Artifact Repositories''' view.
+
# Profiles - the '''Profiles''' view.
+
  
The Metadata Repositories view shows three repositories. Notice that the first two metadata repositories are squirreled away in agent data subdirectory of the configuration directory of the Admin UI rcp application on your machine. These two repositories are really an implementation detail that should be (and will eventually be) hidden from most users. The third repository is a site on org.eclipse.download where our metadata of interest lives.
+
A subtle twist on old behavior here is that plug-ins and features added to the ''dropins'' folder are properly installed into the system rather than being forced in. This means p2 has an opportunity to confirm that the new plug-in doesn't conflict with other installed plug-ins, and it can even go out and fetch any missing prerequisites of the newly dropped in plug-ins. This also means you can later use the GUI to install extra functionality that depends on the plug-ins in the ''dropins'' folder, since p2 knows about them and can reason about their dependencies. In other words, new plug-ins installed via the ''dropins'' folder behave exactly like plug-ins installed via the user interface. Note that updating plug-ins which are located under the ''dropins'' folder using the p2 UI will result in the updated plug-ins being saved under the main eclipse/plugins and eclipse/features folders and not under the ''dropins'' hierarchy as siblings to the older versions of the plug-ins, as might be expected.
  
The Profiles view shows the Equinox Provisioning UI profile which is profile defining the install location for the Admin UI app you are running. If you right click on the list item and  select properties, you will see some information about this profile:
+
==== Supported dropins formats ====
  
    [[Image:AgentProfileProperties.jpg]]
+
The dropins folder supports a variety of layouts, depending on the scale of your application and the desired degree of separation of its parts. The simplest layout is to just drop plug-ins in either jar or directory format directly into the dropins folder:
  
The meaning of the Flavor property is an advanced topic, so don't play with that unless you want to explore error conditions! In fact, once it has been set in a profile and something has been installed using that flavor, the Flavor property should be non-modifiable (bug).
+
  eclipse/
 +
    dropins/
 +
      org.eclipse.core.tools_1.4.0.200710121455.jar
 +
      org.eclipse.releng.tools_3.3.0.v20070412/
 +
        plugin.xml
 +
        tools.jar
 +
        ... etc ...
 +
    ...
  
If a Metadata repository or a Profile is not empty, then you can expand it to see the installable units (which are really installed units) in the profile. A preference is available to show only the installable units which are a Group; the default for this preference is true. Expanding to show the groups will give you something like this:
+
You can also drop in the traditional Eclipse application or extension layout directly in the dropins folder:
   
+
    [[Image:ExpandedInstallableUnits.jpg]]
+
  
Switching to the Artifact Repository tab and expanding will show:
+
  eclipse/
 +
    dropins/
 +
      eclipse/
 +
        features/
 +
        plugins/
  
    [[Image:Artifacts.jpg]]
+
If you have various different components being dropped in, and you want to keep them separate, you can add an additional layer of folders immediately below the dropins folder that contain traditional Eclipse extensions:
  
=== Step 3 - Creating a new profile ===
+
  eclipse/
 +
    dropins/
 +
      emf/
 +
        eclipse/
 +
          features/
 +
          plugins/
 +
      gef/
 +
        eclipse/
 +
          features/
 +
          plugins/
 +
      ... etc ...
  
You will need to decide where you want to install the SDK and create a profile for that location. In the profile view, right click and select 'Add a new profile':
+
Finally, you can add link files as in the traditional Eclipse links folder:
  
     [[Image:SelectNewProfile.jpg]]
+
  eclipse/
 +
     dropins/
 +
      emf.link
  
then fill in the appropriate data in the Profile properties dialog:
+
==== Debugging dropins ====
  
    [[Image:NewProfileDialog.jpg]]
+
If you are attempting to use dropins, but your bundles are not being found, first ensure <tt>org.eclipse.equinox.ds</tt> and <tt>org.eclipse.equinox.p2.reconciler.dropins</tt> are marked to auto-start.
  
=== Step 4 - Doing the install ===
+
Resolution errors with dropins are silently ignored.  To enable useful logging messages, place the following tracing options in your <tt>.options</tt> file:
 +
<source lang="text">
 +
org.eclipse.equinox.p2.core/debug=true
 +
org.eclipse.equinox.p2.core/reconciler=true
 +
</source>
 +
and then run with "<tt>-debug path/to/.options</tt>"
  
The '''sdk''' group is near the bottom of the list of group installable units in the repository ''http://download.eclipse.org/eclipse/equinox/provisioning/metadata/'' so scroll down until '''sdk''' is in view. The Admin UI supports two ways of initiating an install: 1). you can right click on the '''sdk''' group, select Install..., then choose the profile in the resulting popup dialog; or 2). you can drag&drop the '''sdk''' group onto the profile. Let's do d&d since it is easier (the little smudge over MyEclipseSDK is the drop cursor):
+
=== Bundle pooling ===
  
    [[Image:DropSDK.jpg]]
+
Prior to p2, each Eclipse application had its own private ''plugins'' directory where the application's software was kept.  This had the drawback that systems with two or more Eclipse-based applications installed ended up with significant duplication of software and other artifacts. Furthermore, the common pieces had to be upgraded separately for each application, often resulting in slow downloads of software already available elsewhere on the local system.
  
then click Yes on the resulting Install IU dialog:
+
To escape from this duplication problem, p2 natively supports the notion of bundle pooling. When using bundle pooling, multiple applications share a common ''plugins'' directory where their software is stored. There is no duplication of content, and no duplicated downloads when upgrading software. A Windows system configured to use bundle pooling would have a layout something like this:
  
     [[Image:ConfirmInstall.jpg]]
+
  Application1/
 +
     configuration/
 +
      config.ini
 +
      ... other configuration files for Application1...
 +
    Application1.exe
 +
    Application1.ini
 +
  Application2/
 +
    configuration/
 +
      config.ini
 +
      ... other configuration files for Application2...
 +
    Application2.exe
 +
    Application2.ini
 +
  ...
 +
  Documents and Settings
 +
    Username
 +
      .p2/
 +
        org/eclipse.equinox.p2.core
 +
        org/eclipse.equinox.p2.director
 +
        org/eclipse.equinox.p2.engine
 +
        org/eclipse.equinox.p2.touchpoint.eclipse
 +
          plugins/      <-- shared bundle pool
  
and boom, the install will start (assuming you have network connectivity org.eclipse.download, no firewall issues, etc):
+
With this layout, all the software is stored in a single ''plugins'' directory outside of the application install area. p2 takes care of ensuring that the bundles needed by the various applications in the system are present in the bundle pool.
  
    [[Image:InstallProgress.jpg]]
+
In Windows 7 SP1 Mars release the structure is more like the following.
 +
<pre>
 +
C:\Users\{user name}\.eclipse\org.eclipse.platform_4.5.0_1881578221_win32_win32_x86_64
 +
  configuration
 +
      .settings
 +
      org.eclipse.core.runtime
 +
      org.eclipse.e4.ui.css.swt.theme
 +
      .
 +
      .
 +
      . {10 more...}
 +
  features
 +
      org.eclipse.cdt.gdb_8.7.0.201506070905
 +
      org.eclipse.cdt.gnu.build_8.7.0.201506070905
 +
      org.eclipse.cdt.gnu.debug_8.7.0.201506070905
 +
      .
 +
      .
 +
      . {219 more...}
 +
  p2
 +
      org.eclipse.equinox.p2.core
 +
      org.eclipse.equinox.p2.engine
 +
      org.eclipse.equinox.p2.repository
 +
      pools.info
 +
      profiles.info
 +
  plugins
 +
      org.eclipse.cdt.core.win32.x86_64_5.3.0.201506070905
 +
      org.eclipse.epf.common.html_1.5.0.v20130128_0851
 +
      org.eclipse.epf.common_1.5.0.v20130128_0851
 +
      .
 +
      .
 +
      . {1,145 more...}
 +
  artifacts.xml
 +
</pre>
  
Anecdotally, the install takes slightly less time than the download of a corresponding Eclipse SDK zip (one datapoint: 21 minutes for equinox provisioning install vs. 23 minutes for download of the zip). The progress monitor gets stuck after reporting 'Collecting for xyzzy' for a few files (bug, sorry), but you can check on continued download progress by watching new files appear in C:\equinox.prov\plugins.
+
=== Installer ===
  
=== Step 5- After the install ===
+
There is now an [[Equinox/p2/Installer]] that will install the Eclipse project SDK. The installer supports both traditional standalone installs, and installs using [[Equinox/p2/Getting Started#Bundle pooling|bundle pooling]].
  
The install will finish with a whimper, not a bang, as the progress dialog disappears and the new profile you created is populated with the groups and installable units that are now installed into the profile:
+
== Running the p2 UI from a self-hosted workbench ==
  
    [[Image:AgentPostInstall.jpg]]
+
We do not yet support a properly configured, self-hosted p2 system (see {{bug|224658}}). This means that if you run a self-hosted workbench, the launched Eclipse will not be p2 aware.  The p2 UI will notice this and tell you that it cannot open. 
  
The directory you chose for your profile location will look like this, before running the eclipse you just installed:
+
If your desire is simply to develop or otherwise play with the new UI, and you don't care that the self hosted workbench is not provisioned, you can load the '''org.eclipse.equinox.p2.ui.sdk''' project and change  this code in '''ProvSDKUIActivator'''.
  
    [[Image:InstalledSDK.jpg]]
+
  ProvSDKUIActivator.ANY_PROFILE = true;
  
== See also ==
+
This will allow you launch the UI, but please note that the UI will be operating on the installation profile of the '''host workbench'''.
  
If you encounter bugs, or would like to enter enhancement requests for this work, please use the Equinox Incubator category in [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Equinox Bugzilla].  You can add the prefix "[prov]" to the subject line of the bug report to help us with bug triage.
+
== Interaction with legacy Update Manager ==
  
For more detailed information, visit one or more of the following pages  ==
+
In Eclipse platform version 3.4, the old Update Manager still exists under the covers for backwards compatibility. You can even re-enable the old Update user interface by enabling the "Classic Update" capability on the General > Capabilities preference page.
  
* [[Equinox Provisioning Admin UI Users Guide]] For folks who want experiment with the equinox capabilities for installing, updating, fixing, and uninstalling capabilities.
+
However, users will rarely have a need for enabling Update Manager, because p2 is able to install from any update site that was designed for Update Manager.  Add the update site you want to use by dragging a URL from a browser into the '''Available Features''' page in the '''Help > Software Updates ''' dialog.  The features from that site will be added to the available features list, and from there you can install them into the system.
* [[Equinox Provisioning Console Users Guide]] For OSGI geeks who enjoy starting and stopping bundles.
+
* [[Equinox Provisioning Getting Started for Developers]] For developers who want to create applications that extend or exploit equinox provisioning.
+
  
[[Category:Provisioning|Getting Started]]
+
=== Links Folder ===
[[Category:Equinox|Provisioning]]
+
 
 +
Update Manager supported the notion of an eclipse/links folder, where *.link files could be dropped in to connect extensions to an Eclipse-based application. For backwards compatibility the links folder is supported by p2 with the same behavior. This is really just a subset of the functionality available in the [[Equinox/p2/Getting Started#Dropins|Dropins]] folder.
 +
 
 +
== Removing p2 ==
 +
[[Equinox/p2/Removal]] describes the steps to completely remove p2 from the platform and revert to using the original Eclipse Update Manager.  In addition, for Eclipse project 3.4 builds, there is a link on the right hand side of the download page called "Eclipse Classic Update Manager". This gives a link to a script that can be used to remove p2 from any Eclipse SDK, platform binary, or platform SDK build.
 +
 
 +
Removing p2 from the Eclipse SDK is no longer supported in [[Galileo]] (3.5) or later. However, the platform itself is not tied to any particular provisioning technology, so applications are free to choose an alternative provisioning system (or none) depending on their requirements.
 +
 
 +
[[Category:Equinox p2|Getting Started]]

Latest revision as of 17:06, 10 September 2015

As of Eclipse project build I20080305 (shortly before Eclipse 3.4/Ganymede M6), the Eclipse SDK contains a new provisioning system called Equinox/p2. p2 replaces Update Manager as a mechanism for managing your Eclipse install, searching for updates, and installing new functionality. This document will help you getting started with p2. If you want to explore some of the capabilities of p2 that are not exposed to end users in the Eclipse SDK, see also Equinox/p2/Getting Started Admin UI.

p2 user interface

In the workbench, p2 replaces the Help > Software Updates menu entry from Update Manager. The resulting dialog shows the features that are installed, and the features that are available to install. You can add additional update sites by clicking Manage sites in the Available features pane. Or, simply drag and drop a URL link in a browser to the Available features pane. For example, dragging this link (http://download.eclipse.org/eclipse/testUpdates) will add the eclipse test updates site. Select any set of available features and click Install to install them into the current running system.

Equinox/p2/Update UI Users Guide provides more information about how the UI works.

You must modify the p2 UI code if you want to Run the p2 UI in a self-hosted workbench.

p2 basics

Disk layout

Before p2, many Eclipse users circumvented Update Manager and installed new plug-ins by dumping them in the eclipse/plugins/ directory and restarting with the -clean command line argument. There are many drawbacks to this "wild west" approach that we won't get into here, but suffice it to say that this approach to installation is not recommended. Although p2 will detect plug-ins added directly to the plugins folder (with an associated startup performance cost), alterations to plug-ins installed by p2 in this directory is not supported. If you manually remove a plug-in installed by p2, or attempt to replace with a different version, p2 will not detect it and may be broken.

The short rule of thumb is: if you added something manually, you can remove it manually. If you installed via p2, you should uninstall via p2. The shorter rule of thumb is: don't mess with the plugins folder if you can avoid it. p2 provides a new dropins folder that is much more powerful and allows separation of content managed by p2 from content managed by other means (described below).

When you install a p2-enabled Eclipse application, you will notice some new files and directories that didn't exist before. Here is a subset of a typical Eclipse install tree with some of this new content highlighted:

 eclipse/
   configuration/
     config.ini
     org.eclipse.equinox.simpleconfigurator/
       bundles.info
   dropins/
   features/
   p2/
   plugins/
   eclipse.exe
   eclipse.ini
   ...

The file bundles.info contains a list of all the plug-ins installed in the current system. On startup, all the plug-ins listed in this file are given to OSGi as the exact set of plug-ins to run with.

Any extra plug-ins in the plugins directory or elsewhere are ignored. If you really want to force Eclipse to startup with a particular set of bundles installed, you could manually edit this file to have the contents you need. However, unless you're just hacking around or testing, editing this file is not recommended. However, it's useful to know about this file so you can see exactly what is installed in the system you are running. Typically, p2 is the interface between this file and the rest of the world. Clients initiate provisioning requests to p2 via API, the GUI or some of the facilities described below, and as a result p2 may install or uninstall bundles from the OSGi runtime by updating the bundles.info file.

The new dropins folder is where you can drop in extra plug-ins if you don't want to use the p2 user interface. See the dropins section for more details. For backwards compatibility, p2 will also detect extra plug-ins dropped into the plugins directory, and install any discovered bundles into the system.

Note that the above tree is just a sample layout of an Eclipse-based application. Very little of this structure is actually guaranteed to take this shape. The configuration directory can be stored separately from the rest of the install using the -configuration command line argument. The bundles and features may be in a shared bundle pool elsewhere on disk. The eclipse.ini and eclipse.exe files may be branded with different names. The p2 directory may also be stored elsewhere when a single management agent is configuring multiple applications. In short, you should never write code that makes assumptions about the relative placement of files and directories in an Eclipse install.

Dropins

Provisioning operations should generally occur using the p2 UI, or by invoking p2 tools or APIs. However, there are situations where scripts need to install plugins and features via file system operations, and have the new content dynamically discovered by the system either at startup, or while running. To support this kind of low-level manipulation of the system, p2 supports the notion of watched directories. A watched directory is a place where a user or script can drop files and have them discovered by p2. Various policies can be applied to watched directories to configure when they are checked for new content, and whether to eagerly install discovered content.

The Eclipse platform ships with a default watched directory called dropins. The dropins folder is configured to be scanned during startup, and for changes to be immediately applied to the running system. Thus the dropins folder can be used much like the plugins directory was used in the past.

A subtle twist on old behavior here is that plug-ins and features added to the dropins folder are properly installed into the system rather than being forced in. This means p2 has an opportunity to confirm that the new plug-in doesn't conflict with other installed plug-ins, and it can even go out and fetch any missing prerequisites of the newly dropped in plug-ins. This also means you can later use the GUI to install extra functionality that depends on the plug-ins in the dropins folder, since p2 knows about them and can reason about their dependencies. In other words, new plug-ins installed via the dropins folder behave exactly like plug-ins installed via the user interface. Note that updating plug-ins which are located under the dropins folder using the p2 UI will result in the updated plug-ins being saved under the main eclipse/plugins and eclipse/features folders and not under the dropins hierarchy as siblings to the older versions of the plug-ins, as might be expected.

Supported dropins formats

The dropins folder supports a variety of layouts, depending on the scale of your application and the desired degree of separation of its parts. The simplest layout is to just drop plug-ins in either jar or directory format directly into the dropins folder:

 eclipse/
   dropins/
     org.eclipse.core.tools_1.4.0.200710121455.jar
     org.eclipse.releng.tools_3.3.0.v20070412/
       plugin.xml
       tools.jar
       ... etc ...
   ...

You can also drop in the traditional Eclipse application or extension layout directly in the dropins folder:

 eclipse/
   dropins/
     eclipse/
       features/
       plugins/

If you have various different components being dropped in, and you want to keep them separate, you can add an additional layer of folders immediately below the dropins folder that contain traditional Eclipse extensions:

 eclipse/
   dropins/
     emf/
       eclipse/
         features/
         plugins/
     gef/
       eclipse/
         features/
         plugins/
     ... etc ...

Finally, you can add link files as in the traditional Eclipse links folder:

 eclipse/
   dropins/
     emf.link

Debugging dropins

If you are attempting to use dropins, but your bundles are not being found, first ensure org.eclipse.equinox.ds and org.eclipse.equinox.p2.reconciler.dropins are marked to auto-start.

Resolution errors with dropins are silently ignored. To enable useful logging messages, place the following tracing options in your .options file:

org.eclipse.equinox.p2.core/debug=true
org.eclipse.equinox.p2.core/reconciler=true

and then run with "-debug path/to/.options"

Bundle pooling

Prior to p2, each Eclipse application had its own private plugins directory where the application's software was kept. This had the drawback that systems with two or more Eclipse-based applications installed ended up with significant duplication of software and other artifacts. Furthermore, the common pieces had to be upgraded separately for each application, often resulting in slow downloads of software already available elsewhere on the local system.

To escape from this duplication problem, p2 natively supports the notion of bundle pooling. When using bundle pooling, multiple applications share a common plugins directory where their software is stored. There is no duplication of content, and no duplicated downloads when upgrading software. A Windows system configured to use bundle pooling would have a layout something like this:

 Application1/
   configuration/
     config.ini
     ... other configuration files for Application1...
   Application1.exe
   Application1.ini
 Application2/
   configuration/
     config.ini
     ... other configuration files for Application2...
   Application2.exe
   Application2.ini
 ...
 Documents and Settings
   Username
     .p2/
       org/eclipse.equinox.p2.core
       org/eclipse.equinox.p2.director
       org/eclipse.equinox.p2.engine
       org/eclipse.equinox.p2.touchpoint.eclipse
         plugins/      <-- shared bundle pool

With this layout, all the software is stored in a single plugins directory outside of the application install area. p2 takes care of ensuring that the bundles needed by the various applications in the system are present in the bundle pool.

In Windows 7 SP1 Mars release the structure is more like the following.

C:\Users\{user name}\.eclipse\org.eclipse.platform_4.5.0_1881578221_win32_win32_x86_64
   configuration
      .settings
      org.eclipse.core.runtime
      org.eclipse.e4.ui.css.swt.theme
      .
      .
      . {10 more...}
   features
      org.eclipse.cdt.gdb_8.7.0.201506070905
      org.eclipse.cdt.gnu.build_8.7.0.201506070905
      org.eclipse.cdt.gnu.debug_8.7.0.201506070905
      .
      .
      . {219 more...}
   p2
      org.eclipse.equinox.p2.core
      org.eclipse.equinox.p2.engine
      org.eclipse.equinox.p2.repository
      pools.info
      profiles.info
   plugins
      org.eclipse.cdt.core.win32.x86_64_5.3.0.201506070905
      org.eclipse.epf.common.html_1.5.0.v20130128_0851
      org.eclipse.epf.common_1.5.0.v20130128_0851
      .
      .
      . {1,145 more...}
   artifacts.xml

Installer

There is now an Equinox/p2/Installer that will install the Eclipse project SDK. The installer supports both traditional standalone installs, and installs using bundle pooling.

Running the p2 UI from a self-hosted workbench

We do not yet support a properly configured, self-hosted p2 system (see bug 224658). This means that if you run a self-hosted workbench, the launched Eclipse will not be p2 aware. The p2 UI will notice this and tell you that it cannot open.

If your desire is simply to develop or otherwise play with the new UI, and you don't care that the self hosted workbench is not provisioned, you can load the org.eclipse.equinox.p2.ui.sdk project and change this code in ProvSDKUIActivator.

 ProvSDKUIActivator.ANY_PROFILE = true;

This will allow you launch the UI, but please note that the UI will be operating on the installation profile of the host workbench.

Interaction with legacy Update Manager

In Eclipse platform version 3.4, the old Update Manager still exists under the covers for backwards compatibility. You can even re-enable the old Update user interface by enabling the "Classic Update" capability on the General > Capabilities preference page.

However, users will rarely have a need for enabling Update Manager, because p2 is able to install from any update site that was designed for Update Manager. Add the update site you want to use by dragging a URL from a browser into the Available Features page in the Help > Software Updates dialog. The features from that site will be added to the available features list, and from there you can install them into the system.

Links Folder

Update Manager supported the notion of an eclipse/links folder, where *.link files could be dropped in to connect extensions to an Eclipse-based application. For backwards compatibility the links folder is supported by p2 with the same behavior. This is really just a subset of the functionality available in the Dropins folder.

Removing p2

Equinox/p2/Removal describes the steps to completely remove p2 from the platform and revert to using the original Eclipse Update Manager. In addition, for Eclipse project 3.4 builds, there is a link on the right hand side of the download page called "Eclipse Classic Update Manager". This gives a link to a script that can be used to remove p2 from any Eclipse SDK, platform binary, or platform SDK build.

Removing p2 from the Eclipse SDK is no longer supported in Galileo (3.5) or later. However, the platform itself is not tied to any particular provisioning technology, so applications are free to choose an alternative provisioning system (or none) depending on their requirements.

Back to the top