PDE Support for Eclipse Update Site Building

Starting from Milestone 4, PDE provides support for building update sites in your workspace. In this document, we will walk you through the new function by starting with a clean workspace and ending with a fully functioning update site you can browse using Update Manager.

Note: M4 driver has a small glitch that prevents rebuilds of the site once Update Manager uses the JARs. The fix for this problem is available in driver 20030107 and higher.

Creating the plug-in

We will start by creating a simple plug-in. To do so, we will use PDE templates to quickly create a working plug-in that has some content.

  1. Open 'New->Plug-in Development->Plug-in Project' wizard. Choose 'com.example.xyz' as the project name. Press 'Next'.
  2. Accept the default project structure. Press 'Next'.
  3. From the list of templates, choose 'Hello, World'. Press 'Next'.
  4. You can accept the defaults. Press Finish and wait for the manifest editor to open.
  5. Verify that the plug-in works as designed by selecting the running the 'Run-time Workbench' link on the first page of the dialog (just follow the instructions on the page). The second instance should open and it should have a new 'Sample Menu' and a tool bar action that opens 'Hello, World' message box when selected.

Before moving on, we have to make sure that the plug-in will be built correctly. Content of the plug-in project is not automatically included during the build. The file that controls this is 'build.properties':

  1. Open 'build.properties' file in the project root.
  2. In the 'Build Script Variables' section on the left, press 'Add...'. Select 'bin.includes' from the list. Press OK.
  3. Select the newly added variable. Move to the section on the right and add the following by pressing 'Add' and modifying the token using editing in-place:

        *.jar
        plugin.xml
        icons/
  4. Save and exit.

The specification above will ensure that all the libraries, the manifest file and the 'icons' folder is included in the run-time version of the plug-in when it is built.

Creating the feature

We should now create a simple feature. Eclipse Update does not work with plug-ins because plug-ins are too fine-grain and usable functional chunks are composed of several plug-ins working together. Features are used to group these plug-ins, give them a name, copyright, license and other attributes important for deploying function.

  1. Open 'New->Plug-in Development->Feature Project' wizard. Choose 'com.example.xyz-feature' as the project name. Press 'Next'.
  2. Choose 'com.example.xyz' for feature Id, "XYZ Feature" for the name and "XYZ Inc." for the provider. Press Next.
  3. Choose 'com.example.xyz' plug-in from the list of plug-ins that are referenced by this feature.
  4. Press Finish. Wait for the feature manifest editor to open.
  5. Switch to the 'Information' page.
  6. Enter "Sample XYZ feature description" in the text area.
  7. Select 'Copyright Notice' and enter "Copyright XYZ Inc. 2003".
  8. Select "License Ageement" and enter:

    LICENSE AGREEMENT

    YOU MUST ACCEPT THIS AGREEMENT IN ORDER TO INSTALL THE FEATURE.
  9. Save (Ctrl+S).

Similarly to the plug-in project, features also require build.properties file to define what will be included in the archive during the build. By default, PDE wizard adds feature.xml to bin.includes variable during the initial creation. You need to add other files or folders you want packaged in the feature.

Creating the site

We can now create an Update Site project. Eclipse Update site is any directory that contains site.xml file that describes the features available on the site. By default, update site also contains 'features' directory containing the packaged feature archives and 'plugins' containing the packaged plug-ins.

  1. Open 'New->Plug-in Development->Update Site Project wizard. Choose 'Sample Update Site' for the project name.
  2. Press 'Finish'. Wait for the site map editor to open (since update site project does not have Java nature, the perspective will switch to 'Resource' in order to see it).
  3. Define a sample category. In the 'Category Definitions' section, press the 'Add...' button. Specify 'sample' for the name, 'Sample Category' for the label and "This category demonstrates how features can be classified." for the description. Press 'OK' and save.
  4. Switch to the Build page. Unlike other pages, this page does not define content of the site.xml file. Instead, it defines how features and plug-ins in the workspace are built in order to generate required archives.
  5. In the 'Features to Build' page, press 'Add...' button and select 'com.example.xyz' feature. Press 'Finish'. This will add the feature project to the list of features to build when 'Build Now' button is pressed.
  6. Check the feature checkbox. In addition to being built, this feature will appear in site.xml file and be visible to users that browse your site. Save.
  7. Switch to the 'Features' page to confirm the content. It should show one feature. Select it. Note how URL, Id and Version fields are defined.
  8. Focus on the 'Categories' section and check the available 'Sample Category' checkbox. This will classify the feature under this category. If not classified, the feature will appear under 'Other' category. Save.
  9. Switch back to the 'Build' page and press 'Build Now'. Wait for the build to finish. If everything is correct, you should have 'plugins' and 'features' directory under the project root and each should have 'com.example.xyz_1.0.0.jar' file.

