Everyware™ Software Framework

PART 5. ADDITIONAL ECLIPSE TOOLING
Continuous and Build Integration Tooling (Buckminster)

Buckminster Integration Tooling

Overview

This howto shows how to add Buckminster to Eclipse. Buckminster is a set of frameworks and tools for automated build, assemble, and deploy development processes in Eclipse. The main project site has additional information at http://www.eclipse.org/buckminster/. Internally Eurotech uses Buckminster to maintain the various project builds, ‘hierarchies’ of projects, svn checkouts, update site builds, and plugin builds. It is useful in that with a few simple clicks one can check out an entire set of projects that make up a product if the SVN is organized properly. It is also convenient in that a few simple clicks can also build the entire set of projects. Further more, the bundle version numbers can become the SVN revision numbers rather than just time stamps as they do with a standard manual export. This makes version tracking on targets much easier.

In this example you will learn how to:

Add and Configure the Buckminster Plug-ins for Eclipse

Prerequisites

Using Buckminster

Note this howto covers how to use Buckminster with Subversion. However, Buckminster also supports Git and Maven. The usage of these is outside of the scope of this document.

Begin by clicking ‘Help -> Install New Software…’ in the Eclipse menu. This will open the menu shown in figure 1. Select ‘Helios – http://download.eclipse.org/releases/helios’ in the ‘Work with:’ field. Expand the ‘General Purpose Tools’ section and select the three plug-ins below:

Buckminster - Core
Buckminster - PDE support
Buckminster - Subversive support

These are all shown in figure 1. Once they are selected click ‘Next’.

Figure 1 Selecting the Buckminster Plug-ins

This will result in the verification dialog box shown in figure 2. Click ‘Next’ again.

Figure 2 Confirming the Buckminster Plugins

A new dialog will display the Eclipse EULA that is required for these plug-ins. Accept the agreement as shown in figure 3 and click ‘Finish’.

Figure 3 Accepting the EULA

The install will probably take a few minutes to complete. Once done, it will prompt you with a restart option as shown in figure 4. Select ‘Restart Now’. This will restart Eclipse with the newly installed plug-ins.

Figure 4 Restart Dialog

With Eclipse restarted we can now configure the Buckminster plug-in. The Eclipse Welcome screen (shown in figure 5) has documentation links to the Buckminster documentation. Feel free to look it over.

Figure 5 Buckminster Welcome Screen

With Buckminster installed you now need to set up a project to use it. Buckminster is very complex and can do many things. I would suggest reading Bucky Book if you are interested in all the gory details. However, this howto will show you how to use SVN, rmaps, and features to checkout your projects and build them.

For a given product internally at Eurotech we create a ‘Bucky Bootstrap’ project in Eclipse. This project is a general project that contains some metadata files. Begin by right clicking in the Package Explorer and go to ‘New -> Project’. Select ‘General -> Project’ and click ‘Next’ as shown in figure 6.

Figure 6 Creating a General Project

Give the project a name ‘com.esf.example.bucky.bootstrap’ and click ‘Finish’ as shown in figure 7.

Figure 7 Finalizing the General Project

With the three projects created there are three components we have to add. These are:

Buckminster Properties
Resource Map
Component Query

Buckminster Properties File

This is a simple key/value properties file that defines some basic information that Buckminster should use for builds. This is an example file:

#######################################################################################

# Where all of the output should go

buckminster.output.root=${user.home}/Desktop/bucky/output

# Where all of the temp files should go

buckminster.temp.root=${user.home}/Desktop/bucky/temp

# How .qualifier in versions should be replaced (this will replace .qualifier with SVN revision number of the project)

qualifier.replacement.*=generator:lastRevision

# Don’t build source bundles

cbi.include.source=false

#######################################################################################

Create the file by right clicking on the ‘com.esf.example.bucky.bootstrap’ project and go to ‘New -> File’. This will open the dialog in figure 8. Call the file buckminster.properties.

Figure 8 Creating Buckminster Properties

Copy and paste the contents of the buckminster.properties into the file.

Resource Map

Now we need to create the ‘rmap’ file. The rmap is what Buckminster uses to find the resources necessary to resolve the projects. This is an example rmap file.

<?xml version="1.0" encoding="UTF-8"?>

<rmap

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://www.eclipse.org/buckminster/RMap-1.0"

xmlns:bc="http://www.eclipse.org/buckminster/Common-1.0"

xmlns:mp="http://www.eclipse.org/buckminster/MavenProvider-1.0"

