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/Obsolete Docs/Proposals/Install Handler Proposal"

< Equinox‎ | p2
(The Installer.properties)
(The Installer.properties)
Line 67: Line 67:
 
* o.e.e.p2.p2Version - a requirement on the primary installer - (see below)
 
* o.e.e.p2.p2Version - a requirement on the primary installer - (see below)
 
* o.e.e.p2.secondary.mode - how feedback is provided to the user (see below)
 
* o.e.e.p2.secondary.mode - how feedback is provided to the user (see below)
 +
 +
'''p2Version'''
 +
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 the
  
 
==Solution using Profiles==
 
==Solution using Profiles==

Revision as of 16:13, 12 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 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

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 an Eclipse SDK.

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 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.p2Version - a requirement on the primary installer - (see below)
  • o.e.e.p2.secondary.mode - how feedback is provided to the user (see below)

p2Version 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 the

Solution using Profiles

Structure

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

  • .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 "shared installation - capability" that an installer like p2 is using.
  • 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 "secondary installer"
    • The "secondary installer is basically a the very small headless director app.
    • The "secondary installer uses the same p2 data area as the eclipse installation location where it is "hosted"
    • The secondary installer has a profile name that is either in the "download style" (i.e,. EclipseSDKInstaller) 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 secondary installer
    • The secondary installer uses the shared .p2 data area and has a profile that reflects its location

Scenarios

User has nothing installed

  • User can download a zip, unzip and run - currently no p2 provisioning takes place (which makes it impossible to use install handlers to add a registry key).
  • 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 force the p2 instance 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 provisions 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
    • if the target has its own director (i.e. it is self updating) the install handlers should also be installed in the target (this is the responsibility of the publisher as the installer is not aware of if the installation is "self managed" or not.)

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

Provisioning steps

  • Setup:
    • As the profile already exists, and the installer profile's name is derived from the target profile, it is a trivial task to find the installer profile
    • As the installer location is derived from the target location - it is also trivially obtained
    • As the data area is the same, there is nothing special needed
  • As in the virgin install - the requirements on the installer are obtained from the original plan
  • The installer plan is created and the installer profile is updated
  • The installer is then executed to perform the install

Uninstalling

When uninstalling, already installed install handlers may no longer be needed. This can be solved by:

  • ignoring the issue - the install handlers are probably not that big
  • scanning the target profile for Install Handlers - collecting everything required, and then uninstalling from the installer profile what is no longer needed.
  • the install handlers in the target can trivially be uninstalled in all cases

Suggest using the "ignore this" in the first implementation.

Agents for different platforms

It is possible to perform an installation for another platform than the current. This has several implications:

  • A shared install causes no problems - it would be a very odd to use a shared installation when doing a cross platform install, the content of the install location is not worth much without the shared location - which is user specific and always for the users platform.
  • In a stand alone install, the profile is created for the cross platform, but an installer profile must be created for the provisioning platform (so the secondary installer can run).
  • It may also be required that the secondary installer is provisioned for the cross platform.

A first implementation could ignore all this, and just let the installer create the secondary installer profile as described earlier. The fact that it is not for the cross platform becomes an issue when used on the cross platform. Since the case can be considered to be somewhat special - it is probably ok to let the user fix the installation manually by a) dropping the "alien" installer install and b) provisioning the wanted installer c) first provision the cross platform installer to a suitable location, and then use that to provision the cross platform installation.

Support for this could be added by checking if installer is a different platform than the target, and if so, name the secondary installer profile differently. A search for a secondary installer would know how to find the appropriate profile. Perhaps by having multiple entries in the target profile.

The "secondary installer"

The secondary installer can be a small headless packaging of the director app. To enable progress monitoring it is proposed that an additional -monitor <portnumber> parameter is passed to the secondary installer. The first installer opens this port (or "stdout") and sets up a monitor that reacts to data from the secondary process.

p2 "container" version handling

A provision action takes place in a "p2 container" (for lack of better term) and there is currently no mechanisms to deal with the issues. As an example a 3.n SDK is provisioned by a 3.n+1 p2, or an update is wanted of an existing 3.n SDK to a 3.n+1 SDK.

Currently if provisioning is performed to a "p2 container" that is not compatible - it will at best stop with an error when the provisioning takes place. At worst it will write data in a format that causes other users of the same container to crash or add information that in itself will be impossible to use by some clients (e.g. references to repositories using features that are not supported by all container clients), and thus causing them to crash.

To be continued....

Delaying Install Actions

As noted earlier, some install instructions are not wanted when using provisioning for the purpose of packaging, in cross platform scenarios, or when installing into a shared environment. In all these cases the final step of installation can not be performed until the actual user is using it in the environment where it is supposed to be used (e.g. the registry key case).

This could be supported by having an extra phase that is run when the provisioned target is started. An extra option is needed to the director to be able to control if this phase is included or not.

The addition of an extra phase which execution is bequested to startup of the target can be dealt with separately, it does not have a direct effect on the rest of this proposal although they are related. There is one particular scenario that is tricky to handle; a non self managed RCP app requiring running bequested install handlers. In this case, the bequest would have to go to the secondary installer and the bequesting mechanism would have to be done without p2 involvement (i.e. during the startup of the RCP application it has to be detected that there are bequests, and it must then invoke the secondary installer).

It could also be argued that any post-installation actions like this could just be handled by the application itself.

Options

By storing information in the target profile that describes where the installer profile and data area is, it is possible to decouple the two and have the secondary installer be installed in arbitrary fashion. I propose that this mechanism is used but that installation is done as in described in the earlier figure to avoid having to switch data area when provisioning to the secondary installer. Later when this is made possible with p2, this restriction can be lifted.

The first installer can look at a set of secondary installer parameters so the scheme is fully flexible.

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 requirements on the installer

This is covered in bug 263304

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.

Back to the top