Re: [buckminster-dev] some questions on Buckminster

[Thomas Hallgren <thomas@xxxxxxx>]

Hi Alex,
no wiki on the build system just yet. I wrote a long reply on this 
specific topic on our other newsgroup (buckminster) to Edwin Park 
(included below). I'll try and find some time to formalize this and put 
it up there as soon as possible.

- thomas

Alex Chen wrote:
> Hi Thomas,
>
> - the build error on Buckminster due to I haven't install RCP 
> delta-pack, I will try it soon
> - from the "hello xml world" demo, I see some properties from 
> build.xml in project org.demo.worlds:
>
> ****************
> <project name="org.demo.worlds">
>     <target name="java.binary.archives">
>         <dirname property="output.dir" file="${sp:output}"/>
>         <buckminster.valuefileset id="input.fileset" 
> value="${fs:input}"/>
>         <mkdir dir="${output.dir}"/>
>         <jar destfile="${sp:output}">
>             <fileset refid="input.fileset"/>
>         </jar>
>     </target>
> </project>
> ****************
>
> Is there any wikis on the meaning of ${sp:output} or ${fs:input}, I 
> can guess what they do in building process, but I think it should have 
> some documents on them.
In general, Buckminster will use two naming conventions for those 
properties.

sp:<property name> means "Single Property", i.e. a path or a file.
fs:<property name> a "File Set" or a group of such sets (see below).

I'll give you an example from the auto-generated cspec of our 
org.eclipse.buckminster.pde bundle. It contains an action that creates 
the actual bundle jar file that looks like this:

<cs:public name="bundle.jar" actor="ant">
 <cs:actorProperties>
   <cs:property key="buildFileId" value="buckminster.pdetasks"/>
   <cs:property key="targets" value="create.bundle.jar"/>
 </cs:actorProperties>
 <cs:prerequisites>
    <cs:attribute name="manifest" alias="manifest"/>
    <cs:attribute name="jar.contents" alias="action.requirements"/>
 </cs:prerequisites>
 <cs:products alias="action.output" base="${buckminster.output}/jar/" 
fileCount="1" upToDatePolicy="COUNT"/>
</cs:public>

Here's the same thing broken into separate lines with each line explained.

<cs:public name="bundle.jar" actor="ant">

The action is public, i.e. it can be referenced as an attribute from 
other cspecs and you can execute this action from Buckminster. A private 
action is only reachable from other attributes (groups or actions) 
within the same cspec. The name of this action is "bundle.jar" and it 
will be executed by the Buckminster "ant" actor.

 <cs:actorProperties>
   <cs:property key="buildFileId" value="buckminster.pdetasks"/>
   <cs:property key="targets" value="create.bundle.jar"/>
 </cs:actorProperties>

The actorProperties are specific to the chosen actor, in this case 
"ant". This actor needs a build file or a buildFileId. The latter is an 
ID of a build file provided by a plugin that extends the Buckminster 
extension point "org.eclipse.buckminster.ant.buildScripts". The 
"buckminster.pdetasks" build file is provided by the 
org.eclipse.buckminster.pde plug-in. The ant actor also optionally 
expects a "targets" definition, i.e. the targets to execute as a comma 
separated list in order of execution. This property is optional and will 
default to the name of the action.

 <cs:prerequisites>
    <cs:attribute name="manifest" alias="manifest"/>
    <cs:attribute name="jar.contents" alias="action.requirements"/>
 </cs:prerequisites>

This is the input to the action and probably the thing that you would be 
most interested in since it appoints everything that this action is 
dependent on (in this cspec or in cspecs that are referenced through 
dependencies). In this case, the prerequisites are local to the cspec.

Note that each attribute has an alias. This will become the name that 
can be used from ant. The following properties will be avialiable:

sp:manifest
fs:manifest
fs:jar.contents

The manifest will be available as both a "single property" and as a 
"file-set" since it is one single file. The jar.contents however, will 
only be available as a file-set since it cannot be represented as a 
single property.

 <cs:products
   alias="action.output"
   base="${buckminster.output}/jar/"
   fileCount="1"
   upToDatePolicy="COUNT"/>

This defines the products that this action will create and where they 
will end up. The base is important and integral to how file-sets are 
constructed when this actions is a prerequisite to other actions. A flat 
list of paths is often insufficient. In case you want to compile 
something or create a zip file, you often need a base and a set of files 
extending from that base. Sometimes, an action has several prerequisites 
that uses different base settings. That is the reason why Buckminster 
introduces something called a "file-set group".

The product also contains an upToDatePolicy that defines how buckminster 
decides if the action needs to be executed or not. In this case, the 
policy says that if the product contains at least one file and if all 
files are found to be younger then the youngest file in the 
prerequisites, then the action is up to date.

Now, let's take a look what happens in Ant. The current definition looks 
like this:

<target name="create.bundle.jar">
 <extractBundleVersion file="${sp:manifest}" property="bundle.version"/>
 <extractBundleId file="${sp:manifest}" property="bundle.id"/>
 <mkdir dir="${sp:action.output}"/>
 <buckminster.jar
   jarfile="${sp:action.output}/${bundle.id}_${bundle.version}.jar"
   manifest="${sp:manifest}" duplicate="preserve">
     <buckminster.filesetgroup value="${fs:action.requirements}"/>
 </buckminster.jar>
</target>

The buckminster.jar is an extension to the normal ant 'jar' task. The 
only difference is that the buckminster.jar knows how to transform a 
Buckminster filesetgroup into several filesets. Instead of 
buckminster.jar, we could have used just 'jar' if we were certain that 
the prerequisite contained only one file-set, i.e.:

 <jar
   jarfile="${sp:action.output}/${bundle.id}_${bundle.version}.jar"
   manifest="${sp:manifest}" duplicate="preserve">
     <buckminster.valuefileset value="${fs:action.requirements}"/>
 </buckminster.jar>
</target>

The buckminster.valuefileset simply transforms an fs:<xxx> property into 
a normal ant fileset.

If you want more examples, I suggest that you take a look at how 
Buckminster is building itself. In order to get started, you can take 
the following steps:

1. Create a target platform that contains the Eclipse 3.3.1.1 IDE and 
the RCP delta-pack.
2. Install Buckminster with support for maven, svn, cvs, and pde.
3. Open the cquery at 
http://www.eclipse.org/buckminster/samples/queries/buckminster-dev.cquery
4. Run resolve and materialize form the cquery editor.

This should get all relevant Buckminster source into your workspace. The 
ant buildscript that the pde provides through the extensionpoint can be 
found in the source package org.eclipse.buckminster.pde.antscripts in 
the plug-in org.eclipse.buckminster.pde.

A right-click on any of the projects in the workspace followed by 
"Buckminster" -> "View cspec..." will reveal Buckminsters view of that 
component.

The hard coded cspec found in the org.eclipse.buckminster.update project 
might be of special interest to you since it has actions that use 
prerequisites from many other components. Other fairly advanced uses of 
the ant actor can be found in the cspec of the top level component 
org.eclipse.buckminster and the ant build scripts under the make folder.

Lot of words. I hope some of it made sense to you. I'll try to get it 
all structured and incorporated into our docs pretty soon.