xmlns:pp="http://www.eclipse.org/buckminster/PDEMapProvider-1.0">

<bc:propertyRef key="buckminster.component" />

</uri>

</provider>

</searchPath>

</rmap>

The main concerns in the rmap are the ‘searchPath’ entries and the ‘locator’ entries. The searchPath ties a name to an SVN location. The locator ties the name to a regular expression that represents the component names that can be found there. So, given this example all bundles, features, and buckminster components that start with the name com.esf.core will be expected in www.my_svn_server.com/svn/esf/trunk/bundles/foundation/. searchPath and locator entries can be added so Buckminster can find all of the dependent components.

To create the rmap right click on the com.esf.example.bucky.bootstrap and click ‘New -> Other’. This will open the dialog box shown in figure 9.

Figure 9 Creating the rmap

Expand ‘Buckminster’ and select ‘Resource Map’ and click ‘Next’. This will open the dialog shown in figure 10.

Figure 10 Naming the rmap

Give the rmap a name (example.rmap in this case) and click ‘Finish’. Now right click on example.rmap in the Package Explorer and select ‘Open With -> Text Editor’. This will open the rmap so you can manually edit the xml. Copy and paste the example rmap from above and change the fields to match your SVN requirements.

Component Query

The Component Query (cquery) file is the base Buckminster file that triggers the resolution of bundles in the workspace. It points to a single ‘feature’ that has knowledge of all of the required components. Those components are then resolved using the rmap file and checked out of SVN. For example, say we have a very simple project layout that looks like this:

com.esf.example.my_product_root.core.feature

#this contains two features and one plugin (com.esf.example.my_product_root.part0.bundle)

com.esf.example.my_product_root.part1.feature

#this contains two plugins

com.esf.example.my_product_root.part1.bundle

com.esf.example.my_product_root.part2.bundle

com.esf.example.my_product_root.part2.feature

#this contains one plugin

com.esf.example.my_product_root.part3.bundle

Features in Eclipse are groupings of additional Features and Plugins (aka bundles). Creating Eclipse features to group projects can be done in Eclipse. To create a feature project right click on the Package Explorer in Eclipse and select ‘New -> Project’. Now expand ‘Plug-in Development’ and select ‘Feature Project’ and click ‘Next’.

Figure 11 Creating a Feature Project

This will open the dialog shown in figure 12.

Figure 12 Specifying the Feature Name

Set the feature name as ‘com.esf.example.my_product_root.core.feature’ and click ‘Finish’.

Now open the feature.xml for the new project. This is shown in figure 13.

Figure 13 Adding Plugins to feature.xml

Click the plug-ins tab on the bottom of the main editor window. In the center of the page there is a tool to add new plugins to your feature. Add as many as you need for your project. In order for you to be able to add them via this mechanism the projects must already be in your workspace. We’ll show you how to circumvent this shortly.

You can also add features to this feature. This is shown in figure 14.

Figure 14 Adding Features to feature.xml

Adding features is the same as adding plugins – except they are features. The important points are shown above in figure 14. Again, the features must be in the workspace in order to add them this way.

You can add features and plugins to the feature.xml by clicking on the feature.xml tab of feature.xml. This is shown in figure 15.

Figure 15 Manaual Addition of features and Plugins to feature.xml

Figure 15 shows how you can add features and plugins using the ‘includes’ and ‘plugins’ tags in feature.xml manually.

So again, features can be used to group components (both more features and plugins) into common sets. For example a more real world case is shown below. For a little background Denali is a web UI driven product created by Eurotech to act as a mobile router. Denali can run on many Eurotech platforms. So, this hierarchical structure for projects is the key to keeping this organized and functioning with Buckminster. Also, Helios and Isis are hardware platforms created by Eurotech.

com.esf.example.helios_denali.feature

#this contains the two features below plus all of the Helios/Denali specific business logic plugins (i.e. to flash Helios specific LEDs)

com.esf.example.denali_base.feature

#this contains all non platform specific Denali base plugins

com.esf.example.esf_base.helios.feature

#this contains the following esf_base feature plus all Helios specific ESF foundation plugins plugins

com.esf.example.esf_base.feature

#this contains all of the core non-platform specific ESF foundation plugins

A corollary project running Denali on the Isis would look like this.

com.esf.example.isis_denali.feature

#this contains the two features below plus all of the Isis/Denali specific business logic plugins (i.e. to take advantage of the Isis’ additional Serial ports)

com.esf.example.denali_base.feature

#this contains all non platform specific Denali base plugins

