[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [buckminster-dev] some questions on Buckminster

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.