The intent of this tutorial is to assist you in setting up an update site to add plugins/features to mHARP-EQ. The update site is a really nice feature of Eclipse that allows others to add functionality to mHARP-EQ without including them as part of the core platform.
- A good understanding of Eclipse Plug-ins and Features
- A good understanding for installing a web server (e.g. Apache)
Assuming that you have a good understanding of the prerequisites, the first thing to do is to go through this Eclipse wiki page that provides very basic instructions for creating an update site.
There are some parts of the feature.xml that you will want to update. Some of these updates will also be done to the plugin or plugins that are part of the feature.
In the Overview tab, at a minimum you should provide:
- ID - unique id of the feature
- Version - feature version (e.g. 1.0.0.qualifier). See the guidelines here for feature and plugin versioning and when/how to increment.
- Name - feature name, should be an externalized string
- Vender - Name of the vendor providing the plugin (e.g. NCSA). This should be an externalized string.
In this section, you should provide users with information about your feature. For example, you should at a minimum provide:
- Text - a brief description of the feature and what it contains
- Copyright Notice
- Text - The copyright notice for the feature.
- License Agreement
- License - Most features will choose local license
- Text - The text regarding the feature's license. This will be displayed to the user during installation from the update site.
In the plug-ins tab, list all plug-ins and fragments that should be packaged in the feature. Optionally, you can specify a specific version of a plugin.
This tab should list the dependent features and/or plug-ins for the feature to be installed. This is used by the update mechanism in mHARP-EQ to determine what dependencies should be satisfied to install the feature. This prevents incomplete features from being installed and breaking the application.
Updating Plug-in Manifest
This section will briefly describe the part(s) of the MANIFEST.MF that are relevant for creating the update site. This is not intended to be an exhaustive overview of the MANIFEST, for more details see the Eclipse Help guide.
In the overview tab, the following information should be provided:
- ID - the unique id for the plugin
- Version - the version of the plugin, see the rules mentioned in the previous section for how to version your plug-ins.
- Name - the name of the plug-in (e.g. mHARP Buildings)
- Vendor - the vendor providing the plugin
The site.xml defines what features the update site has available. The next section will discuss the different parts of the site.xml.
Site Map tab
It's recommended that you add 1 or more categories to organize your features in the site map tab and that you keep features small in size (e.g. as few plug-ins as possible). The categories will help users determine what each feature contains (e.g. Buildings, Bridges, etc) and keeping the features small will allow users to only install what they want (e.g. don't group buildings/bridges/networks/etc in the same feature). After you have created the categories and added your features to them, if you click the Build All button you will see a features and plugins folder created along with an artifacts.jar and content.jar. Those created files/folders along with the site.xml is what will go in your update site folder. See the next section for details.
Hosting your Update Site
Setting up the update site is fairly straightforward. If you an Apache or equivalent web-server installed on a machine (for this tutorial we'll assume Apache on an Ubuntu machine), then all you need to do is copy the following to the web server's root folder /var/www/:
- features folder
- plugins folder
- artifacts.jar file
- content.jar file
- site.xml file
After copying those files to your web server root folder, you can test your update site by launching mHARP-EQ and doing the following:
- Go to Help > Install New Software...
- Click the Add... button and enter a Name and the Location (e.g. the web address of your update site).
- Click OK
- Where it says Work with:, select your update site. You should see your categories and features listed in the dialog.