Browsing the site

The site is now ready for browsing. We will use Update Manager to do so:

  1. Select 'Help->Software Updates->Update Manager'.
  2. Move to the 'Feature Updates' view. Find 'My Computer' object and drill down into our workspace (on the file system). You will notice that our Update Site project will have a different icon. Select it.
  3. Bring up the pop-up menu and choose the option "Bookmark Location...". For the bookmark name type "Update Site Preview". Press 'Finish'.
  4. Collapse the 'My Computer' node. You will notice a new bookmark object for our site. Expand it.
  5. You should see "Sample Category" object. Expand it.
  6. You should now see the "XYZ Feature" object. Select it. The content of the feature should show up in the Preview view on the right. Verify that Copyright, License and description is all correct.

Installing from the site

In order to verify that you can indeed install the XYZ Feature from the site, you need to use a different Eclipse instance (to avoid polluting the instance you are using for development). For that purpose, unzip an Eclipse driver somewhere else. Launch it and go directly to the Update Manager (as above - 'Help->Software Updates->Update Manager').

Once you do, repeat the steps 1-6 defined in 'Browsing the site' (when at the step 2, make sure you drill down to the design instance workspace, not the test instance). However, this time we will go further and install the feature:

  1. Press the button 'Install Now' in the Preview page. The Install wizard will open.
  2. Accept the license agreement by selecting 'I accept...' radio button. Press Next.
  3. Accept the default location where the feature will be installed. Press Finish.
  4. We haven't digitally signed the feature, so we will receive a warning. Press 'Install' button to continue.
  5. The feature will now install. When finished, you will receive a message that a restart is needed. Press 'Yes'. Wait for the restart.
  6. Once Eclipse is up again, expand 'Current Configuration' node in the 'Install Configuration' view of the Update Manager perspective. Also expand the default install site. You should see two features: "Eclipse Project SDK (Windows)" and the newly installed "XYZ Feature".
  7. To confirm that the feature has been installed correctly, switch to the Resource perspective and reset it. You should now see the 'Hello, World' tool bar button and the 'Sample Menu' menu in the menu bar.

Advanced topics

Publishing to a remote server

It is possible to publish the update site project to the final location on a remote server when using FTP/WebDav optional support (must be downloaded separately from the regular driver). This is a very nice feature because it allows you to work in the workspace, build and then upload changes to the target server by uploading the delta only:

  1. Select the update site project and bring up the pop-up menu.
  2. Choose 'Team->Target Site'. The wizard will open.
  3. Select 'FTP' protocol and press 'Next'.
  4. Select the ftp URL that includes the remote server and the path from the FTP root to the physical root of the site as defined by the HTTP server.
  5. Specify user name and password for the FTP account. Press Next.
  6. Specify the directory that will be the project root on the server (use the provided default that is the same as the project name).
  7. Press 'Finish'.

You have now established the target site. Changes you make in the workspace will be compared to the target and delta will be computed when upload is needed.

To upload, select the project and use 'Team->Synchronize with target' option. This will bring the familiar 'Synchronize' view used with CVS repositories. Select the desired branch or the root and 'Upload' the content to the server.

You can test the remote server by creating a bookmark in the Update Manager and entering the remote (http://<remote server address>/<project name>/[site.xml]) address. You should be able to browse the site and see the same content as when browsing locally (using 'file://' protocol) albeit somewhat slower (this time Update is downloading content using http protocol). If you can see it, that means everybody else that can see your server can also create the bookmark and browse the site contents.

Building multiple versions

Since version information is not included in the project name, your workspace can only hold one set of versions at a time. In contrast, update site can host many feature and plug-in versions.

You can use the update site support in PDE to build multiple versions, but you need to perform a little 'trick'. When creating Update Site project, you need to create it somewhere outside your single-version workspaces. Allocate a place on your hard drive on the site and create a the project there. You need to do this for each workspace you want to work in. Note that 'New' wizard for the update site will not create folders and files (including site.xml) that are already present in the selected location.

Since your 'features' and 'plugins' folders will contain JARs created in other workspaces, you should not use 'Scrub output folders before build' option (Build page in the site editor). Otherwise, you will loose all the JARs that do not belong to the workspace. When this option is not selected, new JARs will be created as usual but the old ones will be left alone.

When hosting multiple versions, classification using categories is very important. Note that a feature can be added to more than one category (just check as many as you want).