Difference between revisions of "Building an RCP application with Hudson and Buckminster"

Revision as of 03:35, 20 July 2009

This article is currently a draft and not all necessary resources are in place yet.

This tutorial will show how to set up a cross platform build of an RCP application with Buckminster and Hudson. The application to be built will be the Buckminster MailApp RCP which can be found in the Subversion Repository.

Prerequisites

Before attempting this tutorial you need several things up and running

• A running instance of Hudson CI Server
• The Buckminster PlugIn for Hudson
• A headless installation of Buckminster that also contains the Equinox_p2_director_application (as of bug 282992 this currently means to manually copy the org.eclipse.equinox.p2.director.app bundle into the 'plugins' directory of the Buckminster installation)
  

Project Layout

The MailApp shows all the necessary parts to make a P2 enabled product buildable with Buckminster.

org.eclipse.buckminster.tutorial.mailapp

This is the actual PlugIn. It contains the source code of the example application as well as all product customizations like the splashscreen and the product extension.

org.eclipse.buckminster.tutorial.rcpp2.feature

This feature project includes all the necessary plugins to make the resulting RCP self-managed (i.e. enable the p2 update manager)

org.eclipse.buckminster.tutorial.product.feature

This feature will be the main feature to be installed. It contains the actual plugin, the product definition, all necessary dependencies and a build script along with a CSPECX to make this build script known to Buckminster. A product definition is similar to a feature in a way that both aggregate features and plugins. However, a product definition can only be feature-based, or plugin-based, not both at the same time, whereas a feature can have both included plugins and features. That's why it is common practice to have your product feature-based and delegate all the work to the single feature you are including in your product.

Note that the feature contains the org.eclipse.equinox.executable feature besides the plugin itself, org.eclipse.rcp and org.eclipse.buckminster.tutorial.rcpp2.feature. This feature is necessary for all products that contain native launcher artifacts and it is included in the Delta Pack.

Buckminster will create an update site from that feature that contains all the plugins, features and binary artifacts. Once that is done, the build script will then utilize the p2 director application to create the actual product from the update site's content. To make this action known to Buckminster a CSPECX is required for that feature.

<?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="create.product" actor="ant">
            <actorProperties>
                <property key="buildFile" value="build/product.ant"/>
                <property key="targets" value="create.product"/>
            </actorProperties>
            <properties>
                <property key="profile" value="MailProfile"/>
                <property key="iu" value="org.eclipse.buckminster.tutorial.mailapp.product"/>
            </properties>
			<prerequisites alias="repository">
				<attribute name="site.p2"/>
			</prerequisites>
            <products alias="destination" base="${buckminster.output}">
            	<path path="MailApp/"/>
            </products>
		</public>
		<public name="create.product.zip" actor="ant">
            <actorProperties>
                <property key="buildFileId" value="buckminster.pdetasks"/>
                <property key="targets" value="create.zip"/>
            </actorProperties>
			<prerequisites alias="action.requirements">
				<attribute name="create.product"/>
			</prerequisites>
            <products alias="action.output" base="${buckminster.output}">
            	<path path="MailApp.zip"/>
            </products>
		</public>
	</actions>
</cspecExtension>

This will make the two actions (create.product and create.product.zip) known to Buckminster. If you materialized the MailApp Tutorial into your workspace and have the Delta Pack installed, you should have everything in place now to create the product with Buckminster just by right clicking on org.eclipse.buckminster.tutorial.mailapp.product.feature and selecting buckminster -> invoke action -> create.product.zip.

Configuring the Build Environment

In case you don't have a headless Buckminster installation just yet, follow the instructions in Getting started with Headless Buckminster. For convenience, these are essentially the steps to do:

director -r http://download.eclipse.org/tools/buckminster/headless-3.5/ -d BUCKMINSTER_INSTALL_DIRECTORY -p Buckminster -i org.eclipse.buckminster.cmdline.product
buckminster install http://download.eclipse.org/tools/buckminster/headless-3.5/ org.eclipse.buckminster.core.headless.feature
buckminster install http://download.eclipse.org/tools/buckminster/headless-3.5/ org.eclipse.buckminster.cvs.headless.feature
buckminster install http://download.eclipse.org/tools/buckminster/headless-3.5/ org.eclipse.buckminster.pde.headless.feature
buckminster install http://download.eclipse.org/tools/buckminster/headless-3.5/ org.eclipse.buckminster.maven.feature
buckminster install http://download.cloudsmith.com/buckminster/external/ org.eclipse.buckminster.subversive.headless.feature

