Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Eclipse b3/proposals/Unit Syntax
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.
Contents
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 ] '}' ; <pre> This mimics a java class. Example: <pre> 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];