Ant actor API (Buckminster)

Argument passing

Buckminster passes two types of arguments to the Ant actor:

• Actor properties
• Regular properties
• Path groups

Actor properties

The actor properties controls the way the actor executes. The actor properties are declared in the <actorProperties> element. At present, the ant actor supports three actor properties:

Property	Meaning
targets	A comma separated list of ant targets to execute
buildFile	The project relative path to the build script
buildFileId	The id of a build script registered using the org.eclipse.buckminster.ant.buildScripts extension point.

Regular properties

These properties are sent verbatim to the script. The regular properties are declared in the <properties> element. Declaring a regular property is equivalent to using a -DpropKey=propVal when doing Ant command line invocations.

Path groups

A CSPEC attribute can be expressed as zero or many path groups. A path group has a base and zero to many <path> elements that are relative to that base. The base is always a directory. The relative paths denote directories or files.

An action that has no product is an example of an attribute that has zero path groups. An action will typically produce one path group but since attributes can be grouped, it's not uncommon that an attribute has several path groups, all with different base.

The prerequisites of an action are references to attributes. The Ant actor considers them to be named path groups. Each prerequisite has a default name associated with it and that name can be overridden using an alias.

The default name is for the prerequisites clause as a whole is:

buckminster.requirement.<action name>

and for each prerequisite listed in that clause:

buckminster.requirement.<action name>.<component identifier>#<attribute name>

Buckminster will convert the list of named path groups into properties. The string representation of a path group looks like this:

?<base>[<path sep><path>[<path sep><path>...]]

The paths and the <path sep> character are in their operating system dependent format.

An attribute that consists of several path groups will be represented by a property that consists of several concatenated path group string representations.

Buckminster will potentially create two properties for each prerequisite and use a namespace in order to distinguish between the two. The property that contains the path groups lives in the namespace fs and is mandatory. When a prerequisite evaluates to exactly one path group and that path group has zero or one path, Buckminster will also create a singleton property that appoints that path. This property lives in the namespace sp.

Example: Let's assume that a CSPEC has an artifact named "feature.xml". An action will use this attribute as a prerequisite with alias "feature.manifest".

First Buckminster creates the "fs:feature.manifest" property. It will contain "?/home/bob/workspaces/org.someorg.somename/:feature.xml", i.e. a base (the component root) and in this case, one path (the relative path of the file).

Buckminster concludes that this prerequisite appoints one single thing so it will also create the property "sp:feature.manifest". This value of this property will be "/home/bob/workspaces/org.someorg.somename/feature.xml".

Using the fs: properties

Using the sp: prefixed properties should be strigth forward, but how can I use the fs: properties in my Ant script?

Buckminster includes a set of ant tasks and types that makes this possible:

Type	Description
buckminster.valuefileset	A special Ant "fileset" that can be initialized from an fs: property. For the example above, it would use value="${fs:feature.manifest}"
buckminster.valuepath	A special Ant "path" that can be initialized from an fs: property.
buckminster.filesetgroup	Represents a group of filesets, each with different base. Can be initialized from an fs: property.

Buckminster also provides a specialization of most tasks that are able to take multiple nested <fileset> elements so that they can use a <buckminster.filesetgroup> element. The list of tasks include copy, delete, executeOn, jar, and zip and the type path. Simply prefix them with buckminster.[[Category:Buckminster Technical Reference]