Publishing a Buckminster Update Site

Information:
Buckminster does not seem to be very active anymore. To build Eclipse products, update sites and similar have a look at my tycho tutorials. My Buckminster tutorials are no longer maintained and remein here as reference only.


Building a p2 update site with Buckminster is fairly easy. Following the tutorial "Building a p2 Update Site" from BuckyBook will give you a working update site in minutes. What I was missing was some way to publish the resulting p2 site automatically. Fortunately Buckminster actions can easily be extended. What we want to do is create a new ant task that copies over the p2 site to a user defined location.

Source code for this tutorial is available on googlecode as a single zip archive, as a Team Project Set or you can checkout the SVN projects directly.

Step 1: Prerequisites

Before we can extend our build process we need to create an update site according to the Buckminster tutorial.

Plug-in Project

Create a new Plug-in Project named com.example.myplugin. On the 2nd page enable This plug-in will make contributions to the UI. On the 3rd page select the template Plug-in with a view. Leave everything else unchanged.

Feature Project

Create a new Feature Project named com.example.myfeature. Add the plug-in com.example.myplugin to the feature.

Update Site Feature

Buckminster needs a unique Feature Project for building its update site. So create a new Feature Project named com.example.update.p2. Add com.example.myfeature to the included features.

Create a new file called buckminster_p2.properties with following content:

# Where all the output should go
buckminster.output.root=${user.home}/Build/Example P2

# Where the temp files should go
buckminster.temp.root=${user.home}/tmp

# How .qualifier in versions should be replaced
qualifier.replacement.*=generator:lastRevision

target.os=*
target.ws=*
target.arch=*

Creating categories

A nice update site groups its features in categories. So lets create a new Category Definition in com.example.update.p2. The editor is rather straight forward. Create categories with a unique ID and a display Name. Afterwards add your com.example.myfeature feature to the category.

Whenever your feature version number changes, you need to re-add your feature again.
Now right click on your com.example.update.p2 Feature Project and select Buckminster -> Invoke Action...

Select the site.p2 action and enter your buckminster_p2.properties properties file location. After hitting OK your update site will be built. Following this example it will be located at

${user.home}/Example P2/com.example.update.p2_1.0.0-eclipse.feature/site.p2

Step 2: Generating a publish action

To create a publish action we need to create an ant file doing the work and a specification telling buckminster what to do. Lets start by declaring the destination for the publish action.

Open buckminster_p2.properties and add following line

updatesite.destination=${user.home}/Build/UpdateSite

This will be our target destination. Now create a new file buckminster.cspex in your com.example.update.p2 Feature Project with following content:

<?xml version="1.0" encoding="UTF-8"?>
<cspecExtension xmlns:com="http://www.eclipse.org/buckminster/Common-1.0"
                    xmlns="http://www.eclipse.org/buckminster/CSpec-1.0">
    <actions>
        <public name="site.p2.publish" actor="ant">
            <actorProperties>
                <property key="buildFile" value="build/publishUpdateSite.ant" />
                <property key="targets" value="publish.p2" />
            </actorProperties>
            <properties>
                <property key="source" value="${buckminster.output}/site.p2/" />
                <property key="destination" value="${updatesite.destination}" />
            </properties>
            <prerequisites alias="repository">
                <attribute name="site.p2" />
            </prerequisites>
            <products base="${updatesite.destination}" upToDatePolicy="ACTOR"/>
        </public>
    </actions>
</cspecExtension>

Line 5 creates an action called site.p2.publish and delares it an ant task.
Line 7 defines the and build file, line 8 the ant target
Line 11,12 define source and destination properties for the ant task
Line 15 defines the buckminster site.p2 action as a prerequisite. This means that first site.p2 is executed, afterwards our ant task is called.

Finally we need to add our ant task. Create a file build/publishUpdateSite.ant and add following lines:

<project>
    <target name="publish.p2">
        <echo message="Source:      ${source}"/>
        <echo message="Destination: ${destination}"/>
        
        <mkdir dir="${destination}"/>
        <copy todir="${destination}" preservelastmodified="true">
            <fileset dir="${source}"/>
        </copy>
    </target>
</project>

This will create the destination folder if not present and copy the p2 site content to that location.

Step 3: Executing the publish action

Save all files, right click on your com.example.update.p2 Feature Project and select Buckminster -> Invoke Action...
Use site.p2.publish action. Take care that the property file location is still correct. Push OK to publish your update site. You can find your site at C:\Build\UpdateSite

The ant task is rather simple and can easily be extended to eg. use WebDav to upload the content to a webserver or to store the update site to SVN, ...

Alternative: Alter site.p2 action directly

If publishing is just a question of copying files we can do this without our custom action and ant task. Instead we can directly modify the target path of the site.p2 action. Therefore set your buckminster.cspex content to

<?xml version="1.0" encoding="UTF-8"?>
<cspecExtension xmlns:com="http://www.eclipse.org/buckminster/Common-1.0"
                    xmlns="http://www.eclipse.org/buckminster/CSpec-1.0">

    <alterActions>
        <public name="site.p2">
            <products base="${updatesite.destination}/" upToDatePolicy="ACTOR"/>
        </public>
    </alterActions> 
</cspecExtension>