com.esf.example.esf_base.isis.feature

#this contains the following esf_base feature plus all Isis specific ESF foundation plugins plugins

com.esf.example.esf_base.feature

#this contains all of the core non-platform specific ESF foundation plugins

So, even though this is similar software running on different platforms the code is structured in a way so much of it is shared across the two products. Furthermore, features like com.esf.example.esf_base.helios.feature can be used as the ‘Isis esf_base’ since additional foundation bundles are present in it take advantage of the Isis’ unique capabilities. But, again com.esf.example.esf_base.feature is still common across all platforms.

Regardless of the layout beyond the ‘root’ project (com.esf.example.helios_denali.feature and com.esf.example.isis_denali.feature in the two examples above) the rest of the layout is of no concern to Buckminster. The only thing that Buckminster cares about is that there is only a single ‘root’ project and that all downstream projects (both features and plugins) can be found using the rmap file.

With this understanding we can now make the cquery file. Begin by right clicking on the com.esf.example.bucky.bootstrap project and selecting ‘New -> Other’. This will open the dialog shown in figure 16.

Figure 16 Creating the Component Specification file

As shown in figure 16 expand ‘Buckminster’ and select ‘Component Query file’ and click ‘Next’. This will open the dialog shown in figure 17.

Figure 17 Changing the Name of the cquery

The dialog will open showing the container as /com.esf.example.bucky.bootstrap. This is fine. But we should change the name of the project. Normally this would be something like [product_name].cquery. However, in this case we’ll just call it example.cquery. Then click ‘Finish’.

This will open the cquery file as shown in figure 18.

Figure 18 Editing the cquery

The cquery must be modified to point to the three items shown in figure 18. These are the core feature (com.esf.example.my_product_root.core.feature), the properties file, and the rmap. Also, the core feature must be specified as a ‘Component Type’ of eclipse.feature. Once done all we have to do is ‘Resolve and Materialize’ the projects. This is done by clicking the button shown in figure 19.

Figure 19 Resolving and Materializing

When this button is clicked, all of the features that ‘extend down’ from the base com.esf.example.my_product_root.core.feature will be automatically fetched from the SVN and put into the workspace. If there are errors they will be displayed in the console at the bottom of the Eclipse window in the console.

You can download all of the example projects here. Use this procedure to import them into your workspace. Once you have them, this is the process to test them in your new Buckminster environment. Modify the rmap to look as follows:

<?xml version="1.0" encoding="UTF-8"?>

<rmap

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns="http://www.eclipse.org/buckminster/RMap-1.0"

xmlns:bc="http://www.eclipse.org/buckminster/Common-1.0"

xmlns:mp="http://www.eclipse.org/buckminster/MavenProvider-1.0"

xmlns:pp="http://www.eclipse.org/buckminster/PDEMapProvider-1.0">

<bc:propertyRef key="buckminster.component" />

</uri>

</provider>

</searchPath>

</rmap>

Change the highlighted portion to match the URL of your SVN with the full path to the projects in SVN. Now commit all of the projects to the location you specified in the rmap. Now create a new clean workspace and check out only the com.esf.example.bucky.bootstrap project. Open the cquery file and click the ‘Resolve and Materialize’ button. At this point, if the rmap was modified properly all of the bundles should come down from the SVN and into your workspace.

At this point, you can attempt to do a build. Begin by right clicking on the root project (com.esf.example.my_product_root.core.feature) and select ‘Buckminster -> Invoke Action’. This will open the dialog shown in figure 20.

Figure 20 Building the Update Site (and plugins)

Browse to the com.esf.example.bucky.bootstrap projects buckminster.properties file. Select ‘site.p2’ and click ‘OK’. This will build the update site. In the directory that was specified for the output in buckminster.properties is where you will find the built projects. This is shown if figure 21.

Figure 21 Built Features and Plugins

Note this step has now replaced the ‘export -> plugins and fragments’ that we typically do when building bundles. If you decend into the com.esf.example.my_product_root.core.feature_1.0.0-eclipse.feature\site.p2\plugins directory you will see all of the plugins that were build in our hierarchy of projects. This is shown in figure 22.

Figure 22 Built Projects

This process can be hard to deal with at first. But, as you projects and products begin to fork and branch this makes keep them grouped and orderly very easy. It also makes SVN checkouts easy, makes getting tagged versions of code easy, and makes building binaries with SVN revision numbers easy. Once Buckminster and the setup is place you’ll be glad it is there.

<<Previous Quickstart Next>>