Latest revision as of 15:28, 19 April 2010

This information is dated. Please visit the b3 website for the latest information http://www.eclipse.org/modeling/emft/b3/

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
    : [ 'meta' ] simple-requires-statement
    ;

simple-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 ] '}'
    | [  'immutable' ] 'property identifier '=' property-expr ';'
    ;

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 foo.bar = 10;
immutable property myName = "fred";

Part Statement

part-statement
    : visibility  part
    ;

visibility : [ 'private' ]  ;

part
    : artifacts-statement
    | group-statement
    | action-statement
    | derived-statement
    ;

Artifacts Statement

artifacts-statement
    : 'artifacts' identifier '{' path-group-list '}'
    ;

artifacts-body
    : path-group-list
    | artifacts-body-statements
    ;

artifacts-body-statements
   : artifacts-body-statement
   | artifacts-body-statements artifact-body-statement
   ;

artifacts-body-statement
   : 'paths' '{' path-group-list '}'
   | provides-statement
   ;

path-group-list
    : path-group
    | path-group-list path-group
    ;

path-group
    : base-path '[' path-list ']' ';'
    | path-list ';'
    ;

path-list
    : path
    | path-list ',' path 
    ;

base-path : path ;

path
     : unquoted-safe-string
     | quoted-string
     ;

The syntax allows for very compact specification if paths do not contain special characters. If they do (syntax markers, or spaces) they must be quoted. Since artifacts can declare that they provide capaiblities in a namespace, a more elaborate syntax is needed where paths become a separate compound statement. A base path, is simply a path followed by an array of paths. The array is not required if the base path is empty. Examples:

artifacts source {
     src/x.xxx, src/y.xxx;
    src [x.xxx, y.xxx];
    "source and stuff" [ x.xxx, "complicated name.doc"];
}
artifacts source {
    paths {
        src/x.xxx, src/y.xxx;
        src [x.xxx, y.xxx];
        "source and stuff" [ x.xxx, "complicated name.doc"];
    }
   provides java.package org.myorg.x 1.2.0;

Group Statement

group-statement
    : ['preserved'] 'group' identifier '{' group-body '}'
    ;

group-body
    : properties-statement
    | advice-statement
    | required-statement
    ;

// properties as shown earlier
// advice as shown elsewhere

required-statement
    : 'required' [ 'when' filter-expr ] '{' required-body '}' [ 'with' '{' required-options '}' ]
    ;

required-body
    : 
    | body-statement
    | required-body body-body-statement
    ;

    : properties-statement
    | advice-statement
    | 
    ;

required-options
    | required-option ';'
    | required-options required-option
    ;

required-option 
    : 'rebase' '=' path
    | 'includePattern' '=' pattern
    | 'excludePattern' '=' pattern
    ;

Filter Expression

Discuss - how to express filters.

• OSGi syntax sucks (lisp style)
• want OSGi type predicates to retain semantics - i.e. identifier and wildcard
• want java/c style for not, and, or and parentheses

filter-expr
    : predicate
    | '(' filter-expr ')'
    | filter-expr '&&' filter-expr
    | filter-expr '||' filter-expr
    | '!' filter-expr
    ;

predicate
    : property-name '~=' quote regexp-pattern quote
    | property-name '==' identifier
    | property-name '==' identifier-with-wildcard
    ;