UpdateRepository
(XXX macro: "PageOutline")
Ideally, CSS end users can update their version of CSS seamlessly to the latest version, install desired features or uninstall functionality that they no longer want.
CSS versions with online update support have a menu entry Help, Check for Updates that contacts a pre-configured update site, then either displays available updates or states that there is nothing to update.
For example, users who downloaded epics_css_1.9.9-*.zip from http://ics-web.sns.ornl.gov/css/updates/apps/ should see that a version 2.0.0 or later is available, and after selecting the version, maybe acknowldege "unsigned" content and agreeing on a restart, CSS updates itself to that version.
The menu item Help, About... offers a button Installation Details which leads to a dialog that lists the installation history, and allows to revert to a previous version:
In addition, Help, Install New Software... allows the manual installation of optional features.
Online updates are based on Eclipse "P2", see
- Online help in the Eclipse IDE
- http://www.vogella.de/articles/EclipseP2Update/article.html ,
- http://www.ralfebert.de/blog/eclipsercp/p2_updates_tutorial/,
- http://www.slideshare.net/irbull/p2-introduction.
- http://wiki.eclipse.org/Equinox_p2_Repository_Mirroring
While the overall "update" can be accomplished in a way that is convenient to the end user, there are still some problems.
A Product must be based on Features, which in turn list Plugins. The version numbers of the product, features and plugins must change when their content is modified for P2 to recognize the change. The use of "1.1.2.qualifier" is suggested to assert that new builds will create individual versions based on the build date.
In one case it was necessary to delete the
.eclipse
directory in the home directory to make online updates take effect.
This was for a shared installation, and seems to be related to the fact that Eclipse uses several "Locations" as visible in the menu Help, About..., Installation Details, Configuration.
This setting points to a directory with P2 information about installed plugins:
eclipse.p2.data.area=@config.dir/../p2
The configuration area defaults to a location inside the CSS installation:
osgi.configuration.area=......./CSS/configuration
When the "owner" of CSS performs the online updates and then runs CSS, all is fine. When another user runs CSS, a user who does and should not have write permission to the install location, Eclipse sets the configuration area to a ".eclipse" directory in the user's home directory, and uses the original configuration area as a shared, read-only location:
osgi.configuration.area=/usr/fred/.eclipse/2083432532/configuration
osgi.sharedConfiguration.area=......./CSS/configuration
In one scenario, that ".eclipse" directory somehow caused CSS to ignore the latest online updates. Removing the ".eclipse" directory, then restarting CSS, fixed the problem.
Each CSS "Product" and each "Feature" has its default update repository built-in. Since different sites use different products, and probably also need to control what updates (features, their versions) are suitable for their users, at least for the complete product update, the update repositories need to be site-specific.
The only practical way to create products is a "headless build", but in a headless build the launchers for Linux and OS X are for the time being not marked as executable (https://bugs.eclipse.org/bugs/show_bug.cgi?id=282260).
A side effect of the headless build and a P2-managed product is that it is no longer possible to simply replace plugins in a product with new versions. If you replace a plugin JAR file with a different version, even if the names exactly match, P2 will recognize the change because of checksums and refuse to load the modified plugin.
In the spirit of maintaining a well defined product with known content, this makes sense. Occasionally, however, it is a big nuisance because quick updates to small bugs are no longer possible via basic plugin updates. Instead, one would normally create a new product by incrementing all version numbers, performing a complete headless build, then publishing the new product and update site.
A feature patch can be used to update only part of a product while maintaining full configuration control.
Assume our current product contains a plugin org.csstudio.trends.databrowser2 with version number 3.0.1
that we intend to replace with a newer version 3.0.2 without updating the whole prodcut.
We need to determine which feature provides that plugin in the product-to-update, and we need to determine its exact version, including a possible date/time qualifier. If you do not know which feature provided the original plugin, search the files in the features subdirectory of the installed product. Assume we find that the plugin was provided as part of the feature
org.csstudio.trends.databrowser2.feature_3.0.1.20110715
Create a new Feature Patch project in the Eclipse IDE:
- As a project name you can for example use “databrowser3.0.1.patch”.
- In the “Properties of feature being patched” section of the project wizard enter the “Feature ID” of the original feature, i.e
org.csstudio.trends.databrowser2.feature. - Under “Feature Version” be sure to enter the correct version that you intend to update, i.e.
3.0.1.20110715. - Add the plugins that should be updated with the patch, i.e.
org.csstudio.trends.databrowser2. The feature that we are patching might contain many more plugins, but in the patch we only include what we want to add or replace. Assert that the version numbers plugin that you want to reaplace are updated from their installed version.
You can now export the feature patch, using an archive file like databrowser3.0.1.patch.zip as the target, and then use that ZIP file to install the patch into your product via the menu item Help, Install New Software... by adding the ZIP file to the available software sites.
As a result, the original org.csstudio.trends.databrowser2 plugin is replaced with the new one, while P2 remains fully aware of what version of which plugin was installed from where.
While it can be convenient when "only updating one plugin", one should not use dropins or direct plugin folder manipulations, because that circumvents P2.
SNS CSS from version 2.3.0 on has limited support for dropins, meaning
- There is a folder
dropinsin the product - The product contains the plugin
org.eclipse.equinox.p2.reconciler.dropins - The file
configuration/org.eclipse.equinox.simpleconfigurator/bundles.infoconfigures the reconciler.dropins plugin to be started (line ends intrue)
When dropins are enabled, arbitrary plugins copied into the dropins directory will be included in the product on the next restart.
Without dropins, when manually adding plugins to the plugins folder, edit configuration/config.ini to include:
# Allow manual addition to the "plugins/" folder
# These will be ignored after the next full online update!
org.eclipse.update.reconcile=true
However, for both manually added plugins or the dropins folder the whole-product update restrictions still apply: You cannot put a new Data Browser plugin into the dropins directory when the product configuration already contains a Data Browser version.
Correctly configuring all dependencies takes a lot of time.
Help, Install New Software... might allow users to install features which are really incompatible to their current setup.
For example, it will allow users of the SNS "Office" product to add the core CSS components for the SNS "Basic" product without warnings, resulting in a product that really contains two products, which then refuses to run.