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
(Specifying the need for an install handler)
 
(36 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{CommentBox|W.I.P}}
+
{{CommentBox|Obsolete}}
=Introduction=
+
This page describes a proposal for adding support for a mechanism similar to the Update Manager's "Install Handler".
+
See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=257792 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.
+
 
+
==Solution==
+
===Structure===
+
Here is a proposed structure for how the various parts are organized. It helps to have this explained first.
+
[[Image: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 meta data version/capabilities - so may not be 3.4, 3.5 etc
+
* 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 .p2 data area and has a profile that reflects its location
+
 
+
===Scenarios===
+
====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 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
+
 
+
'''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 IU's - 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.
+
===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 and sets up a monitor that reacts to data from the secondary process.
+
===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 [https://bugs.eclipse.org/bugs/show_bug.cgi?id=263304 bug 263304]
+
 
+
=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.
+
 
+
[[Category:Equinox p2|Install Handler Proposal]]
+

Latest revision as of 05:31, 3 August 2009

Obsolete

Back to the top