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

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.

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.

Install into new profile - no IH required

• A p2 director is given a provisioning task - for a profile (Pa) in a data area (Da) installing to location (La).
• The profile is created
• A plan is created
• The plan is scanned for requirements on the installer
• As there are no installer requirements, the plan is executed.

Install into new profile - IH required

As above until final step

• As there are installer requirements a plan for the installer must be constructed - there are two scenarios depending on if the installer is p2 based or not
  • if p2 based and it is not possible to switch the p2 setup - the original setup (for the installer) is lost as p2 must have been started for (Pa,Da,La) to create the original plan.
  • If not p2 based, there is no profile to use for the install handler plan creation - it would need to compare required capabilities against what is currently running (which is assumed to not work).

• if switching is possible the installer should always be p2 based, and should remember its original settings to enable provisioning into its own profile.
  • A switch is made to Di, a profile Pb is created named after La, and a location Lb is selected by the installer
  • The installer provisions a correctly configured installer to the installer profile
  • The just provisioned installer is executed - it is told to not (again) install install handlers

• if switching is not possible - it gets a bit complicated:
  • the installer is started for Pa,Da,La) and we do not want to install an installer there - a second instance of the installer must be used for this
  • the second installer installs the appropriately configured installer (as in the scenario above) and then executes it

1. Unless the agent has a property set that blocks instal handler installs - the plan is scanned for IU's that have a reference to install handler IU's. A list of install handler IUs is produced.
2. The engine checks if these IU's are already installed in the currently used profile (perhaps by creating a plan). If no install handlers needs to be provisioned, execute the plan and work is done.
3. An "external agent profile" xp2 is created and is provisioned to contain a minimal agent as well as the install handler IUs from step 2.
4. The original provisioning task to x is bequested from xp2. A property (block install handler install) must be set (see step 2) to avoid unnecessary work (or recursion at worst).
5. A fork is made and the xp2 profile is executed
6. The spawning agent waits /watchdogs the execution performed by xp2 so it can report on success/faliure
7. Done.

With this approach:

1. it does not matter if an external or embedded agent is running the install
2. 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.
3. the default xp2 profile should contain a minimum of things, and should be created using sharing
4. 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.).