[
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.