Building an Update Site using Buckminster

Creating the Update Site Project

1. Right click in the Package Explorer and select New -> Project
2. In the New Project wizard that pops up, open the Plug-in Development folder
3. Click on Update Site Project
4. Give the project a name. We use org.test.update
5. Click on Finish

The project appears in the workspace and it contains one single file, an empty site.xml. Buckminster will use this as the update site template. This means that you can add site categories to this file but you should not add any features. Buckminster will generate a new site.xml where the features are added.

Creating an index.html file

Just create an empty file for now and call it index.html. You can add content to this file that will be what the user will see if they happen to access your update site with a browser.

Creating the Component Specification

Now we need to add some content to our site. This is done by adding a Buckminster CSPEC to the project.

1. Right click on the project and select New -> Other
2. In the New wizard that pops up, open the Buckminster folder
3. Select Component Specification file and click on Next
4. Click on Finish to accept the default values for Container: and File name:

A file named buckminster.cspec is created in the project and the Buckminster CSPEC editor opens:

Main information

• The name of the component is normally the same as the name of the project. This makes it easier to find the component.
• The component type must in our case be set to buckminster.
• The version can be any OSGi compliant version such as 1.0.0

Artifacts

Artifacts denotes files and folders that are present inside of a component. The action that will create the update site needs to know about the site.xml template and other files to copy so we need to add that to our specification:

1. Click on the Artifacts tab
2. Click on New below the Artifacts table
3. Enter the name site.template
4. Click on the New button next to the Path table
5. Enter the name site.xml in the dialog that pops up and click OK
6. Click on New below the Artifacts table
7. Enter the name site.rootFiles
8. Click on the New button next to the Path table
9. Enter the name index.html in the dialog that pops up and click OK

We now have two artifacts, each with one path. The separation is necessary in this particular case since the build action will reference the artifacs separately. An artifact may have several paths and you can add as many files and folders as you wish to the site.rootFiles artifact.

Dependencies

We need to define the features that will be included on the update site. Buckminster considers them to be dependencies:

1. Click on the Dependencies tab
2. For each feature that you want to add, repeat the following:
   1. Click on New just next to the Dependencies table
   2. Enter the name of a feature component
   3. Set the Component Type to eclipse.feature
   4. Click OK

Groups (categories)

This step is optional unless you want to categorize the contents of the update site. The build action will automatically match groups that it finds in the CSPEC with categories that it finds in the site template. Let's assume that we added the two categories Basic and Optional to the site.xml file when we edited it earlier. Now we want to divide our features into these two categories:

1. Click on the Groups tab
2. For each category, repeat the following:
   1. Click on New just below the Groups table
   2. Enter the name of the group. In our example Basic or Optional
   3. For each feature that should be included in this group
      1. Click on New just next to the prerequisites table
      2. Select a feature from the drop down menu.
      3. Enter the name feature.jars
      4. Click OK

The feature.jars group

We need one group that contains all features that should be present on the update site. If we were using categories in the previous step, this group will simply contain them. If we don't have categories, this group will reference the features directly. In the latter case, the group is created in exactly the same way as described for the category groups. In the former case, we do like this:

1. Click on the Groups tab
2. Click on New just below the Groups table
3. Enter the name of the group. We call it feature.jars
4. For each category that should be included in this group
   1. Click on New just next to the prerequisites table
   2. Leave the component name blank
   3. Select the category group using the drop down menu.
   4. Click OK

The bundle.jars group

In addition to finding all features to include, the action also needs to know about all bundles that those features are referencing. Each feature exposes this with a special attribute bundle.jars so the only thing we need to do is to group them together:

1. Click on New just below the Groups table
2. Enter the name of the group. We call it bundle.jars
3. For each feature that should be included in this group
   1. Click on New just next to the prerequisites table
   2. Select a feature from the drop down menu.
   3. Enter the name bundle.jars
   4. Click OK

If you follow the example, you now have four groups, Basic, Optional, feature.jars, and bundle.jars.

The Action

The last thing to add to the CSPEC is the Action that will trigger the actual build of the update site.

1. Click on the Actions tab
2. Adding General action information
   1. Click on New below the Actions table
   2. Enter the name build.site
   3. Put a check mark the Public checkbox
   4. Enter the Actor Name: ant
3. Adding the site.template prerequisite
   1. Click on the New button next to the Prerequisites table
   2. Leave Component blank (this means current component)
   3. Select site.template from the Attribute combobox
   4. Enter the Alias name template
   5. Click OK
4. Adding the rootFiles prerequisite
   1. Click on the New button next to the Prerequisites table
   2. Leave Component blank
   3. Select site.rootFiles from the Attribute combobox
   4. Enter the Alias name rootFiles
   5. Click OK
5. Adding the features
   1. Click on the New button next to the Prerequisites table
   2. Leave Component blank
   3. Select feature.jars from the Attribute combobox
   4. Enter the Alias name features
   5. Click OK
6. Adding the plugins
   1. Click on the New button next to the Prerequisites table
   2. Leave Component blank
   3. Select bundle.jars from the Attribute combobox
   4. Enter the Alias name plugins
   5. Click OK
7. Adding general properties. These properties control the general behavior.
   1. In the middle pane, click on Properties
   2. Click on New next to the General Properties table
   3. Enter Key site.name and a value such as test.archivedsite
   4. Click OK
   5. If you want your site to have some extra suffix such as _incubation then:
      1. Click on New next to the General Properties table
      2. Enter Key site.extra.suffix and a value such as _incubation
      3. Click OK
8. Adding actor properties. These properties control behavior specific to an actor. We need two of them. One to specify the ant build script that will be used and another to specify what ant target to call in that file.
   1. Click on New next to the Actor Properties table
   2. Enter Key buildFileId and the value buckminster.pdetasks
   3. Click OK
   4. Click on New again
   5. Enter Key targets and the value create.site
   6. Click OK
9. Finally, we must specify the product of this action and give it an alias that it passes on to Ant.
   1. Click on Products in the middle pane.
   2. Enter the Product Alias action.output
   3. Enter the Product Base Path site/

This concludes the CSPEC editing. Save it using CTRL-s or File -> Save

Building the site

Right-click on your project, select Buckminster -> Invoke action -> build.site

The output will end up in ${user.temp}/buckminster by default. You can change this by setting the property buckminster.output.root in a property file that you reference when you execute the action. You can also specify properties using Windows -> Preferences -> Run/Debug -> String substitution.