Revision as of 19:54, 8 October 2009

While attempting to construct a full build unit by using advice, several things became clear:

• The advice mechanism is powerful, but since it is general, more typing is required than what is really necessary
• Noice/Signal ratio is quite bad
• User needs to have an understanding of the model to do anything
• The model can not be simplified too much

Conclusion - the unit must really have a full syntax description.

Unit Syntax

Using [ ] to mean an optional part.

Unit Declaration

unit-name : identifier;
namespace : identifier;
capability-name : identifier;
version : string;
version-range : // defined by omni version range

unit-statement
    : 'unit' [ unit-name ] ['implements' namespace] [ version ] unit-body
    ;

unit-body
    : '{' [ unit-statements ] '}'
    ;

This mimics a java class. Example:

unit org.myorg.foo implements osgi.bundle {
    // ...
}

unit org.morg.foo implements eclipse.feature version 1.2.3 {
}

Since the same syntax is used to extend already generated build unit meta data, the unit's name, namespace and version are optional. If stated, they override the basic meta data translation. A component that does not have any other meta data must naturally declare enough to make the result be a valid build unit.

unit implements osgi.bundle {
    //...
]

Would only modify the namespace.

Unit Statements

unit-statements
    : unit-statement
    | unit-statements unit-statement
    ;

unit-statement
    : provided-statement
    | required-statement
    | properties-statement
    | part-statement
    ;

Capabilities

Provided Capabilities

The default provided capability - i.e. that the build unit is a build unit, is implicit and does not have to be declared, and it can not be extended in any way. The build unit may define provided capabilities at the root, but capabilities can also be declared in the parts (thus making it easier to remember to handle them as parts are added or removed). The build units total collection of provided capabilities is the sum of the self reference, the capabilities declared in general for the unit, and capabilities provided by parts.

provides-statement
    : 'provides' '{' capability-list '}'
    | 'provides' capability
    ;
capability-list
    : capability
    | capability-list capability
    ;
capability
    : namespace  capability-name [ version ] ';'
    ;

Examples:

provides {
    java.package org.myorg.foo;
    java.package org.myorg.bar 1.2.0;
}
provides java.package org.myorg.fee 3.0.0;

Required Capabilities

The build unit may define required capabilities at the root, but required capabilities can also be declared in the parts (thus making it easier to remember to handle them as parts are added or removed). The build units total collection of required capabilities is the sum of the required capabilities declared in general for the unit, and capabilities required by parts.

requires-statement
    : 'requires' '{' rcapability-list '}'
    | 'requires' rcapability
    ;
rcapability-list
    : rcapability
    | rcapability-list rcapability
    ;
rcapability
    : namespace  capability-name [ version-range ] ';'
    ;

Examples:

requires {
    java.package org.myorg.foo;
    java.package org.myorg.bar [1.2.0, 2.0.0);
}
requires java.package org.myorg.fee [3.0.0, 4.0.0];

Properties Statement

The build file can define properties, set their values, and declare if they are imutable.

properties-statement
    : 'properties' '{' [ property-list ] '}'
    ;

property-list 
    : property-spec ';'
    | property-list  property-spec
    ;

property-spec
    : [ 'immutable' ] identifier '=' property-expr
    ;

property-expr
    : string-value
    | numeric-value
    | boolean-value
    | function
    ;

The 'immutable' keyword will flag redefinition of the property as an error.

Examples:

properties {
    org.myorg.special = true;
    immutable org.myorg.specialvalue=42;
    immutable myName = "Fred";
}

Property-statements can be named for reuse purposes. The same semantics as for advice applies.