Jump to: navigation, search

Difference between revisions of "Equinox/p2/Obsolete Docs/Proposals/Install Handler Proposal"

< Equinox‎ | p2
m
Line 10: Line 10:
 
The feature manifest is modified to refer to the jar, and the class that implements the install handler to use.
 
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.  
 
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==
+
==Requirements on a p2 equivalent service==
 
* Does not have to be backwards compatible with UM's Install Handlers
 
* 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.
 
* Does not replace the need to write a custom installer when different startup, splash-screens etc. are required.

Revision as of 06:12, 14 February 2009

W.I.P

Introduction

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

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 a 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

And - as discovered when elaborating on the solution:

  • Should handle version differences between local existing meta data, the version of an installer, and the version of what is being provisioned. At least to the degree that a user would not be able to destroy an exiting installation, or install a combination that later will be unable to update itself.

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. (Typically a newer installer will be used to install an older app, and attempts will be made to upgrade using both older and newer installations).
  • Currently, p2 can only have one running setup, but an experiment shows that it is possible to stop and start p2 services to enable a series of provisioning actions to take place - this is fine, but services where not designed to handle this, and multithreaded use can produce surprises.
  • Acting 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

After several iterations and attempts to work around limitations and issues - here is the final proposal.

Considerations:

  • Should be implementable within the 3.5 timeframe
  • Should handle first install as well as updates
  • Should handle Eclipse SDK, as well as "other apps"
  • Should handle provisioning of "anything" - what is installed is not a java application

Main Idea: Use a primary/bootstrap and a secondary installer. The "primary/bootstrap" installer is what gets downloaded by users (like the current p2-installer). The primary installer's main task is to install the secondary installer and hand the installation work over to the second installer.

The second installer can be as complex as the publisher wants - the only requirements is that it has a "secondary installer API" that enables the primary installer to hand over the task. More specifically, the secondary installer can be as complex as the entire Eclipse SDK - the secondary installer in this case can be the embedded director.app.

The primary installer is restricted in that it does not handle install handlers - this task is performed by the secondary installer.

Primary to Secondary API

The primary installer can be used to either perform a new install, or to modify an existing installation. In the "new install" case, the primary installer must be given information about how to set up the profile and where to install the secondary installer. In the "update existing" case, the primary installer needs to find this information in what is already installed.

The Profile

Properties in the profile should define how to start the secondary installer.

  • o.e.e.p2.secondary.launcher - defines a secondary launcher name. If property is missing it defaults to the product's launcher
  • o.e.e.p2.secondary.app - defines the application name (can default to "director.app" if missing).
  • o.e.e.p2.secondary.installLocation - a directory path (if different than the product's install location)

Parameters to the secondary installer should be passed via a single command line argument - a URI to a properties file (which in most cases can be the same properties file as being used to drive the primary installer).

The Installer.properties

The installer.properties should be expanded to include the following:

  • o.e.e.p2.secondary.rootId - the UI rootId for the secondary installer
  • o.e.e.p2.secondary.launcher - if different than the primary launcher
  • o.e.e.p2.secondary.secondary.app - the application name for the secondary installer
  • o.e.e.p2.secondary.relativeLocation - a path relative to the install location where the secondary installer should be installed (optional)
  • o.e.e.p2.p2DataAreaVersion - a requirement on the primary installer - (see below)
  • o.e.e.p2.secondary.mode - how feedback is provided to the user (see below)

p2DataAreaVersion
This property is required as it is otherwise impossible to know if the primary installer instance is capable of producing a "compatible p2 container" for what it is installing. A primary installer may have backwards compatibility and needs to know which version it should use when writing a new data area and profile. This property also prevents a user mistake where the wrong primary installer is selected. If the primary installer is not capable of satisfying the request it can simply give up and tell the user to get the correct version.

In addition to this, a p2 data area should contain meta data that states its version.

Example of issues. A 3.n version is used to create shared installations, and later a 3.n+1 version tries to install shared. The product to install requires that it supports 3.n+1. Currently, (best case) some p2 service would detect that the meta data it tries to read is of the wrong version, and worst case is that the newer version writes something that existing installed versions does not understand.

The issue arises since there is a requirement on the "container" when something that manages itself is installed. When standalone installations are made, the secondary installer could perform an upgrade of the data area, but in a shared scenario this becomes very difficult.

Ideally, the IU's being installed should declare their requirements on the container they are installed into. This information is however obtained too late since the profile is needed at the very beginning of the installation.

mode
When the primary hands over to the secondary installer, this property tells the secondary how progress and feedback to the user should be handled. It could define something like "headless" or "ui", where "headless" means that ui should not be loaded, no ui progress monitor, and no ui for explaining errors. The "ui" mode means that the secondary installer is responsible for providing the ui (if it has any).

A third alternative mode is that the secondary installer reports progress to the primary using a socket. Such a progress monitor implementation is available in buckminster.

FAQ Primary/Secondary

Why the separation on primary and secondary?
Primarily [sic] it provides a separation of concerns - the primary installer has one task - to install the secondary installer in a p2 container of a specified version. It uses a defined set of protocols, and does not support install handlers.

Why not let the primary also handle install handlers?
The main reason is that the p2, once started, is tied to one p2 data area. Although experiments have shown that it is possible to stop all p2 services and restart them on a different area, and thus making it possible to run a sequence of provisioning jobs, the services where not designed to be used this way, and code that makes use of the services may break. This is important, since if the primary installer should update itself to include everything that is needed to carry out a complex installation it would need to a) first calculate the plan for the thing to install, b) detect if this plan needs special install handling - to do a) and b) it needs to run against the target p2 data area. It would then c) need to switch back to its own data area to d) install the missing bundles detected in b). Once it has updated itself, it must again switch to the target data area and e) execute the plan to install into the target.

Having done all of the above, continued operations (by a user) requires that the install handlers are also available in the target (since it is self managed). All the work to get the install handlers into the primary installer is thus wasted effort.

Install Handlers

The install handler issue is now much easier to handle. The secondary installer (i.e. director) does the following:

  • a) create the plan for target install
  • b) creates an install handler plan based on the requirements on installer from the plan in a)
  • c) if the plan in b) is empty, everything required is already in place (skip to step e), if not, the plan from b) is executed
  • d) a new plan for the target install must be computed as the installation of the installer requirements in c) may have an effect on the plan from a)
  • e) the target plan (from a, (or d)) is executed.

The director always does this. It does not matter if it was given instructions from a user in a "self managed ui", or from a primary installer.