Revision as of 06:58, 20 November 2007

Contents

Overview of the Example

This examples shows several Buckminster features in action. What these components actualy do when they are executed is not that interesting - there is an XML file with "worlds", there is a world producer and a class that says "hello" to worlds.

If you want to see the difference between setting up this example project manually, and how it works when running Buckminster, see the usage scenario Sharing a Project.

Here is an overview of what is going on:

The A component is called org.demo.hello.xml.world

It lives in a CVS repository

It is an Eclipse plugin - it has some meta data

A has a dependency on B

The B component is called org.demo.xml.provider

It lives in a CVS repository

It is an Eclipse plugin - it has some meta data

It requires two jars; the jar in component D, and a jar that is built by component C.

Component C is called org.demo.worlds

It lives in a CVS repository

Although it is an Eclipse project, it is not an Eclipse plugin.

Component D is a sax parser called se.tada.util.sax

It lives in binary form in the maven repository at Ibiblio

To run the example:

Make sure you have the latest version of Buckminster

Make sure you have the Buckminster Maven plugin installed as this demo feteches things from a Maven repository

The 6 first lines declare the name spaces and syntax of the rmap and the repository providers needed.

Below that you see two major elements declaring search paths, the first is called default, and the second is called maven.

Continue down and you see two locator declarations...

the first states that if a component name starts with se.tada. then the maven search path should be used.

and the second locator states that if the name starts with org.demo. then the default path should be used.

Back to the paths:

The default path:

The default path declares that the repository is in SVN and that what we find is an eclipse plugin

We do not need to commit changes back (mutable=false), and we do not want source (source=false).

The URI to the SVN repository is stated next

This URI ends with the name of the component. This name is obtained from the preset property buckminster.component which contains the name of the component being matched.

The maven path:

The maven path declares that it uses a maven provider and a reader type of maven and that the component type is also a maven component. Further the mutable=false says that we are not interested in committing any changes back to the repository, and source=false says that we are not interested in source.

A URI to the maven repository at Maven.org is declared

A mapping that translates the component name into what the actual file on Ibiblio is called is then declared (i.e. mapping se.tada.util.sax to tada-sax).

The CSPEC in Component C

Since component C - org.demo.worlds is not a plugin and thus lack meta data that describes its dependencies, and
how to produce it, we need to add this information.
We decide to use Buckminster's CSPEC XML language. This is what we place in a file called buckminster.cspec inside component C:

First two lines declare that this is XML, and that it follows the CSPEC format, and it describes a component called org.demo.worlds

Next section lists the component attributes that are artifacts (i.e. a static declaration of paths).

There is only one declaration, a public attribute called source that is mapped to a directory called src. Notice that the name ends with a slash to denote that we refer to the directory.

Next section lists the component attributes that are implemented as actions (i.e. computed attribute values).

java.binary.archives is the first

It is implemented using an ANT action, and parameters are set

Then there is one pre-requisite - the local attribute eclipse.build is needed before this action can execute.

The CSPEX in the B Component

The B components component meta data is created from the information in the Eclipse plug-in. But there are things we want to add that can not
be declared in the regular plug-in meta data. Buckminster makes it possible to extend the generated CSPEC by adding a file buckminster.cspex. This file follows the CSPEC format. In this example this is straight forward as we are only adding things.
Here is the content of the CSPEX file for component B (org.demo.xml.provider).

Lines 1-4 is the XML stuff and declaration of namespaces. Note the use of a cspecExtension element as the top most element.

Next, two component dependencies are listed, on the component org.demo.worlds (a plugin ("osgi.bundle")), and on the tada sax-parser se.tada.util.sax.

The following actions section declares a private "prebind" action - this action kicks in before the component content is bound to the Eclipse workspace. As you can see, the action is an ant action, and it uses a make/prebind.xml file with the instructions for the build.

There are two pre-requisites - on the sax parser, and on a jar file called worlds-jar that is obtained from the attribute java.binary.archives in the component org.demo.worlds

The products section declares that the result is called output and where the output is produced.

Demo flow

The following takes place when Buckminster resolves the query.

Resolving the CSPEC for all components

The name of the top component in the CQUERY is resolved to the default searchPath in the RMAP.

The SVN provider of this RMAP is chosen (it's the only one)

The eclipse.project componentType will obtain the ProjectDescriptor (the .project) from the eclipse project.

From the natures of that descriptor, it will conclude that the component is a plugin.

The component type will use a PluginBuilder to create a CSPEC from the plugin manifest files.

This CSPEC will contain a dependency to the org.demo.xml.provider component.

Buckminster now resolves that component in the exact same #1 to #6

The CSPEC from org.demo.xml.provider is augmented with a CSPEC extension (CSPEX) that adds the jar dependencies (since those cannot be fully expressed in the plugin manifest)

The first jar dependency is resolved using the same provider as before but the ProjectDescriptor has no plugin nature this time so the CSPEC that has been checked in with the component instead.

The second jar is resolved using the maven search path and the maven repository.

Materializing and binding the components

All components are copied (by Buckminster) to the local disk using the chosen providers.

The bind phase starts and components are bound in dependency order.

The first component that becomes known to Eclipse is org.demo.worlds (i.e. C)

The CSPEX of the second component, org.demo.xml.provider (i.e. B) contains a prebind action that:

Builds component C to a jar and copies that jar into the jars directory of component B.

Copies the component D from a cache location into the jars directory of component B.

Once the prebind actions have completed, the B component bound to the workspace.

Component A is bound last.

Eclipse receives a lot of events and thus, rebuilds the workspace.

Note that the tada-sax (i.e. D) was never bound to the workspace since it is not an Eclipse project.