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"

< Equinox‎ | p2
(Installer)
(Interaction with legacy Update Manager)
Line 77: Line 77:
  
 
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.
 
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 p2 Removal]] describes the steps to completely remove p2 from the platform and revert to using the original Eclipse Update Manager.
  
 
[[Category:Equinox p2|Getting Started]]
 
[[Category:Equinox p2|Getting Started]]

Revision as of 19:44, 19 March 2008

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://update.eclipse.org/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.

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 p2 does not have this promiscuous behavior of attempting to install every plug-in it can get its hands on. By contrast, p2 employs a much simpler, more predictable, and ultimately much more flexible startup routine.

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 will be included. 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.

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.

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.

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.

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.

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.

Equinox p2 Removal describes the steps to completely remove p2 from the platform and revert to using the original Eclipse Update Manager.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.