Once this is done, configure the Buckminster installation in Hudson. To do so, open the Hudson web interface and navigate to 'Manage Hudson' -> 'Configure System' and press 'Add' at the Buckminster section.

Creating the Build Job

Preparations

Before getting started in Hudson, we need to define the target platform to build against. Since the MailApp does not have many dependencies, we only need the org.eclipse.platform feature and the org.eclipse.equinox.executable feature. To materialize the target platform into the Hudson job workspace, we create an MSPEC with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<mspec
	xmlns="http://www.eclipse.org/buckminster/MetaData-1.0"
	name="Target Platform MSPEC"
	materializer="p2"
	installLocation="${targetPlatformPath}"
	url="http://todo/tp.cquery">
    <property key="target.arch" value="*"/>
    <property key="target.os" value="*"/>
    <property key="target.ws" value="*"/>
</mspec>

Note the wildcard for target.arch, target.os and target.ws. That will ensure that the materialized target platform is platform agnostic. This MSPEC appoints a CQUERY that contains the information on the component to retrieve.

<?xml version="1.0" encoding="UTF-8"?>
<cq:componentQuery xmlns:cq="http://www.eclipse.org/buckminster/CQuery-1.0" resourceMap="http://todo/tp.rmap">
    <cq:rootRequest name="org.eclipse.platform" componentType="eclipse.feature"/>
    <cq:advisorNode namePattern=".*" useTargetPlatform="false" useWorkspace="false"/>
    <cq:property key="target.arch" value="*"/>
    <cq:property key="target.os" value="*"/>
    <cq:property key="target.ws" value="*"/> 
</cq:componentQuery>

The CQUERY again contains wildcards for the target platform filters and also an Advisor Node. The Advisor Node will ensure that nothing is resolved from the current Buckminster Runtime, itself. This target platform will cover all dependencies of the RCP, except for the equinox executable feature, so we need another CQUERY and MSPEC to import the org.eclipse.equinox.executable feature.

Configuring the Job

Next you need to create a new Job to build the product. This can be either a freestyle project for just one product, or a multiconfiguration project if you want to build your RCP for several different platforms at once. This tutorial will use the multiconfiguration project. First add an 'Execute Shell' build step into the Job configuration to always start with a clean workspace:

rm -Rf $WORKSPACE

The next build step will be 'Run Buckminster', where the actual work takes place. These are the steps that need to be done:

1. import org.eclipse.platform into the target platform location
   
2. import org.eclipse.equinox.executable into the target platform location
   
3. set the target platform path for the actual product build to the newly imported target platform
   
4. resolve the MailApp
   
5. invoke the create.product.zip action
   

The MSPECs to be imported reference the property ${targetPlatformPath}, so that value needs to be passed to the Buckminster runtime as an extra JVM property. This is done in the Hudson Plugin by using the 'Advanced' button.

After those steps, you most likely want Hudson to archive the MailApp.zip artifact. This can be done, for this example, with the following expression:

buckminster.output/org.eclipse.buckminster.tutorial.mailapp.product.feature*/MailApp.zip

This is what the result should look like:

Building for multiple platforms

The above configuration should already be sufficient to build your RCP with Hudson. However, so far it will only build for the platform Hudson is running on. To build for several different platforms you need to add three new axes to the multiconfiguration project. For example:

Next, a combination filter needs to be added to filter out the impossible combinations:

!((os=="linux" && ws=="win32") || (os=="win32" && ws=="gtk"))

The multiconfiguration project will now execute the build steps with all possible combinations of the values of the three axes (except for the filtered ones). To pass the currently selected values to Buckminster, we simply need to add additional JVM properties in the advanced configuration of the Buckminster build step. The complete list of additional properties should now look like this:

-DtargetPlatformPath=${WORKSPACE}/targetPlatform
-Dtarget.os=${os}
-Dtarget.ws=${ws}
-Dtarget.arch=${arch}

Now everything should be in place to execute the job. Once it has successfully completed, the configuration matrix should show the following result:

Clicking on of the executed combinations will reveal the built artifact for this platform configuration