Creating the Update Site Project

In the New Project wizard that pops up, open the Plug-in Development folder

Click on Update Site Project

Give the project a name. We use org.test.update

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.

Right click on the project and select New -> Other

In the New wizard that pops up, open the Buckminster folder

Select Component Specification file and click on Next

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:

Click on the Artifacts tab

Click on New below the Artifacts table

Enter the name site.template

Click on the New button next to the Path table

Enter the name site.xml in the dialog that pops up and click OK

Click on New below the Artifacts table

Enter the name site.rootFiles

Click on the New button next to the Path table

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:

Click on the Dependencies tab

For each feature that you want to add, repeat the following:

Click on New just next to the Dependencies table

Enter the name of a feature component

Set the Component Type to eclipse.feature

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:

Click on the Groups tab

For each category, repeat the following:

Click on New just below the Groups table

Enter the name of the group. In our example Basic or Optional

For each feature that should be included in this group

Click on New just next to the prerequisites table

Select a feature from the drop down menu.

Enter the name feature.jars

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:

Click on the Groups tab

Click on New just below the Groups table

Enter the name of the group. We call it feature.jars

For each category that should be included in this group

Click on New just next to the prerequisites table

Leave the component name blank

Select the category group using the drop down menu.

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:

Click on New just below the Groups table

Enter the name of the group. We call it bundle.jars

For each feature that should be included in this group

Click on New just next to the prerequisites table

Select a feature from the drop down menu.

Enter the name bundle.jars

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.

Click on the Actions tab

Adding General action information

Click on New below the Actions table

Enter the name build.site

Put a check mark the Public checkbox

Enter the Actor Name:ant

Adding the site.template prerequisite

Click on the New button next to the Prerequisites table

Leave Component blank (this means current component)

Select site.template from the Attribute combobox

Enter the Alias name template

Click OK

Adding the rootFiles prerequisite

Click on the New button next to the Prerequisites table

Leave Component blank

Select site.rootFiles from the Attribute combobox

Enter the Alias name rootFiles

Click OK

Adding the features

Click on the New button next to the Prerequisites table

Leave Component blank

Select feature.jars from the Attribute combobox

Enter the Alias name features

Click OK

Adding the plugins

Click on the New button next to the Prerequisites table

Leave Component blank

Select bundle.jars from the Attribute combobox

Enter the Alias name plugins

Click OK

Adding general properties. These properties control the general behavior.

In the middle pane, click on Properties

Click on New next to the General Properties table

Enter Keysite.name and a value such as test.archivedsite

Click OK

If you want your site to have some extra suffix such as _incubation then:

Click on New next to the General Properties table

Enter Keysite.extra.suffix and a value such as _incubation

Click OK

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.

Click on New next to the Actor Properties table

Enter KeybuildFileId and the value buckminster.pdetasks

Click OK

Click on New again

Enter Keytargets and the value create.site

Click OK

Finally, we must specify the product of this action and give it an alias that it passes on to Ant.

Click on Products in the middle pane.

Enter the Product Aliasaction.output

Enter the Product Base Pathsite/

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

Building the 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.