Equinox/p2/Obsolete Docs/Proposals/Install Handler Proposal

W.I.P

Introduction

This page describes a proposal for adding support for a mechanism similar to the Update Manager's "Install Handler". See bug 257792 for discussion.

Background

When using Update Manager it is possible to write a plugin, that is packaged as a jar and included in a feature. The feature manifest is modified to refer to the jar, and the class that implements the install handler to use. Update Manager executes this handler as part of the installation after having set up an environment consisting of org.eclipse.core.runtime, org.eclipse.update.core, and optionally (unless running in the headless mode) org.eclipse.ui.

Requirements on an p2 equivalent service

• Does not have to be backwards compatible with UM's Install Handlers
• Does not replace the need to write a custom installer when different startup, splash-screens etc. are required.
• Should provide a mechanism to allow an IU to specify requirements on the installer configuration

Proposal

The provisioning of install handlers can be seen as a provisioning/update of the currently running installer. First, the resolution is computed. Once all the IU's to process are known, the requirements on the installer are collected. A new resolution is then performed against the installer/agent profile. When resolved, any new installation/update required in installer/agent is performed. Once processed, the install of the original plan proceeds. Any custom install instructions are performed on custom touchpoints.

Although this sound simple - there are many issues to overcome.

Issues

• Installing an IU into the agent profile can have an effect on the already calculated plan when agent profile and profile to install to is the same
• An install handler needs to be installed in all agents that perform operations on a profile repository where a bundle requiring an install handler is installed. (Install handler may have uninstall instructions, and the install location may be garbage collected). The install handler must be available locally as it would be bad to require a fetch from some remote meta data repository (which may not even exist when the user wants to uninstall some bundle).
• When an update of a bundle requires a newer version of the install handler both the old and the new version must be available to the agent.
• Attempt will probably be made to use different version of an installer against different versions of the p2 data area
• Currently, p2 can only have one running setup, and it is unclear if this setup can be stopped and restarted without side effects
• Describing and then act on install handlers depending on the type of installation - an example is an IH that sets a registry key - this is not wanted if the installation is performed for the purpose of packaging.

Solutions to issues

Structure

Here is a proposed structure for how the various parts are organized. It helps to have this explained first.

A separate .p2i area is not needed - update image and text.

• .p2 under user.home should have a version as it is not a good idea to try to run a mixture of installers/p2 versions in the same shared area - the version should reflect the meta data version/capabilities - so may not be 3.4, 3.5 etc
• .p2i is a shared area for installers - this area could be the same as the .p2 area if it is ok to mix the two. This area is also versioned
• Location A is a stand alone installation
  • It is a standard p2 based eclipse installation
  • It has an additional "installer" directory
  • The installer directory has a p2 installed director.app
  • The director app is headless (very small)
  • The director uses the same p2 data area as the eclipse installation location where it is "hosted"
  • The director has a profile name that is either in the "download style" (i.e,. Eclipse SDK installer) or in the "p2-installer style" (i.e. name reflects location).
• Location B is a shared installation
  • It is a standard "p2-installer style" shared Eclipse installation
  • It has an additional "installer" directory
  • The installer directory has a p2 installed director app
  • The director app is headless (very small)
  • The director uses the shared .p2i data area and has a profile that reflects its location

Scenarios

Have nothing

• User has nothing installed.
• User can download a zip, unzip and run - no p2 provisioning takes place
• User can install using an agent (p2-installer, director, a custom installer) - let's assume the p2-installer as it is used in the EPP Wizard
• If this is an install of the Eclipse SDK - then it would be a bad idea to not already have packaged required install handlers into the p2-installer
• If the p2-installer is used for a custom Eclipse, RCP application, or for any other type of "native" installation, the install may require install handlers

The trivial cases where the p2-installer just installs are not described. Here are the steps for an installation requiring install handlers.

An install into Standalone A:

• A p2 director is given a provisioning task - for "Stand Alone A" (in the previous figure).
• The profile is created
• A plan is created
• The plan is scanned for requirements on the installer
• As there are installer requirements a plan for the installer must be constructed
  • With the proposed layout, the second installer would always be installed using the same data area as the target and there is no need to switch. (If switching is required it becomes a lot more difficult).
  • It does not matter if the p2-installer is p2 based - it would typically not be a shared installation, and its location is not where we want to install install handlers.
• The installer now provision the secondary installer (director.app) (i.e. A/installer/director.app into the profile Ai) using the same data area as the stand alone A (which is not yet installed). The secondary installer is correctly configured to include the install handlers.
• The just provisioned installer is executed - it is told to not (again) install install handlers - and is given the original install parameters

An install into Shared B:

• The shared install is basically the same as the standalone - only using a different data area.
• Naturally, subsequent installation of secondary installers is much faster

Modifying an installation

Something already installed can be modified in different ways:

• It is an Eclipse or RCP app with a built in director
  • The user can use the UI and install new things
  • The director.app can be invoked from the command line to install new things
• A p2-installer could have been freshly downloaded with a configuration to install some add on
• The user could feed an already existing p2-installer with a set of properties to install some add on

There are again trivial cases:

• There are no IHs required by the provisioning plan
• The IHs required are already installed

TBD

With this approach:

• it does not matter if an external or embedded agent is running the install
• if the needed install handlers have already been installed in the agent the fork/exec is not needed. This can happen when i) the installer is a custom installer already prepared with the required install handlers, ii) an embedded agent (Eclipse SDK agent) has already installed the necessary install handler code in a previous run (example - the "registry key setter action" was required by a previously installed IU, and it is still there.
• the default xp2 profile should contain a minimum of things, and should be created using sharing
• It is the responsability of the publisher of an IU requiring an install handler to make sure it always installed into the profile where the IU requiring it is installed. (This to ensure an uninstall.).

Changing Data Area

The long term solution is to modify p2 to enable multiple instances. The current approach is based on services that are configured from system properties. Changing this is a major effort and touches on several hundred places in the code where services are being consumed.

A test where the exemplary setup bundle is stopped and restarted is currently being performed to see if this makes it possible to run provisioning tasks to different data areas sequentially. If not possible, the only option is to launch a new installer to address the issue.

The proposal works around this limitation by using the same data area for the installer as for the main install.

Access by all agents

There are many issues:

• The installer and the target can be for different platforms (e.g. a windows installer installing a linux installation)
• There is no way to install the install handler in all potential agents
• Agents may have different versions

A solution can consist of the following:

• When installing something that has its own director, it is enough to ensure that the install handlers are also installed - future provisioning operations using itself will work.
• An external agent will always need to figure out what it needs to be able to perform provisioning in a given profile - how it solves this is up to the particular agent implementation.

Changed premises for plan

There is no issue if the set of IU's being installed for "install handler" does not affect the original plan. This could be made to be a requirement when writing an install handler.

The real solution would be to re-plan after the install of the install handler if the agent profile is equal to the target profile.

Multiple versions required

From an engine perspective this will work fine, as touch points are registered with a name and a version. Need to discuss how this should work. Is it assumed that touchpoints implementations are backwards compatible? And if they are not, that the incompatible (newer) version is given a new name?

An alternative is to install the bundles required for the uninstall phase first, then remove them, and then install what is needed for the update/install phases.

Specifying the need for an install handler

Some options:

• The IU could have a second "required capabilities" section called "required installer capabilities"
• The IU could have one "required capability" specially marked as being for the "installer"
• The IU could use properties - referring to another IU that specifies the installer required capabilities (and a range).

Of these, the second options skews the plan when the agent is running in a separate profile. The first option is intrusive as it requires changes to meta data format, parsing, etc. Third option will not prevent agents that do not provide the install handler feature from attempting to install (and fail unless the appropriate touchpoints are there).,

Proposal: Use two properties

• org.equinoq.p2.installHandler.iu: <IU key>
• org.equinox.p2.installHandler.range: <version range>

Where o.e.p.iH.range can be an empty range.

Take 2

After some thought; meetings, and more thoughts...

External agent

An external agent such as the p2-installer is used to provision. The provisioning task is for a profile (Pa) in a data area (Da) installing to location (La). We decide to use a shared installation for install handlers in data area Di.