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.
Difference between revisions of "Buckminster component meta-data language 1.0 (Reference)"
(→Public/Private Actions) |
(→Provider component) |
||
Line 297: | Line 297: | ||
'''readerType="xs:string"''' | '''readerType="xs:string"''' | ||
'''componentTypes="xs:string"''' | '''componentTypes="xs:string"''' | ||
− | + | resolutionFilter="xs:string" ? | |
− | + | ||
mutable="xs:boolean" ? | mutable="xs:boolean" ? | ||
source="xs:boolean" ? > | source="xs:boolean" ? > | ||
Line 365: | Line 364: | ||
The specified ''componentTypes'' may include a custom type which must be declared using the Buckminster <code>org.eclipse.buckminster.core.componentTypes</code> extension point. The [[Extending Buckminster with a custom component type]] document explains how this can be done. | The specified ''componentTypes'' may include a custom type which must be declared using the Buckminster <code>org.eclipse.buckminster.core.componentTypes</code> extension point. The [[Extending Buckminster with a custom component type]] document explains how this can be done. | ||
|- valign="top" | |- valign="top" | ||
− | | | + | | resolutionFilter |
| xs:string | | xs:string | ||
− | | | + | | a filter in LDAP string format |
− | + | | A filter that will discriminate the provider if it evaluates to false using properties that is in effect during CQUERY evaluation. | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | | | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
|- valign="top" | |- valign="top" | ||
| mutable | | mutable |
Revision as of 07:38, 27 August 2008
< To: Buckminster Project
In order to increase navigability of the specification it is suggested that the reader enables "Auto-number headings" in his Wiki account Preferences > Misc
Contents
- 1 Introduction
- 2 Language components
- 3 RMAP (Resource Map)
- 3.1 RMAP pseudo-schema
- 3.2 Rmap component
- 3.2.1 SearchPath component
- 3.2.1.1 Provider component
- 3.2.1.1.1 Provider Matcher component
- 3.2.1.1.1.1 Provider Match component
- 3.2.1.1.1.2 Provider Group component
- 3.2.1.1.1.3 =Provider Group Name component=
- 3.2.1.1.1.4 =Provider Version Name component=
- 3.2.1.1.1.5 =Provider Group Timestamp component=
- 3.2.1.1.1.6 =Provider Group Revision component=
- 3.2.1.1.1.7 =Provider Group Os component=
- 3.2.1.1.1.8 =Provider Group Ws component=
- 3.2.1.1.1.9 =Provider Group Arch component=
- 3.2.1.1.1.10 =Provider Group Nl component=
- 3.2.1.1.2 Uri component
- 3.2.1.1.3 Provider Digest component
- 3.2.1.1.4 VersionConverter component
- 3.2.1.1.1 Provider Matcher component
- 3.2.1.1 Provider component
- 3.2.2 Locator component
- 3.2.3 Redirect component
- 3.2.1 SearchPath component
- 3.3 RMAP sample
- 4 CQUERY (Component Query)
- 5 CSPEC (Component Specification)
- 5.1 CSPEC pseudo-schema
- 5.2 Cspec component
- 5.2.1 Dependencies component
- 5.2.2 Generators component
- 5.2.3 Artifacts component
- 5.2.4 Groups component
- 5.2.5 Actions component
- 6 CSPECX (CSPEC Extension)
- 6.1 CSPECX pseudo-schema
- 6.2 CspecExtension component
- 6.2.1 AlterDependencies component
- 6.2.2 AlterArtifacts component
- 6.2.3 AlterGroups component
- 6.2.4 AlterActions component
- 6.2.4.1 Public/Private AlterActions
- 6.2.4.1.1 AlterActions AlterInstallerHints component
- 6.2.4.1.2 AlterActorProperties component
- 6.2.4.1.3 AlterActions AlterProperties component
- 6.2.4.1.4 AlterPrerequisites component
- 6.2.4.1.4.1 AlterPrerequisites AlterInstallerHints component
- 6.2.4.1.4.2 =Remove component=
- 6.2.4.1.4.3 AlterPrerequisites AlterAttribute component
- 6.2.4.1.4.4 Remove component
- 6.2.4.1.4.5 AlterProducts component
- 6.2.4.1.4.6 =AlterProducts Public/Private=
- 6.2.4.1.4.7 ==AlterProducts Public/Private AlterInstallerHints component==
- 6.2.4.1.4.8 ===Remove component===
- 6.2.4.1.4.9 ==AlterProducts Public/Private RemovePath component==
- 6.2.4.1.4.10 =RemoveProduct component=
- 6.2.4.1.4.11 =RemovePath component=
- 6.2.4.2 Remove component
- 6.2.4.1 Public/Private AlterActions
- 7 BOM (Bill of Materials)
- 8 MSPEC (Materialization Specification)
- 9 Shared Language Concepts
Introduction
This document describes the conceptual model of the Buckminster 1.0 component meta-data language. The document is not a formal specification although it uses some of the terminology and structure required for W3C-style specifications.
This document is intended as a complete reference for those working with the various Buckminster artifacts at the XML representation level as well as contributors and consumers of Buckminster. A compressed description of the Buckminster 1.0 component meta-data language can be found in the primer. It focuses on the required or most used language artifacts and provides plenty of examples.
Background
Buckminster is a component resolution & materialization framework. Its purpose is to get software components for you and materialize them in a context of choice, typically a workspace or file system. This applies whether you are looking at what's available on your local machine, within your development organization or in the public open source cloud. Buckminster is an extensible meta-framework, comprising a component metadata language and a runtime.
The Buckminster component meta-data language allows the Buckminster framework to understand information expressed about components, their dependencies and their associated lifecycle actions. The language also allows users to express component queries and describe reusable component assemblies ready to be consumed via Buckminster.
Prefixes and Namespaces used in this document
The following namespaces and prefixes are used throughout the document. The same combinations will be used in the associated schemas as well unless specified otherwise.
Prefix | Namespace | Source | Schema |
---|---|---|---|
xs | http://www.w3.org/2001/XMLSchema | Defined in the W3C XML Schema specification (Part 1 & 2) | - |
com | http://www.eclipse.org/buckminster/Common-1.0 | Defined in the Buckminster meta-data language | common-1.0.xsd |
rm | http://www.eclipse.org/buckminster/RMap-1.0 | Defined in the Buckminster meta-data language | rmap-1.0.xsd |
cq | http://www.eclipse.org/buckminster/CQuery-1.0 | Defined in the Buckminster meta-data language | cquery-1.0.xsd |
cs | http://www.eclipse.org/buckminster/CSpec-1.0 | Defined in the Buckminster meta-data language | cspec-1.0.xsd |
md | http://www.eclipse.org/buckminster/MetaData-1.0 | Defined in the Buckminster meta-data language | metadata-1.0.xsd |
mpv | http://www.eclipse.org/buckminster/MavenProvider-1.0 | Defined in the Buckminster meta-data language | maven-provider-1.0.xsd |
BNF pseudo-schemas
Pseudo-schemas are used throughout the document to provide a compressed view of the elements and attributes for each language element. The pseudo-schemas use BNF-style conventions for attributes and elements:
- "?" denotes optionality (i.e. zero or one occurrences)
- "*" denotes zero or more occurrences
- "+" one or more occurrences
- "[" and "]" are used to form groups
- "|" represents a choice
Attributes are assigned a value which corresponds to their type which may be either based on the XML Schema data types or the Buckminster language. Prefixes indicate which applies. Elements with simple content are conventionally assigned a value which corresponds to the type of their content, as defined in the associated schema. In order to increase readability required attributes and elements are highlighted in bold.
<defined_element required_attribute_of_type_string="xs:string" optional_attribute_of_type_int="xs:int"? > <required_element /> <optional_element />? <one_or_more_of_these_elements />+ [ <choice_1 /> | <choice_2 /> ]* </defined_element>
The Buckminster component meta-data language has six parts each conforming to a specific Buckminster artifact type. Each language part or artifact type has a namespace associated with it which is mapped to a distinct schema (see Prefixes and Namespaces used in this document). This document assumes that pseudo-schemas given for a particular part will use their associated namespace as a default namespace (i.e. http://www.eclipse.org/buckminster/RMap-1.0 for RMAP). Elements declared in other namespaces and shared across the six language parts will be indicated using the namespace prefixes as listed above.
Note that attributes will never be prefixed as all Buckminster schemas declare the attributeFormDefault
to be unqualified
. Consult the W3C XML Schema recommendation for details on this (XML Schema Part 1).
Document structure
The main section of the document describes the six Buckminster artifact types which correspond to the six parts of the language. Each of those parts is addressed in a main section. Each of the main sections provides an XML instance example for each Buckminster artifact.
The document explains the conceptual model of Buckminster and refers to components of the Buckminster language each of which is mapped to an XML element information item. Complete BNF pseudo-schemas are given at the start of each part to illustrate those.
The individual element descriptions provide pseudo-schemas to a depth of one only. Each of those subsections provides an explanation of the component (or element) semantics as well as a table view of the attributes with explanations of the semantics of those attribute in the context of the Buckminster framework. More detailed descriptions are provided where necessary.
Language components
The Buckminster meta-data language 1.0 has six main components or artifact types. These artifacts are typically represented in distinct files which use the identifiers (i.e. RMAP, CQUERY) of the artifact types as file extensions. The Buckminster runtime enforces this convention with all file extensions expected to be lower case.
The modular structure of the language guarantees exchange and re-use of artifacts in different application scenarios and allows the development of targeted tools such as Buckminster editors and wizards.
RMAP (Resource Map)
A resource map is used when resolving a request for a component through Buckminster Component Query. It supports federated, parameterized and search-path based resolution of materializable components. A CQUERY appoints a URL identifying an RMAP for the resolution process. The resolution is federated because resolution can be delegated to another RMAP. It is parameterized as properties can be used as parameters in the search paths (e.g. like $HOME
, $CLOSEST_MIRROR
).
RMAP pseudo-schema
The following pseudo-schema provides an overview of the XML vocabulary used to describe a resource map. It is fully expanded with the exception of those components that are part of the Buckminster property model shared across all Buckminster artifacts. An XML style comment indicates where element syntax with regard to child elements is not fully expanded.
NOTE that the pseudo-schema is navigable. Each element links to the document section explaining the structure and semantics of the element.
<rmap> <documentation/> ? [ <property key="com:propertyKey" value="xs:string" mutable="xs:boolean" ? /> | <propertyElement> <!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--> </propertyElement> | <searchPath name="xs:string" > <provider readerType="xs:string" componentTypes="xs:string" componentType="xs:string" <!-- DEPRECATED --> managedCategories="xs:string" ? <!-- DEPRECATED --> mutable="xs:boolean" ? source="xs:boolean" ? > <documentation/> ? <matcher base="xs:string> [ <match name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <group name="xs:string" optional="xs:boolean"> [ <name name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <version name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <timestamp name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <revision name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <os name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <ws name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <arch name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <nl name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> | <match name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> ]* </group> ]+ </matcher> <uri> <!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--> </uri> <digest algorithm="xs:string" /> <versionConverter type="xs:string" > <transform toPattern="xs:string" toReplacement="xs:string" fromPattern="xs:string" fromReplacement="xs:string" > * </versionConverter> ? </provider> + </searchPath> | <locator pattern="xs:string" searchPathRef="xs:string" /> | <redirect pattern="xs:string" href="com:URL" /> ]* </rmap>
Navigate through the following sections if a non-expanded view of individual components is required.
Rmap component
The Rmap component is represented by an rmap
XML element information item which serves as the root element of a resource map artifact (that is a ".rmap" file). It is a container for optional SearchPath, Locator, Redirect, Property and PropertyElement components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by rmap.
<rmap> <documentation/> ? [ <property/> | <propertyElement/> | <searchPath/> | <locator/> | <redirect/> ]* </rmap>
The documentation
element may contain mixed content and should be used to provide contextual documentation of the RMAP and its contained elements. This applies whereever the documentation
element is shown in the Buckminster specification.
SearchPath component
A SearchPath provides a reusable pointer to an area that Buckminster will use during the component resolution and materialization process. A complete SearchPath definition expresses where to find things, how to read and interpret its location and content and how to get access to those.
The RMAP can contain any number of named SearchPaths. The defined SearchPaths are unrelated data items. Thus, the order in which they appear carries no implicit information and has no influence on how Buckminster interpretes them.
A SearchPath MUST CONTAIN one or more Providers. Buckminster consults those in the order in which they appear until the component resolution process succeeds with one of them. Buckminster WILL flag up an error when a component can not be found based on the information provided by a searchPath. NOTE that their may be multiple matching Providers for a particular component. In this case Buckminster will internally assign a "Provider score" which ranks those providers depending on how well they fit a set of component constraints that are embodied in AdvisorNodes defined for the ComponentQuery that Buckminster resolves. Two properties specifically contribute to this score: mutable and source. The preferences regarding those properties may be stated in an AdvisorNode and will contribute to the score and the resulting Provider ranking. Only if all Provider in a set are equally ranked, the order of appearance decides which will be picked: the first matching one.
The SearchPath component is represented by a searchPath
XML element information item. It is a container for required Provider components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by searchPath.
<rmap> <searchPath name="xs:string" > <provider/> + <documentation/> ? </searchPath> </rmap>
The searchPath
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of the searchPath MUST BE unique within the set of all searchPaths defined in an RMAP. The Buckminster resolution process MUST FAIL if duplicate names are used for searchPath in the same RMAP. |
Provider component
A Provider declares all information required to obtain a component of a specific type, from a specific location using a specific versioning scheme. The information declared by a Provider allows the Buckminster framework to dynamically instantiate and configure a component reader (enumerating and reading the content) for a particular component type (obtaining and translating dependency information) and a version converter that maps Buckminsters notion of a "version" (i.e. as expressed in a component query) to the corresponding "version selector" of the provider (such as branch name, change-number, timestamp, etc).
The Provider component is represented by a provider
XML element information item. It is a container for a required Uri and an optional VersionConverter components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by provider.
<rmap> <searchPath> <provider readerType="xs:string" componentTypes="xs:string" resolutionFilter="xs:string" ? mutable="xs:boolean" ? source="xs:boolean" ? > <documentation/> ? <matcher/> ? <uri/> <digest/> ? <versionConverter/> ? </provider> + </searchPath> </rmap>
The provider
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
readerType | xs:string | - | The readerType specifies the component reader that Buckminster should associate with this provider. The value of this attribute must specify the fully qualified name of a reader. The Buckminster framework provides reference implementations for the following reader types (details of the existing reader implementations can be found in Buckminster Component Readers). The attribute value that MUST BE used to reference those readers is highlighted in bold:
Consult the information for the format attribute of Uri to see examples of the format required to encode location and access details for each reader type. The specified readerType may be a custom reader which must be declared using the Buckminster |
componentTypes | xs:string | - | NOTE this replaces both managedCategories and componentType. The notion of category has been replaced by an extended notion of componentTypes. The attribute now takes a comma-separated list of componentTypes which also capture the semantics previously covered by categories.
The componentTypes are required to configure the required reader. A component type indicates to the reader which component structure and meta-data to expect for the declared Provider. This information is essential in order for Buckminster to extract component dependency information which Buckminster automatically translates into its own dependency format (CSPEC) which will then be used in the component resolution and materialization process. A component type must be referenced in this attribute by its fully qualified name. Buckminster provides reference implementations for the following component types with the associated attribute values as indicated:
The specified componentTypes may include a custom type which must be declared using the Buckminster |
resolutionFilter | xs:string | a filter in LDAP string format | A filter that will discriminate the provider if it evaluates to false using properties that is in effect during CQUERY evaluation. |
mutable | xs:boolean | true
false |
The mutable attribute specifies whether a Provider will provide mutable artifacts (this is typically the case for component readers of type cvs or svn) or whether its content cannot be edited and submitted back (examples would be maven, eclipse.platform, etc).
The value of this attribute must be considered with source attribute and the mutableLevel and sourceLevel attribute values specified on an AdvisorNode given with a RootRequest in a ComponentQuery. Together they contribute to an internally computed Provider score which allows to rank all matching Providers. In cases of equally ranked Providers the first one appearing in the list of matching Providers will be chosen. EXAMPLES:
|
source | xs:boolean | true
false |
Conceptually, the source attribute is similar to the mutable attribute. It allows to specify whether the Provider has content in source (i.e. cvs) or binary (i.e. maven) form.
The value of this attribute must be considered with mutable attribute and the mutableLevel and sourceLevel attribute values specified on an AdvisorNode given with a RootRequest in a ComponentQuery. Together they contribute to an internally computed Provider score which allows to rank all matching Providers. In cases of equally ranked Providers the first one appearing in the list of matching Providers will be chosen. EXAMPLES:
|
Provider Matcher component
A Matcher allows to define directives required to interprete common download pages as a provider indirection mechanism.
A large number of components (zip and tar.gz archives in particular) can be found on download pages which are reachable via a URL and contain a number of references to download URLs appointing the actual download files. Matcher together with Match and Group allows to define patterns to extract download URLs according to preset filters and/or to manipulate URLs to enable a direct download (i.e. to circumvent the need to select mirrors). Patterns will be defined using Match and Group components.
The Matcher component is represented by a matcher
XML element information item. It is a container for one or more Match and Group components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by matcher.
<rmap> <searchPath> <provider> <matcher base="xs:string" > [ <match/> | <group/> ]+ </matcher> </provider> </searchPath> </rmap>
The matcher
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
base | xs:string | - | A URL appointing the "download page" which will act as a provider. Patterns defined to extract download URL appointing archive files will be applied to the content obtained from base. |
Provider Match component
A Match is the most basic directive used within Matcher. It allows to define a pattern which must be matched by URLs contained in the content provided at the base URL appointed by the enclosing Matcher. The result of the pattern match can be assigned to a variable which is referenceable by other elements (i.e. Uri within the Provider context.
The Match component is represented by a match
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by match.
<rmap> <searchPath> <provider> <matcher> <match name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </matcher> </provider> </searchPath> </rmap>
The match
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression. |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
Provider Group component
A Group allows to declare a complex matching and filter directive used within Matcher. It allows to define a pattern and filters which are associate with specific component properties expressed in a file name (such as the target operating system, version, locale, etc). A Group defines pattern fragments which are combined into a complete pattern that in turn must be matched by URLs contained in the content provided at the base URL appointed by the enclosing Matcher. The result of the complete pattern match or invidually defined pattern fragments can be assigned to a variables which are referenceable by other elements (i.e. Uri within the Provider context.
The Group component is represented by a group
XML element information item. It is a container for zero to many Name, Version, Timestamp, Revision, Os, Ws, Arch, Nl and Match components. The non-expanded pseudo-schema shows the element and attribute information items contained by group.
<rmap> <searchPath> <provider> <matcher> <group name="xs:string" optional="xs:boolean" /> [ <name/> | <version/> | <timestamp /> | <revision/> | <os/> | <ws/> | <arch/> | <nl/> | <match/> ]* </group> </matcher> </provider> </searchPath> </rmap>
The group
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
=Provider Group Name component=
Name allows to define a pattern (fragment) matching the component name as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on component names.
The Name component is represented by a name
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by name.
<rmap> <searchPath> <provider> <matcher> <group> <name name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </group> </matcher> </provider> </searchPath> </rmap>
The name
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression.
Sample pattern: "[a-zA-Z0-9_-]+" |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
=Provider Version Name component=
Version allows to define a pattern (fragment) matching the component version as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on component versions.
The Version component is represented by a version
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by version.
<rmap> <searchPath> <provider> <matcher> <group> <version name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </group> </matcher> </provider> </searchPath> </rmap>
The version
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression.
Sample pattern: "([0-9]+\.)*[0-9]+" |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
=Provider Group Timestamp component=
A Timestamp allows to define a pattern (fragment) matching the a timestamp as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on timestamps.
The Timestamp component is represented by a timestamp
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by timestamp.
<rmap> <searchPath> <provider> <matcher> <group> <timestamp name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </group> </matcher> </provider> </searchPath> </rmap>
The timestamp
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression. |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
=Provider Group Revision component=
A Revision allows to define a pattern (fragment) matching the a revision number as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on revision numbers.
The Revision component is represented by a revision
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by revision.
<rmap> <searchPath> <provider> <matcher> <group> <revision name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </group> </matcher> </provider> </searchPath> </rmap>
The revision
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression. |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
=Provider Group Os component=
A Os allows to define a pattern (fragment) matching the operating system information as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on operating system information.
The Os component is represented by a os
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by os.
<rmap> <searchPath> <provider> <matcher> <group> <os name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </group> </matcher> </provider> </searchPath> </rmap>
The os
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression.
Sample pattern: "aix|linux|macosx|solaris|win32" |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
=Provider Group Ws component=
A Ws allows to define a pattern (fragment) matching the windowing system information as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on windowing system information.
The Ws component is represented by a ws
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ws.
<rmap> <searchPath> <provider> <matcher> <group> <ws name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </group> </matcher> </provider> </searchPath> </rmap>
The ws
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression.
Sample pattern: "carbon|gtk|motif|wpf|win32" |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
=Provider Group Arch component=
A Arch allows to define a pattern (fragment) matching the architecture information as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on architecture system information.
The Arch component is represented by a arch
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by arch.
<rmap> <searchPath> <provider> <matcher> <group> <arch name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </group> </matcher> </provider> </searchPath> </rmap>
The arch
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression.
Sample pattern: "ppc|x86|x86_64" |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
=Provider Group Nl component=
A Nl allows to define a pattern (fragment) matching the locale as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on locale information.
The Nl component is represented by a nl
XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by nl.
<rmap> <searchPath> <provider> <matcher> <group> <nl name="xs:string" optional="xs:boolean" pattern="xs:string" prefix="xs:string" suffix="xs:string" /> </group> </matcher> </provider> </searchPath> </rmap>
The nl
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}.
If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead. |
optional | xs:boolean | true
false |
Denotes if this part is optional or must be matched. |
pattern | xs:string | - | The pattern which will be applied to URLs in turn. It must be a valid regular expression.
Sample pattern: "en_GB|en_US" |
prefix | xs:string | - | A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
suffix | xs:string | - | A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters. |
Uri component
A Uri declares the address associated with the enclosing Provider. It must contain sufficient information such that the component reader is able to access and read information from the location. This typically includes location path, protocol and access details (user name and password).
The Uri component is represented by a uri
XML element information item. It is a container for optional Constant, Format, PropertyRef, Replace, Split, ToLower and ToUpper components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by uri.
<rmap> <searchPath> <provider> <uri format="xs:string" > [ <com:constant/> | <com:format/> | <com:propertyRef/> | <com:replace/> | <com:split/> | <com:toLower/> | <com:toUpper/> ] * </uri> </provider> </searchPath> </rmap>
The uri
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
format | xs:string | - | The value of this attribute encodes the access details required by the component reader. The specific format of this value depends on the component reader specified by the Provider in the SearchPath.
EXAMPLE: Assuming declaration of a cvs reader on a component type of eclipse-project a valid attribute value (valid in the sense that the Buckminster framework implementation can utilise it) would be " EXAMPLES FOR ALL COMPONENT READER TYPES:
|
Provider Digest component
A Digest ...
The Digest component is represented by a digest
XML element information item. The non-expanded pseudo-schema shows the attribute information items directly contained by digest.
<rmap> <searchPath> <provider> <digest algorithm="xs:string" > </digest> </provider> </searchPath> </rmap>
The digest
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
algorithm | xs:string | - | - |
VersionConverter component
A VersionConverter specifies how a component reader for a specific component type declared by the enclosing Provider should map between a simple version designator such as "3.1.0" and a version selector specific to the provider such as "main/3.1.0" (which can be based on branchname, tag, changenumber, or timestamp).
The VersionConverter component is represented by a versionConverter
XML element information item. It is a container for optional Transform components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by transform.
<rmap> <searchPath> <provider> <versionConverter type="xs:string" versionTypeype="xs:string" > <transform/> * </versionConverter> </provider> </searchPath> </rmap>
The versionConverter
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
type | xs:string | branch or tag | The value of this attribute specifies which type of version converter the component reader specified by the Provider should use. The conversion can be customized through declarations in the Transform enclosed by the VersionConverter.
The specified version converter type may be a custom type which must be declared using the Buckminster |
versionType | xs:string | string, triplet, or OSGi (this list might be extended) | The value of this attribute specifies what type of version this version converter will create. The default type is string. This value must be provided if you are using other
types of versions such as OSGi or triplet. |
Transform component
A Transform specifies how the conversion between a plain version ("3.1.0") and a version selector (i.e. "main/3.1.0") by the enclosing VersionConverter must be done. A sequence of Transforms details this bi-directional mapping process.
Transform defines substitution patterns via its attributes which facilitate the conversion/transformation.
The Transform component is represented by a transform
XML element information item. The non-expanded pseudo-schema shows the attribute information items for transform.
<rmap> <searchPath> <provider> <versionConverter > <transform toPattern="xs:string" toReplacement="xs:string" fromPattern="xs:string" fromReplacement="xs:string" /> </versionConverter> </provider> </searchPath> </rmap>
The transform
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
fromPattern | xs:string | - | fromPattern builds a pair with the attribute fromReplacement. This attribute pair describes the transformation from plain version strings to version strings as potentially required for use in a version selector (i.e. from "3.1.0" to "v3_1_0").
fromPattern MUST provide a regular expression. All fragments of a given plain version string that match the expression will be replaced with the replacement string provided as a value of fromReplacement. EXAMPLE (assuming two transforms):
|
fromReplacement | xs:string | - | fromReplacement builds a pair with the attribute fromPattern.
SEE DETAILED EXPLANATION FOR THE fromPattern ATTRIBUTE. |
toPattern | xs:string | - | toPattern builds a pair with the attribute toReplacement. This attribute pair describes the re-transformation of transformed version strings to the original plain versions (i.e. from "v3_1_0" to "3.1.0"). The information in these two attributes must exactly reverse the transformation specified in the fromReplacement/fromPattern attributes. The Buckminster framework enforces this requirement.
toPattern MUST provide a regular expression. All fragments of a given transformed version string that match the expression will be replaced with the replacement string provided as a value of toReplacement. EXAMPLE (assuming the two transforms as specified in the example for fromPattern):
|
toReplacement | xs:string | - | toReplacement builds a pair with the attribute toPattern.
SEE DETAILED EXPLANATION FOR THE toPattern ATTRIBUTE. |
Locator component
A Locator acts as a pointer to a SearchPath (defined in the enclosing Rmap) for component requests matching a specified component name pattern. A Locator is used by the Buckminster framework in the component resolution process triggered by a component request. Those requests may originate directly from a CQUERY or from CSPECs which may be resolved recursively as part of the former.
The framework will consult the Locators (and Redirects) in order to find the search path holding the information to analyse and obtain the components required to resolve a component query. An Rmap may specify multiple Locators (and Redirects). Each of those will specify a pattern that the framework component resolver will match against the name of the queried component.
NOTE that the resolver will traverse the Locators (and Redirects) in the order in which they appear in the Rmap. Thus, the order of those should be from "more specific" to "least specific" with regard to the component name matching patterns they provide. The Buckminster component resolver MUST FAIL if no Locator (or Redirect) pattern matches the queried component.
NOTE that different locators in an Rmap may point to the same SearchPath.
The Locator component is represented by a locator
XML element information item. The non-expanded pseudo-schema shows the attribute information items for locator.
<rmap> <locator pattern="xs:string" searchPathRef="xs:string"/> </rmap>
The locator
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
pattern | xs:string | - | The value of this attribute MUST BE a regular expression representing a component name pattern which the Buckminster framework will use during the resolution process to match the name of a queried component.
If a component name matches the pattern specified by this attribute the Buckminster component resolver will attempt to obtain the required component information from the location(s) provided by the SearchPath with the name given in the Locator's |
searchPathRef | xs:string | - | Specifies the name of the search path (as given in a SearchPath's name attribute in the enclosing Rmap) that the Buckminster resolver should follow up during the component resolution process IF the name of the queried component is matched by the pattern provided in the Locator's pattern attribute.
NOTE that different locators in an Rmap may point to the same SearchPath. |
Redirect component
A Redirect acts as a pointer to an Rmap URL for component requests matching a component name pattern specified by the Redirect.
Redirect effectively works like an import for Locators, Redirects and SearchPaths in the appointed external Rmap. Just as a Locator, a Redirect is used by the Buckminster framework in the component resolution process triggered by a component request. Those requests may originate directly from a CQUERY or from CSPECs which may be resolved recursively as part of the former.
The framework will consult the Redirects (and Locators) in order to find the search path holding the information to analyse and obtain the components required to resolve a component query. An Rmap may specify multiple Redirects (and Locators). Each of those will specify a pattern that the framework component resolver will match against the name of the queried component.
A matched Redirect will essentially expand the list of Redirects and Locators in the current Rmap.
NOTE that the resolver will traverse the Redirects (and Locators) in the order in which they appear in the Rmap. Thus, the order of those should be from "more specific" to "least specific" with regard to the component name matching patterns they provide. The Buckminster component resolver MUST FAIL if no Redirect (or Locator) pattern matches the queried component.
NOTE that different redirects in an Rmap may point to the same Rmap URL.
The Redirect component is represented by a redirect
XML element information item. The non-expanded pseudo-schema shows the attribute information items for redirect.
<rmap> <redirect pattern="xs:string" href="com:URL" /> </rmap>
The redirect
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
pattern | xs:string | - | The value of this attribute MUST BE a regular expression representing a component name pattern which the Buckminster framework will use during the resolution process to match the name of a queried component.
If a component name matches the pattern specified by this attribute the Buckminster component resolver will be redirected to an external Rmap specified as a URL in the Redirect's |
href | com:URL | - | Specifies the URL of an external Rmap that the Buckminster resolver should follow up during the component resolution process IF the name of the queried component is matched by the pattern provided in the Redirect's pattern attribute.
NOTE that different redirects in an Rmap may point to the same external Rmap URL. |
RMAP sample
<?xml version="1.0" encoding="UTF-8"?> <rm:rmap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://www.eclipse.org/buckminster/RMap-1.0" xmlns:pv="http://www.eclipse.org/buckminster/Provider-1.0" xmlns:mp="http://www.eclipse.org/buckminster/MavenProvider-1.0" xmlns:bc="http://www.eclipse.org/buckminster/Common-1.0"> <rm:site name="default"> </rm:site> <rm:searchPath name="dash"> <rm:provider readerType="cvs" componentType="eclipse-project" mutable="true" source="true"> <pv:uri format=":pserver:anonymous@dev.eclipse.org:/cvsroot/technology,org.eclipse.dash/{0}"> <bc:property key="buckminster.component" /> </pv:uri> </rm:provider> </rm:searchPath> <rm:locator searchPathRef="dash" pattern="^org\.eclipse\.eclipsemonkey([\.\-].+)?" /> <rm:locator searchPathRef="dash" pattern="^org\.eclipse\.eclipsemonkey-feature" /> <rm:locator searchPathRef="dash" pattern="^org\.eclipse\.dash(\..+)?" /> <rm:locator searchPathRef="dash" pattern="^org\.mozilla\.rhino" /> </rm:rmap>
CQUERY (Component Query)
A component query is the top-level input to the Buckminster resolution and materialization process. A component query is captured by a Buckminster artifact (a .cquery file) of type CQUERY. It specifies a request to resolve (for materialization) a specific component version. A component query will name the required component, specify the version and versioning scheme and point to a resource map containing pointers to the locations of the required component and its dependent components.
A component query is a flexible reusable mechanism which allows federated component resolution. The same component request can for example be reused pointing to different resource maps for geographically distributed development teams.
The resolution and materialization mechanism can be customized through a flexible mechanism annotating the CQUERY with constraint sets captured through so-called "advisor nodes". A team may be working on different projects and in different phases. Each of those can be easily captured by a distinct CQUERY for scenario that the team wants to set up. Sharing component queries formalised in the Buckminster component meta-data language increases repeatability and reduces the introduction of unintended variability points.
CQUERY pseudo-schema
The following pseudo-schema provides an overview of the XML vocabulary used to describe a component query. It is fully expanded with the exception of those components that are part of the Buckminster property model shared across all Buckminster artifacts. An XML style comment indicates where element syntax with regard to child elements is not fully expanded.
NOTE that the pseudo-schema is navigable. Each element links to the document section explaining the structure and semantics of the element.
<componentQuery resourceMap="xs:string" ? properties="xs:string" ? shortDesc="xs:string" ? failOnResolveException="xs:boolean" ?> <documentation/> ? <rootRequest name="xs:string" category="xs:string" ? <!-- DEPRECATED --> componentType="xs:string" ? versionDesignator="xs:string" ? versionType="xs:string" ? > [ <property key="com:propertyKey" value="xs:string" mutable="xs:boolean" ? /> | <propertyElement> <!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--> </propertyElement> | <advisorNode namePattern="xs:string" category="xs:string" ? <!-- DEPRECATED --> componentType="xs:string" ? attributes="xs:string" ? prune="xs:boolean" ? mutableLevel="cq:Feasability" ? sourceLevel="cq:Feasability" ? allowCircularDependency="xs:boolean" ? skipComponent="xs:boolean" ? useInstalled="xs:boolean" ? useMaterialization="xs:boolean" ? useProject="xs:boolean" ? versionOverride="xs:string" ? versionOverrideType="xs:string" ? useResolutionScheme="xs:boolean" ? systemDiscovery="xs:boolean" ? <!-- NOT YET SUPPORTED --> branch="xs:string" ? <!-- NOT YET SUPPORTED --> resolutionPath="xs:string" ? /> <!-- NOT YET SUPPORTED --> <documentation/> ? [ <property key="com:propertyKey" value="xs:string" mutable="xs:boolean" ? /> | <propertyElement> <!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--> </propertyElement> ] * </advisorNode> ] * </rootRequest> </componentQuery>
Navigate through the following sections if a non-expanded view of individual components is required.
ComponentQuery component
The ComponentQuery is represented by a componentQuery
XML element information item which serves as the root element of a component query artifact (that is a ".cquery" file).
A ComponentQuery is a complete representation of a request for a top-level component to resolve or materialize. A ComponentQuery denotes
- the name of one queried component,
- the URL of an RMAP that should be used by the Buckminster framework for resolution and materialization,
- and an optional set of constraints or actions that should be observed during the process.
ComponentQuery is a container for a required RootRequest and optional AdvisorNode, Property and PropertyElement components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for ComponentQuery .
<componentQuery resourceMap="xs:string" ? properties="xs:string" ? shortDesc="xs:string" ? failOnResolveException="xs:boolean" ?> <documentation/> ? <rootRequest> [ <property/> | <propertyElement/> | <advisorNode/> ] * </componentQuery>
The componentQuery
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
resourceMap | xs:string | - | The value of this attribute MUST BE a URL referencing a Buckminster Resource Map (an .rmap file). If set the Buckminster framework will use the appointed RMAP when resolving a query captured by this component query and specified through its RootRequest.
NOTE that resourceMap is not a required attribute. IF no resource map is appointed the Buckminster resolver may revert to a local resolution (using existing projects, materializations, and the target platform) or remote resolvers (such as external sites essentially encoding and publishing map information). Custom resolvers are added through the |
properties | xs:string | - | The value of this attribute MUST provide a path or URL to a file defining properties in the standard Java properties syntax (PROPERTYKEY=VALUE). |
shortDesc | xs:string | - | The value of this attribute should provide a brief description of the ComponentQuery. It is intended as a digest of the full documentation item that might be provided in the artifact and could be used when displaying CQUERY artifacts in an external tool. If present it does not influence the Buckminster resolution and materialization process. |
failOnResolveException | xs:boolean | true
false |
DEPRECATED This concept still exists in Buckminster but its notion as a persisted property on a ComponentQuery has been abandoned. The failOnResolveException policy has to be set in the Buckminster Eclipse UI for every resolution that is started.
A value of false indicates that the resolution process should continue even if individual components can not be resolved; true forces an abortion of the resolution process on failure. |
RootRequest component
A RootRequest specifies the top-level component that Buckminster should resolve and/or materialize as part of ComponentQuery. There MUST BE exactly one RootRequest per component query as a query will always have one root component to resolve. This may trigger recursive resolution of further requests but one component can always be specified as the entry point for the Buckminster component resolver.
The RootRequest component is represented by a rootRequest
XML element information item. The non-expanded pseudo-schema shows the attribute information items for RootRequest. It does not contain any element information items.
<componentQuery> <rootRequest name="xs:string" category="xs:string" ? <!-- DEPRECATED --> componentType="xs:string" ? versionDesignator="xs:string" ? versionType="xs:string" ? /> </componentQuery>
The rootRequest
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The value of this attribute specifies the name of the component that must be resolved as part of the given component query (i.e. org.eclipse.buckminster.core ).
NOTE that the name may point to a virtual component which is an assembly of multiple physical (or virtual) components. |
category | xs:string | feature
plugin |
DEPRECATED !!!
NOTE that this attribute will be removed from future versions of the specification. Consult the documentation on the extended notion of componentTypes in the appropriate sections. The value of this attribute specifies a component category requirement that MUST BE observed by Buckminster when resolving the enclosing ComponentQuery. The notion of component categories allows to distinguish between components which are of the same name but fall in either the category feature or plugin. Together with the managedCategories attribute in Provider it essentially defines a filter on the usable providers. Through the specification of managedCategories the Provider can state that it can only handle requests for components of the specified category. The category attribute on RootRequest states that it will expect a certain component category from the Provider. We can distinguish the following scenarios:
Buckminster supports the two listed categories. Support for custom component categories can be added via the |
componentType | xs:string | - | NOTE that this attribute replaces the category attribute. Consult the documentation on the extended notion of componentTypes in the Provider section.
The value of this attribute specifies a component type requirement that MUST BE observed by Buckminster when resolving the enclosing ComponentQuery. Together with the componentTypes attribute in Provider it essentially defines a filter on the usable providers. Through the specification of componentTypes the Provider can state that it can only handle requests for components of the specified type. The componentType attribute on RootRequest states that it will expect a certain component type from the Provider. We can distinguish the following scenarios:
|
versionDesignator | xs:string | - | The value of this attribute specifies the requested version or range of versions of the component that the query should resolve. The versionDesignator is a string where each plain version in the range must follow the syntax as determined by the Buckminster versionType attribute.
A plain version string may not contain the characters '/', '#', or '@' as the presence of these indicates that it is a Version Selector (accessor to a component repository) and not a plain version (such as "3.1.0"). The version string is further restricted to not include the version designator delimiters '[' ']' '(' ')' or ','. The squared brackets denote inclusive ranges, the rounded brackets exclusive ranges. EXAMPLES:
|
versionType | xs:string | OSGi
String Timestamp Triplet |
The value of this attribute specifies which version format the plain versions in the versionDesignator have to conform to and what sorting mechanism would be applied to different versions. OSGi is the default version type.
Buckminster provides reference implementations for the four specified version types and provides an extension point |
AdvisorNode component
An AdvisorNode allows to specify a constraint or rule that will be applied by Buckminster throughout the resolution process that is triggered by the ComponentQuery for which the AdvisorNode is defined. It is a container for optional Property and PropertyElement components.
The resolution constraints expressed by the AdvisorNode will be applied to components which match the component name pattern defined by the AdvisorNode. A ComponentQuery can have any number of AdvisorNodes and the order in which they appear will be the order in which the Buckminster component resolver will try to match and consult them. Thus, with regard to their component name patterns AdvisorNodes should be ordered from most to least specific. The resolver will stop the search for an applicable AdvisorNode if a match is found. Therefore, all rules applicable to a component with a specific name pattern must be embodied in a single AdvisorNode.
NOTE that the constraints specified by AdvisorNodes are applicable at any level of the resolution process not just the top-level component specified in the RootRequest for a ComponentQuery.
The AdvisorNode component is represented by a advisorNode
XML element information item. The non-expanded pseudo-schema shows the attribute and element information items for AdvisorNode.
<componentQuery> <advisorNode namePattern="xs:string" category="xs:string" ? <!-- DEPRECATED --> componentType="xs:string" ? attributes="xs:string" ? prune="xs:boolean" ? mutableLevel="cq:Feasability" ? sourceLevel="cq:Feasability" ? allowCircularDependency="xs:boolean" ? skipComponent="xs:boolean" ? useInstalled="xs:boolean" ? useMaterialization="xs:boolean" ? useProject="xs:boolean" ? versionOverride="xs:string" ? versionOverrideType="xs:string" ? useResolutionScheme="xs:boolean" ? systemDiscovery="xs:boolean" ? <!-- ATTRIBUTE NOT YET SUPPORTED --> branch="xs:string" ? <!-- ATTRIBUTE NOT YET SUPPORTED --> resolutionPath="xs:string" ? > <!-- ATTRIBUTE NOT YET SUPPORTED --> [ <property/> | <propertyElement/> ] * </advisorNode> </componentQuery>
The advisorNode
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
namePattern | xs:string | - | The value of this attribute specifies a component name pattern in regular expression syntax (see Java Regular Expressions). It is the entry point for the Buckminster resolver when deciding whether the given AdvisorNode is applicable to the component currently being processed. |
category | xs:string | feature
plugin |
DEPRECATED !!!
NOTE that this attribute will be removed from future versions of the specification. Consult the documentation on the extended notion of componentTypes in the appropriate sections. The value of this attribute declares that components matching the namePattern must fall in the specified category. Specifically, the matched Providers must declare this category as part of their managedCategories or not specify managedCategories at all in which case they are considered to handle all categories.
|
componentType | xs:string | - | NOTE that this attribute replaces the category attribute. Consult the documentation on the extended notion of componentTypes in the Provider section.
The value of this attribute declares that components matching the namePattern must be of a particular component type. Specifically, the matched Providers must declare this component type as part of their componentTypes. |
attribute | xs:string | - | Requests that only parts of a component are of interest and that only dependencies for the corresponding attribute specified in the CSPEC for a component matching the namePattern are resolved by Buckminster. By default Buckminster would resolve all dependencies of a component.
EXAMPLE:
|
prune | xs:boolean | true
false |
When set to true Buckminster will perform a transitive dependency pruning on the component matching namePattern and all its dependant components. The pruning properties set in the CSPECs of components will control which dependencies will be pruned.
|
mutableLevel | cq:Feasability | INDIFFERENT
REJECT DESIRE REQUIRE |
The mutableLevel attribute has to be interpreted in connection with the mutable attribute specified by a Provider for a component that matches the namePattern of this AdvisorNode. A Provider can declare whether it will provide mutable artifacts (this is typically the case for component stores of type cvs or svn) or whether its content cannot be edited and submitted back (examples would be maven, eclipse.platform, etc).
In fact, the value of this attribute must be considered with the sourceLevel attribute and the source and mutable attribute values specified on an Provider in an Rmap. Together they contribute to an internally computed Provider score which allows to rank all matching Providers. In cases of equally ranked Providers the first one appearing in the list of matching Providers will be chosen. Depending on the value of the mutableLevel and sourceLevel attributes they may essentially provide a binary filter (i.e. as would be the case for REJECT or REQUIRE). Other combinations require to consider the mentioned Provider score and ranking. EXAMPLES:
|
sourceLevel | cq:Feasability | INDIFFERENT
REJECT DESIRE REQUIRE |
The sourceLevel attribute has to be interpreted in connection with the source attribute specified by a Provider for a component that matches the namePattern of this AdvisorNode. A Provider can declare whether it provides content in source (i.e. cvs) or binary (i.e. maven) form.
Furthermore, the explanation given for the mutableLevel attribute applies. |
allowCircularDependency | xs:boolean | false
true |
If set to false (the default) Buckminster will throw an error and fail the resolution process if it encounters a circular dependency on the component matching the namePattern. If set to true Buckminster will continue the resolution process despite circular dependencies and will ensure that a component is resolved only once.
|
skipComponent | xs:boolean | false
true |
If set to true the Buckminster resolver will skip the resolution of a component matching the namePattern. By default all components are resolved.
|
useInstalled | xs:boolean | true
false |
By default the resolution will use components that are installed as part of the target platform. This may however not always be appropriate. If set to false Buckminster will NOT USE installed components for components that match the namePattern.
EXAMPLE:
|
useMaterialization | xs:boolean | true
false |
Buckminster "remembers" all previous materializations (stored in the workspace meta-data) and will by default use those to resolve matching component requests. The value of this must be set to false if previous materializations should not be used for components matching the namePattern.
|
useProject | xs:boolean | true
false |
By default, Buckminster will resolve requests for components matching the namePattern using projects in the workspace. A project with a matching name will be considered a matching component. |
versionOverride | xs:string | - | Specifies a potential version string overriding other versions specified as required for components matching the namePattern. This must be a plain version, NOT a version designator. This attribute must be specified in conjunction with the versionOverrideType.
EXAMPLE:
|
versionOverrideType | xs:string | OSGi
String Timestamp Triplet |
The value of this attribute specifies which version format the plain version in the versionOverride is conforming to. OSGi is the default version type.
Buckminster provides reference implementations for the four specified version types and provides an extension point |
useResolutionScheme | xs:boolean | true
false |
Buckminster distinguishes between local and remote resolution schemes. By default the Buckminster resolver will use local resolvers (using target platform, workspace projects, previous materializations) unless a remote resolution scheme is appointed (i.e. by providing an RMAP URL in a ComponentQuery). If the value of this attribute is false Buckminster will not attempt a remote resolution otherwise it will.
|
systemDiscovery | xs:boolean | true
false |
ATTRIBUTE NOT YET SUPPORTED.
Eventually this will aid in a Buckminster feature that incorporates system specific information in the resolution process (addressing requirements for a particular OS, JVM, JBoss (which say must be installed and up and running), etc. |
branch | xs:string | - | ATTRIBUTE NOT YET SUPPORTED.
Eventually, this will aid in incorporating specific component branches independent of versions. |
resolutionPath | xs:string | - | ATTRIBUTE NOT YET SUPPORTED.
Eventually, this will aid in defining sequences of component namespaces which should be resolved in a given order. |
CSPEC (Component Specification)
CSPEC pseudo-schema
The following pseudo-schema provides an overview of the XML vocabulary used to describe a component specification. It is fully expanded with the exception of those components that are part of the Buckminster property model shared across all Buckminster artifacts. An XML style comment indicates where element syntax with regard to child elements is not fully expanded.
NOTE that the pseudo-schema is navigable. Each element links to the document section explaining the structure and semantics of the element.
<cspec name="xs:string" category="xs:string" <!-- DEPRECATED --> componentType="xs:string" ? version="xs:string" versionType="xs:string" shortDesc="xs:string" > <documentation/> ? [ <dependencies> <dependency name="xs:string" category="xs:string" ? versionDesignator="xs:string" ? versionType="xs:string" ?> <obtainedFrom attribute="xs:string" component="xs:string" /> ? </dependency> * </dependencies> | <generators> <generator attribute="xs:string" generates="xs:string" component="xs:string" ? /> * </generators> | <artifacts> [ <public name="xs:string" base="xs:string" ? path="xs:string" ? type="xs:string" ? > <documentation/> ? [ <installerHints> <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * </installerHints> | <path path="xs:string" /> ] * </public> | <private ... <!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /artifacts/public ... SEE ABOVE --> </private> ] * </artifacts> | <groups> [ <public name="xs:string" rebase="xs:string" ? > <documentation/> ? [ <installerHints> <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> </installerHints> | <attribute name="xs:string" component="xs:string" ? optional="xs:boolean" ? contributor="xs:boolean" ? /> ] * </public> | <private ... <!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /groups/public ... SEE ABOVE --> </private> ] * </groups> | <actions> [ <public name="xs:string" actor="xs:string" ? > <documentation/> ? [ <installerHints> <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * </installerHints> | <actorProperties> <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * </actorProperties> | <properties> <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * </properties> | <prerequisites rebase="xs:string" ? alias="xs:string" ? includePattern="xs:string" ? excludePattern="xs:string" ? > <documentation/> ? [ <installerHints> <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> </installerHints> | <attribute name="xs:string" ? component="xs:string" ? alias="xs:string" ? optional="xs:boolean" ? contributor="xs:boolean" ? /> ] * </prerequisites> | <products alias="xs:string" ? base="xs:string" ? upToDatePolicy="xs:string" ? filecount="xs:integer" ? pattern="xs:string" ? replacement="xs:string" ? > [ <path path="xs:string" /> | [ <public name="xs:string" ? base="xs:string" ? path="xs:string" ? type="xs:string" ? > <documentation/> ? [ <installerHints> <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> </installerHints> | <path path="xs:string" /> ] * </public> | <private ... <!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /actions/public/products/public ... SEE ABOVE --> </private> ] * ] * </products> ] * </public> | <private ... <!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /actions/public ... SEE ABOVE --> </private> ] * </actions> ] * </cspec>
Cspec component
The Cspec is represented by a cspec
XML element information item which serves as the root element of a component specification artifact (that is a ".cspec" file).
A Cspec is a complete representation of a component including all its dependencies, published sub-components and actions required to satisfy the dependencies and obtain the component.
Cspec is a container for a optional Dependencies, Generators, Artifacts, Groups and Actions components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Cspec.
<cspec name="xs:string" category="xs:string" version="xs:string" versionType="xs:string" shortDesc="xs:string" > <documentation/> ? [ <dependencies/> | <generators/> | <artifacts/> | <groups/> | <actions/> ] * </cspec>
The cspec
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of the component for which this component specification is given. This is the name a component is referred to for example in CQUERYs and RMAPs. NOTE that the version information is not part of the name, but is provided in a separate attribute. |
category | xs:string | feature
plugin |
DEPRECATED !!!
NOTE that this attribute will be removed from future versions of the specification. Consult the documentation on the extended notion of componentTypes in the appropriate sections. The value of this attribute specifies a component category that applies for this component. This component will be advertised both in an RMAP's Provider and may be required by the resolver when specified in a CQUERY's RootRequest. At current, the notion of component categories allows to distinguish between components which are of the same name but fall in either the category feature or plugin. |
version | xs:string | - | The value of this attribute specifies the version of this component as a plain version string. NOTE that this is a distinct version and not a version designator (or range). The syntax is determined by the versionType attribute. |
versionType | xs:string | OSGi
String Timestamp Triplet |
The value of this attribute specifies which version format the plain version string in the version attribute conforms to. OSGi is the default version type.
Buckminster provides reference implementations for the four specified version types and provides an extension point |
shortDesc | xs:string | - | The value of this attribute should provide a brief description of the Cspec. It is intended as a digest of the full documentation item that might be provided in the artifact and could be used when displaying CSPEC artifacts in an external tool. It is a purely informational item and does not influence the Buckminster resolution and materialization process. |
Dependencies component
The Dependencies component declares all dependencies of the component specified in this CSPEC.
Cspec is a container for one or many Dependency components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element information items for Dependencies.
<cspec> <dependencies> <dependency/> * </dependencies> </cspec>
Dependency component
The Dependency component declares a component dependency for the component defined in this CSpec. A dependency is declared with regard to components and may capture multiple prerequisite dependencies that is dependencies on specific Artifacts, Groups or Actions.
The semantics of the Dependency have to be interpreted exactly as ComponentQuery's RootRequest. The Buckminster resolver will have to interprete the dependency as a component request with the resolution context (the RMAP) being provided by the original ComponentQuery.
Dependency is a container for an optional ObtainedFrom component (!!!!!DEPRECATED!!!!! - consult Generators instead) which is represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Dependency.
<cspec> <dependencies> <dependency name="xs:string" category="xs:string" ? <!-- DEPRECATED --> componentType="xs:string" ? versionDesignator="xs:string" ? versionType="xs:string" ?> <obtainedFrom/> ? </dependency> </dependencies> </cspec>
The Dependency
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of a component that the component captured by this CSPEC depends on. |
category | xs:string | feature
plugin |
DEPRECATED !!!
NOTE that this attribute will be removed from future versions of the specification. Consult the documentation on the extended notion of componentTypes in the appropriate sections. Denotes a dependency on a component which belongs to the declared category. The notion of component categories allows to distinguish between components which are of the same name but fall in either the category feature or plugin. The semantics if this attribute have to be interpreted exactly as those of the attribute category in a CQUERY's RootRequest. |
componentType | xs:string | - | NOTE that this attribute replaces the category attribute. Consult the documentation on the extended notion of componentTypes in the Provider section.
Denotes a dependency on a component which is of the declared component type. The semantics if this attribute have to be interpreted exactly as those of the attribute componentType in a CQUERY's RootRequest. |
versionDesignator | xs:string | - | The value of this attribute specifies the requested version or range of versions of the component that the component depends on. The versionDesignator is a string where each plain version in the range must follow the syntax as determined by the versionType attribute.
The semantics if this attribute have to be interpreted exactly as those of the attribute versionDesignator in a CQUERY's RootRequest. A plain version string may not contain the characters '/', '#', or '@' as the presence of these indicates that it is a Version Selector (accessor to a component repository) and not a plain version (such as "3.1.0"). The version string is further restricted to not include the version designator delimiters '[' ']' '(' ')' or ','. The squared brackets denote inclusive ranges, the rounded brackets exclusive ranges. EXAMPLES:
|
versionType | xs:string | OSGi
String Timestamp Triplet |
The value of this attribute specifies which version format the plain versions in the versionDesignator have to conform to and what sorting mechanism would be applied to different versions. OSGi is the default version type.
The semantics if this attribute have to be interpreted exactly as those of the attribute versionType in a CQUERY's RootRequest.
Buckminster provides reference implementations for the four specified version types and provides an extension point |
ObtainedFrom component
!!!!!DEPRECATED!!!!! - consult Generators instead.
The ObtainedFrom component specifies a particular type of dependency where a component and its attributes have to be generated in order to become a referenceable Dependency.
ObtainedFrom allows to declare a Dependency on a component X which is obtained (i.e. generated) via an attribute y in a component Z. The enclosing Dependency would refer to X which would be qualified through the contained ObtainedFrom. NOTE that the dependencies would have to declare a dependency on Z as well.
The non-expanded pseudo-schema shows the attribute information items for Cspec.
<cspec> <dependencies> <dependency> <obtainedFrom attribute="xs:string" component="xs:string" /> </dependency> </dependencies> </cspec>
The obtainedFrom
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
attribute | xs:string | - | Specifies the name of the attribute from which the component declared in the enclosing Dependency can be obtained from. NOTE that the component that declares this attribute is specified in the component attribute. |
component | xs:string | - | Specifies the component which defines the attribute from which the component declared in the enclosing Dependency can be obtained from. |
Generators component
The Generators component declares all Generators applicable to this Cspec and the dependant component tree.
Generators is a container for one or many Generator components which are represented with correspondingly named XML element information items.
<cspec> <generators> <generator/> * </generators> </cspec>
Generator component
The Generator component has a similar purpose to the deprecated ObtainedFrom but removes its limitation with regard to the applicable scope.
The semantics of ObtainedFrom required that every dependant component in the dependency tree rooted from a given Cspec that shared the same dependency also had to explicitly declare where the component would be obtained from. Generator removes this limitation in that it extends the scope of its declaration ("downwards") to every dependant component in the dependency tree. Thus, the information of where/how a component is obtained must be declared only once. Other components requiring the component will only have to declare the Dependency. NOTE that conflicting Generator components in the same scope will result in an error during the Buckminster resolution process.
Assuming a component X has been specified as a Dependency in a given Cspec. Generator allows to declare that component X can be obtained (or generated) via an attribute y in a component Z. NOTE that the enclosing Cspec and all dependant ones would than only declare Dependencys on X and Z to allow a successful resolution.
The non-expanded pseudo-schema shows the immediate attribute information items for Generator.
<cspec> <generators> <generator attribute="xs:string" generates="xs:string" component="xs:string" ? /> </generators> </cspec>
The generator
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
attribute | xs:string | - | Specifies the name of the attribute from which the component specified in the generates attribute would be generated or obtained from.
NOTE that the component that declares this attribute is specified in the component attribute. If none is specified it is the assumed that the attribute is declared in the local/enclosing Cspec. |
generates | xs:string | - | Specifies the component which can be generated or obtained from the attribute in the specified component.
This generated component can be referenced as a Dependency' in given Cspec and all components in its dependency tree. |
component | xs:string | - | Specifies the component which defines the attribute from which the component declared in the generates attribute can be generated or obtained from. If this is not provided it is assumed that the attribute is defined in the enclosing Cspec. |
Artifacts component
The Artifacts component captures one of three approaches (the others are Groups and Actions) in Buckminster to declare reusable component attributes. Of those three approaches component attributes declared with Artifacts can be considered the atomic approach as they do not reference other attributes. The motivation behind this concept is that a component may need to specify a dependency on a particular part of a component rather than the component as a whole. A component attribute declared with Artifacts may for example specify a file or set of files (such as a binary contained in a component) or a folder or set of folders (to capture for example a set of header files in a component) or a combination of both.
NOTE that the Artifacts component serves as a container for zero or more artifact declarations with the declaration of a single artifact (component attribute) being rooted in a Public or Private component for which Artifacts serves as a container.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Artifacts.
<cspec> <artifacts> [ <public/> | <private/> ] * </artifacts> </cspec>
Public/Private Artifacts
Public and Private components contained in an Artifacts component represent the root of a component attribute declaration of type Artifacts. The structure of the Public and Private components is identical. The semantics differs in one point only.
- Public - a public attribute is accessible from within the local Cspec that contains this declaration as well as any other Cspec that references the local component specification as a dependency.
- Private - a private attribute declaration is accessible ONLY from within the local Cspec that contains this declaration.
Artifacts is a container for a optional InstallerHints and Path components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Artifacts.
<cspec> <artifacts> <public name="xs:string" base="xs:string" ? path="xs:string" ? type="xs:string" ? > <documentation/> ? [ <installerHints/> | <path/> ]* </public> </artifacts> </cspec>
The public
and private
elements have the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalized by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The unique name of this attribute declaration by which this and other component specifications can refer to the attribute in order use it. NOTE that a reference external to the containing Cspec will have to reference both the attribute and its containing component. |
base | xs:string | - | The path specifying the root path of artifacts included in this component attribute declaration. This is optional. If not specified the component root will be used as a default.
Specifying the path is of particular convenience if an attribute will consist of multiple resources in different locations but rooted at base. |
path | xs:string | - | The path is a path fragment interpreted relative to the base (the two are concatenated). This attribute represents a convenience mechanism with regard to the use of a path element. It covers the case where the component attribute declaration will only contain one resource (file or folder).
|
type | xs:string | - | - |
Artifacts InstallerHints component
The InstallerHints component captures information that must be interpreted in the context of Actions.
NOTE that - originating from a specific internal requirement - this is an evolving concept which provides a general purpose mechanism through the declaration of Propertys, the semantics of which are not further specified in the context of InstallerHints. An example for this concept would be an action which retrieves i.e. a set of header files specified by the enclosing component attribute declaration and needs to ensure that certain permissions are set on those files. This requirement would be captured by InstallerHints.
Artifacts is a container for zero or many Property components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element information items for InstallerHints.
<cspec> <artifacts> <public> <installerHints> <property/> * </installerHints> </public> </artifacts> </cspec>
Artifacts Path component
The Path component specifies the same information as the path attribute in the enclosing Public or Private components but will have to be used if a component attribute declaration will contain multiple resources. If for example a component attribute is declared which assembles header file from multiple folders each of those folders would have to be specified using a Path component.
The path information provided by the Path component will have to be interpreted relative to the base attribute (the two are concatenated) which is specified in the enclosing Public or Private components.
The non-expanded pseudo-schema shows the attribute information items for Artifacts.
<cspec> <artifacts> <public> <path path="xs:string" /> </public> </artifacts> </cspec>
The path
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
path | xs:string | - | The path is a path fragment interpreted relative to the base attribute (the two are concatenated) which is specified in the enclosing Public or Private components.
If a component attribute declaration specifies only one path the path attribute in the enclosing Public or Private components may be used for convenience. |
Groups component
The Groups component captures one of three approaches (the others are Artifacts and Actions) in Buckminster to declare reusable component attributes.
The Groups component provides a mechanism to group all types of reuseable component attributes. This includes Artifacts, Actions and Groups itself. The motivation behind this concept is that a component may need to specify a logical dependency on multiple reusable component artifacts and that common actions or transformations may have to be applied to this group before it becomes usable in a particular context.
NOTE that the Groups component serves as a container for zero or more group declarations with the declaration of a single group (component attribute group) being rooted in a Public or Private component for which Groups serves as a container.
The non-expanded pseudo-schema shows the immediate element information items for Groups.
<cspec> <groups> [ <public/> | <private/> ] * </groups> </cspec>
Public/Private Groups
Public and Private components contained in a Groups component represents the root of a component attribute group declaration of type Groups. The structure of the Public and Private components is identical. The semantics differs in one point only.
- Public - a public group is accessible from within the local Cspec that contains this declaration as well as any other Cspec that references the local component specification as a dependency.
- Private - a private group declaration is accessible ONLY from within the local Cspec that contains this declaration.
Artifacts is a container for a optional InstallerHints and Attribute components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Artifacts.
<cspec> <groups> <public name="xs:string" rebase="xs:string" ? > <documentation/> ? [ <installerHints/> <attribute/> ] * </public> </groups> </cspec>
The public
and private
elements have the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The unique name of this group declaration by which this and other component specifications can refer to the attribute in order to use it. NOTE that a reference external to the containing Cspec will have to reference both the group and its containing component. |
rebase | xs:string | - | Provides a folder path which overrides the base specified in the grouped attributes. NOTE that this must not result in a MOVE of the artifacts. This directive does only move the break point of base and path which may be required by certain action actors. |
Groups InstallerHints component
The InstallerHints components declared in Groups have the same structure as InstallerHints declared in Artifacts. Consult this definition for a description of the syntax and semantics.
Groups Attribute component
The Attribute component specifies a component artifact should be included in a group declared in Groups. It holds a reference to one of Artifacts, Groups or Actions.
The non-expanded pseudo-schema shows the immediate attribute information items for Attribute.
<cspec> <groups> <public> <attribute name="xs:string" component="xs:string" ? optional="xs:boolean" ? contributor="xs:boolean" ? /> </public> </groups> </cspec>
The attribute
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of Artifacts, Groups or Actions that should be included in the declared group. NOTE that this is the local name as specified in the appropriate declarations. For references to external attributes the component name will have to be specified in component. |
component | xs:string | - | The component which holds the attribute specified in name. |
optional | xs:boolean | true
false |
If true , a dependency on this group is still considered valid even if the dependency on this attribute is not. Otherwise the resolver would fail as any dependencies on this group would be considered invalid then.
|
contributor | xs:boolean | true
false |
Signals that this attribute may trigger an action which does however not produce anything or has any impact on the handled component artifacts. |
Actions component
The Actions component captures one of three approaches (the others are Groups and Artifacts) in Buckminster to declare reusable component attributes.
The Actions component describes resuseable component attributes of a dynamic type. Actions will typically be defined to produce final or intermediate stages of component parts (attributes) or whole components which will be utilized by the Buckminster framework during the component resolution process. An Actions is essentially a component handling behavior which can be dynamically plugged into the resolution process. There is a range of internal Actions provided by the Eclipse platform runtime. Others are external are typically embodied by ANT scripts or system commands. Buckminster is extensible with regard to the supported Actions.
NOTE that this can trigger quite complex flows as an Actions may reference other Artifacts, Groups or indeed Actions as Prerequisites.
Actions is a container for zero or many Public and Private components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element information items for Actions.
<cspec> <actions> [ <public> | <private> ] * </actions> </cspec>
Public/Private Actions
Public and Private components contained in an Actions component represent the root of a component attribute declaration of type Actions. The structure of the Public and Private components is identical. The semantics differs in one point only.
- Public - a public action is accessible from within the local Cspec that contains this declaration as well as any other Cspec that references the local component specification as a dependency.
- Private - a private action declaration is accessible ONLY from within the local Cspec that contains this declaration.
Public/Private are containers for a optional InstallerHints, ActorProperties, Properties, Prerequisites and Products which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Public and Private using Public as an example.
<cspec> <actions> <public name="xs:string" actor="xs:string" ? enabled="xs:boolean" ? > <documentation/> ? [ <installerHints/> | <actorProperties/> | <properties/> | <prerequisites/> | <products/> ] * </public> </actions> </cspec>
The public
and private
elements have the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The unique name of this action declaration by which this and other component specifications can refer to the action in order to use it. NOTE that a reference external to the containing Cspec will have to reference both the group and its containing component.
There is a number of internal (provided by the Eclipse runtime) or well-known (by Buckminster) actions which can be referenced:
|
actor | xs:string | ant | Buckminster currently supports one type of actor:
NOTE 1 that Buckminster's support for actors can be extended via the NOTE 2 others actors are currently being submitted as a proposal. |
Actions InstallerHints component
The InstallerHints components declared in Actions have the same structure as InstallerHints declared in Artifacts. Consult this definition for a description of the syntax and semantics.
ActorProperties component
The ActorProperties component serves as container for propertys which will be supplied for the specific actor defined in the enclosing Public or Private Actions. They provide the required context in order to allow the actor specified for and action to execute. (Also see Properties).
The non-expanded pseudo-schema shows the immediate element information items for ActorProperties.
<cspec> <actions> <public> <actorProperties> <property/> * </actorProperties> </public> </actions> </cspec>
Ant Actor
Currently, only ANT actors are supported.
The following actorProperties can be passed:
- 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.ant.buildScripts
extension point.
Those properties are supplied using the standard property component with the listed property names as keys.
For more informations please consult the ANT Actor API page.
Other actors proposal
Despites Buckminster proposes only ant actors for he moment, some other actors are studied as a proposal.
Actions Properties component
The Properties component component serves as container for Propertys which will be supplied for the specific actor defined in the enclosing Public or Private Actions.
Whereas ActorProperties specify the properties required to execute the actor (such as the script path), Properties specify the execution configuration. With the present support for Ant ,these match regular properties equivalent to using a -DpropKey=propVal when doing ANT command line invocations. These properties are sent verbatim to the actor script.
Those properties are supplied using the standard property component with the listed property names as keys.
The non-expanded pseudo-schema shows the immediate element information items for Properties.
<cspec> <actions> <public> <properties> <property/> * </properties> </public> </actions> </cspec>
Prerequisites component
The Prerequisites component summarizes all dependencies for the enclosing Public or Private Actions which will have to be satisfied in order for the action to be acted upon. This can trigger quite complex flows as an Actions may reference other Artifacts, Groups or indeed Actions as Prerequisites.
Prerequisites can also be interpreted as an inline group.
Prerequisites is a container for a one or many InstallerHints and Attribute components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Prerequisites.
<cspec> <actions> <public> <prerequisites rebase="xs:string" ? alias="xs:string" ? includePattern="xs:string" ? excludePattern="xs:string" ? > <documentation/> ? [ <installerHints> | <attribute/> ] * </prerequisites> </public> </actions> </cspec>
The prerequisites
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
rebase | xs:string | - | Provides a folder path which overrides the base specified in the Attribute group by the Prerequisites. NOTE that this must not result in a MOVE of the artifacts. This directive does only move the break point of base and path which may be required by certain action actors. |
alias | xs:string | - | Specifies an alias by which the actor can refer to the Prerequisites internally. This is only for the benefit of the actors specified in the enclosing Public/Private Actions and does NOT provide a reference that may be used anywhere else. |
includePattern | xs:string | - | A regular expression intended to define inclusion rules for component/attributes identifiers of the form <componentName>#<attributeName> . Based on the includePattern Actionsprerequisites supplied by the appointed attribute will be included if the match the pattern.
|
excludePattern | xs:string | - | A regular expression intended to define exclusion rules for component/attributes identifiers of the form <componentName>#<attributeName> . Based on the excludePattern Actionsprerequisites supplied by the appointed attribute will be excluded if they match the pattern.
This may be useful when i.e. defining a bundle for an update site where certain prerequisites may not have to be included when publishing to a site although they are required prerequisites. |
Prerequisites InstallerHints component
The InstallerHints components declared in Prerequisites have the same structure as InstallerHints declared in Artifacts. Consult this definition for a description of the syntax and semantics.
Prerequisites Attribute component
The Attribute component specifies a component artifact that is part of the Prerequisites declared for the enclosing Actions.
The non-expanded pseudo-schema shows the immediate attribute information items for Attribute.
<cspec> <groups> <public> <prerequisites> <attribute name="xs:string" component="xs:string" ? alias="xs:string" ? optional="xs:boolean" ? contributor="xs:boolean" ? /> </prerequisites> </public> </actions> </cspec>
The attribute
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of Artifacts, Groups or Actions that are part of those prerequisites. NOTE that this is the local name as specified in the appropriate declarations. For references to attributes in external Cspecs the component name will have to be specified in component. |
component | xs:string | - | The component which holds the attribute specified in name. |
alias | xs:string | - | If specified the alias provides a means for more fine-grained, focused references to Prerequisites in actor scripts (currently only Ant scripts). |
optional | xs:boolean | true
false |
If true , the prerequisites are still considered valid even if the dependency on this attribute is not. Otherwise the resolver would fail as any dependencies on the prerequisites would be considered invalid then.
|
contributor | xs:boolean | true
false |
If false , the referenced attribute will NOT be considered when calculating the "up to date policy".
|
Products component
The Products component describes the products of Actions. That is, the artifacts that an action will create. Products can be considered as "inlined artifacts". Products arrive in one of two forms:
- It may consist of one or several component attribute declarations. Referencing any of these artifacts triggers the associated prerequisites.
- Just a base and zero to many paths.
Products can be referenced as a prerequisites themselves and thus also control access: Products is a container for a EITHER one or many Path OR one or many Public and Private components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Products.
<cspec> <actions> <public> <products alias="xs:string" ? base="xs:string" ? upToDatePolicy="xs:string" ? filecount="xs:integer" ? pattern="xs:string" ? replacement="xs:string" ? > [ <path/> | [ <public/> | <private/> ]* ]* </products> </public> </actions> </cspec>
The products
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
alias | xs:string | - | Specifies an alias by which the actor can refer to the Products internally. This is only for the benefit of the actors specified in the enclosing Public/Private Actions and does NOT provide a reference that may be used anywhere else. |
base | xs:string | - | As the product is the result of an action the base can be interpreted as a target location. For references to the product it is interpreted (just as for other artifacts) as the root path of artifacts included in this component attribute declaration.
This is optional. If not specified the component root will be used as a default. |
upToDatePolicy | xs:string | DEFAULT
COUNT MAPPER NOT_EMPTY |
Defines how Buckminster should determine if the products are up to date with respect to the action prerequisites. The motivation behind this directive is that the number of actions that the Buckminster framework has to perform should be limited. In its simplest case a product specifies the target location (base) for an actor's output and if the location holds the expected resources the enclosing Public/Private Actions may not have to be executed. The upToDatePolicy specifies how Buckminster should compare the existing products against an action's Prerequisites.
The following policies can be chosen, some of which may require additional information:
NOTE that this is a convenience mechanism. External changes to the products may cause the applied upToDatePolicy to deliver an erroneous result. |
fileCount | xs:integer | - | Must be interpreted together with the upToDatePolicy if COUNT or MAPPER are specified as an up to date policy. |
pattern | xs:string | - | Must be interpreted together with the upToDatePolicy if MAPPER is specified as an up to date policy. |
replacement | xs:string | - | Must be interpreted together with the upToDatePolicy and pattern if MAPPER is specified as an up to date policy. |
Products Path component
The Path components declared in Products have the same structure as Path declared in Artifacts. Consult this definition for a description of the syntax and semantics.
Products Public/Private
Public and Private components contained in an Products component represent the root of a complex product declaration. The structure of the Public and Private components is identical. The semantics differs in one point only.
- Public - a public product is accessible from within the local Cspec that contains this declaration as well as any other Cspec that references the local component specification as a dependency.
- Private - a private product declaration is accessible ONLY from within the local Cspec that contains this declaration.
Public/Private are containers for one or many InstallerHints and Path which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Public and Private using Public as an example.
<cspec> <actions> <public> <products> <public name="xs:string" ? base="xs:string" ? path="xs:string" ? type="xs:string" ? > <documentation/> ? [ <installerHints/> | <path/> ] * </public> </products> </public> </actions> </cspec>
The public
and private
elements have the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The unique name of this product by which it can be referred to. NOTE that a reference external to the containing Cspec will have to reference both the attribute and its containing component. |
base | xs:string | - | The path specifying the root path of the product. If not specified the component root will be used as a default.
Specifying the path is of particular convenience if an attribute will consist of multiple resources in different locations but rooted at base. |
path | xs:string | - | The path is a path fragment interpreted relative to the base (the two are concatenated). This attribute represents a convenience mechanism with regard to the use of a path element. It covers the case where the component attribute declaration will only contain one resource (file or folder).
|
type | xs:string | - | - |
=Products Public/Private InstallerHints component=
The InstallerHints components declared in Products Public/Private have the same structure as InstallerHints declared in Artifacts. Consult this definition for a description of the syntax and semantics.
=Products Public/Private Path component=
The Path components declared in Public/Private Products Public/Private have the same structure as Path declared in Artifacts. Consult this definition for a description of the syntax and semantics.
CSPECX (CSPEC Extension)
CSPECX pseudo-schema
The following pseudo-schema provides an overview of the XML vocabulary used to describe a component specification extension. It is fully expanded with the exception of those components that are part of the Buckminster property model shared across all Buckminster artifacts. An XML style comment indicates where element syntax with regard to child elements is not fully expanded.
NOTE that the pseudo-schema is navigable. Each element links to the document section explaining the structure and semantics of the element.
NOTE that since the CSPEC Extension is based on the CSPEC it contains a large number of components of the CSPEC. They are not fully shown in the pseudo-schema. Instead an appropriate pointer to the CSPEC components is provided. The same is done in the sections below in order to avoid duplication of the component model reference.
<cspecExtension category="xs:string" version="xs:string" versionType="xs:string" shortDesc="xs:string" > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <dependencies/> | <generators/> | <artifacts/> | <groups/> | <actions/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterDependencies> [ <dependency/> * <!-- <<< INHERITED FROM CSPEC !!! --> | <remove name="xs:string" /> ] * </alterDependencies> | <alterArtifacts> [ <public name="xs:string" base="xs:string" ? path="xs:string" ? type="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> | <path/> ]* <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints> [ <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * | <remove key="xs:string" /> ] * </alterInstallerHints> | <removePath path="xs:string" /> ] * </public> | <private ... <!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /alterArtifacts/public ... SEE ABOVE --> </private> | <remove name="xs:string" /> ] * </alterArtifacts> | <alterGroups> [ <public name="xs:string" rebase="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> <attribute/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints> [ <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * | <remove key="xs:string" /> ] * </alterInstallerHints> | <alterAttribute name="xs:string" component="xs:string" ? optional="xs:boolean" ? contributor="xs:boolean" ? /> | <remove name="xs:string" /> ] * </public> | <private ... <!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /groups/public ... SEE ABOVE --> </private> | <remove name="xs:string" /> ] * </alterGroups> | <alterActions> [ <public name="xs:string" actor="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> | <actorProperties/> | <properties/> | <prerequisites/> | <products/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints> [ <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * | <remove key="xs:string" /> ] * </alterInstallerHints> | <alterActorProperties> [ <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * | <remove key="xs:string" /> ] * </alterActorProperties> | <alterProperties> [ <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * | <remove key="xs:string" /> ] * </alterProperties> | <alterPrerequisites rebase="xs:string" ? alias="xs:string" ? includePattern="xs:string" ? excludePattern="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> <attribute/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints> [ <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * | <remove key="xs:string" /> ] * </alterInstallerHints> | <alterAttribute name="xs:string" component="xs:string" ? optional="xs:boolean" ? contributor="xs:boolean" ? /> | <remove name="xs:string" /> ] * </alterPrerequisites> | <alterProducts> [ <path path="xs:string" /> | [ <public name="xs:string" ? base="xs:string" ? path="xs:string" ? type="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> <path/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints> [ <property value="xs:string" key="com:PropertyKey" mutable="xs:boolean" ? /> * | <remove key="xs:string" /> ] * </alterInstallerHints> | <removePath path="xs:string" /> ] * </public> | <private ... <!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /actions/public/products/public ... SEE ABOVE --> </private> | <removeProduct name="xs:string" /> | <removePath path="xs:string" /> ] * ] * </alterProducts> ] * </public> | <private ... <!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /actions/public ... SEE ABOVE --> </private> | <remove name="xs:string" /> ] * </alterActions> ] * </cspecExtension>
CspecExtension component
The CspecExtension is represented by a cspecExtension
XML element information item which serves as the root element of a component specification extension artifact (that is a "buckminster.cspex" file). NOTE that a CspecExtension is always associated with a component by including a "buckminster.cspex" file with the component.
The Buckminster framework will interprete the CspecExtension together with an automatically generated CSPEC. The extension mechanism will be particularly useful if Buckminster can only generate partial component specifications because of missing meta-data.
CspecExtension is a true extension of CSPEC and allows to both declare and alter (override and remove) CSPEC elements.
CspecExtension inherits all the container properties of Cspec component with regard to the elements. In addition, it is a container for one or many AlterDependencies, AlterArtifacts, AlterGroups and AlterActions components which are represented with correspondingly named XML element information items.
As a general rule the "Alter..." elements replicate the structure of their corresponding declaration elements in Cspec. They are associated with those declarations by specifying the names of those declarations they should alter - either by overriding them or by removing them altogether.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Cspec.
<cspecExtension category="xs:string" version="xs:string" versionType="xs:string" shortDesc="xs:string" > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <dependencies/> | <generators/> | <artifacts/> | <groups/> | <actions/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterDependencies/> | <alterArtifacts/> | <alterGroups/> | <alterActions/> ] * </cspecExtension>
The cspecExtension
element has the same attributes as Cspec with one exception: the name attribute is not inherited by the CspecExtension. A CspecExtension is identified not by name but only by component inclusion (via the "buckminster.cspex" file).
AlterDependencies component
The AlterDependencies describes an extension and alteration of Dependencies information.
AlterDependencies is a container for one or many Dependency (inherited from the CSPEC conceptual model) and Remove components. This allows to alter and remove existing dependencies defined in an associated CSPEC.
The non-expanded pseudo-schema shows the immediate element information items for AlterDependencies .
<cspecExtension> <alterDependencies> [ <dependency/> * <!-- <<< INHERITED FROM CSPEC !!! --> | <remove/> ] * </alterDependencies> </cspecExtension>
Remove component
The Remove component captures the removal of CSPEC artifacts in various places in the CspecExtension.
NOTE that the removal context is defined by the enclosing element and the remove action is then applied to the corresponding CSPEC artifacts of the given name.
The Remove may be applied to Dependencies, Artifacts, Groups, Actions as well as Attributes.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Remove. NOTE that this is only one possible example in which Remove may appear.
<cspecExtension> <alterDependencies> <remove name="xs:string" /> </alterDependencies> </cspecExtension>
The remove
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of the artifacts/component attributes which should be removed from the CSPEC. |
AlterArtifacts component
The AlterArtifacts component declares alterations (removals and overrides) associated with the Artifacts declared in a Cspec.
It is a container for Public, Private and Remove. The latter allows to declare the removal of a named Artifacts declared in a Cspec.
NOTE that the structure of Artifacts in Cspec is replicated. Alterations at any level are identified by the artifact name as provided in the Artifacts declarations.
<cspecExtension> <alterArtifacts> [ <public> | <private/> | <remove> ] * </alterArtifacts> </cspecExtension>
Public/Private AlterArtifacts
Public and Private AlterArtifact components inherit all the properties of Public/Private Artifacts. In addition, they allow to declare alterations (removals and overrides) associated with the Artifacts InstallerHints and Attribute components of matching names declared in a Cspec.
<cspecExtension> <alterArtifacts> <public name="xs:string" base="xs:string" ? path="xs:string" ? type="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> | <path/> ]* <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints/> | <removePath/> ] * </public> </alterArtifacts> </cspecExtension>
Public and Private AlterArtifact inherits all the attributes of Public/Private Artifacts.
AlterArtifacts AlterInstallerHints component
The AlterInstallerHints component declares alterations (removals and overrides) associated with the Propertys declared in InstallerHints of a Cspec as identified by the name attribute in the enclosing Public. This includes addition of new Property components.
<cspecExtension> <alterArtifacts> <public> <alterInstallerHints> [ <property/> | <remove/> ] * </alterInstallerHints> </public> </alterArtifacts> </cspecExtension>
Remove component
Denotes the removal of a Property in AlterInstallerHints component. See also: Remove.
<cspecExtension> <alterArtifacts> <public> <installerHints> <remove key="xs:string" /> </alterInstallerHints> </public> </alterArtifacts> </cspecExtension>
RemovePath component
Denotes the removal of a Path in AlterInstallerHints component. See also: Remove.
<cspecExtension> <alterArtifacts> <public> <removePath path="xs:string" /> </public> </alterArtifacts> </cspecExtension>
Remove component
Denotes the removal of the Artifacts component with the matching name. See also: Remove.
<cspecExtension> <alterArtifacts> <remove name="xs:string" /> </alterArtifacts> </cspecExtension>
AlterGroups component
The AlterGroups component declares alterations (removals and overrides) associated with the Groups declared in a Cspec.
It is a container for Public, Private and Remove. The latter allows to declare the removal of correspondingly named Groups declared in a Cspec.
NOTE that the structure of Groups in Cspec is replicated. Alterations at any level are identified by the group name as provided in the Groups declarations.
<cspecExtension> <alterGroups> [ <public> | <private/> | <remove> ] * </alterGroups> </cspecExtension>
Public/Private AlterGroups
Public and Private AlterGroups components inherit all the properties of Public/Private Groups. In addition, they allow to declare alterations (removals and overrides) associated with the Groups InstallerHints and Attribute components of matching names declared in a Cspec.
<cspecExtension> <alterGroups> <public name="xs:string" rebase="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> | <attribute/> ]* <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints/> | <alterAttribute /> | <remove/> ] * </public> </alterGroups> </cspecExtension>
Public and Private AlterGroups inherits all the attributes of Public/Private Groups.
AlterGroups AlterInstallerHints component
The AlterInstallerHints component declares alterations (removals and overrides) associated with the Propertys declared in InstallerHints of a Cspec as identified by the name attribute in the enclosing Public. This includes additions of new Property components.
<cspecExtension> <alterGroups> <public> <alterInstallerHints> [ <property/> | <remove/> ] * </alterInstallerHints> </public> </alterGroups> </cspecExtension>
Remove component
Denotes the removal of a Property in AlterInstallerHints component. See also: Remove.
<cspecExtension> <alterGroups > <public> <alterInstallerHints> <remove key="xs:string" /> </alterInstallerHints> </public> </alterGroups > </cspecExtension>
AlterGroups AlterAttribute component
The AlterAttribute component declares alterations (removals and overrides) associated with the Attribute of the matching name declared in Groups of a Cspec as identified by the name attribute in the enclosing Public.
<cspecExtension> <alterGroups > <public> <alterAttribute name="xs:string" component="xs:string" ? optional="xs:boolean" ? contributor="xs:boolean" ? /> </public> </alterGroups > </cspecExtension>
AlterAttribute inherits all the attributes of Attribute in Cspec.
Remove component
Denotes the removal of the Attribute with matching name declared in Groups of a Cspec as identified by the name attribute in the enclosing Public. See also: Remove.
<cspecExtension> <alterArtifacts> <alterAttribute > <remove name="xs:string" /> <alterAttribute> </alterArtifacts> </cspecExtension>
Remove component
Denotes the removal of the Groups component with the matching name. See also: Remove.
<cspecExtension> <alterGroups> <remove name="xs:string" /> </alterGroups> </cspecExtension>
AlterActions component
The AlterActions component declares alterations (removals and overrides) associated with the Actions declared in a Cspec.
It is a container for Public, Private and Remove. The latter allows to declare the removal of correspondingly named Actions declared in a Cspec.
NOTE that the structure of Actions in Cspec is replicated. Alterations at any level are identified by the group name as provided in the Actions declarations.
<cspecExtension> <alterActions> [ <public/> | <private/> | <remove> ] * </alterActions> </cspecExtension>
Public/Private AlterActions
Public and Private AlterActions components inherit all the properties of Public/Private Actions. In addition, they allow to declare alterations (removals and overrides) associated with the Actions and InstallerHints, ActorProperties, Properties, Prerequisites and Products components of matching names declared in a Cspec.
<cspecExtension> <alterActions> <public name="xs:string" actor="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> | <actorProperties/> | <properties/> | <prerequisites/> | <products/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints/> | <alterActorProperties/> | <alterProperties/> | <alterPrerequisites/> | <alterProducts/> ] * </public> </alterActions> </cspecExtension>
Public and Private AlterActions inherits all the attributes of Public/Private Actions.
AlterActions AlterInstallerHints component
The AlterInstallerHints component declares alterations (removals and overrides) associated with the Propertys declared in InstallerHints of a Cspec as identified by the name attribute in the enclosing Public. This includes addition of new Property components.
<cspecExtension> <alterActions> <public> <alterInstallerHints> [ <property/> | <remove/> ] * </alterInstallerHints> </public> </alterActions> </cspecExtension>
Remove component
Denotes the removal of a Property in InstallerHints component. See also: Remove.
<cspecExtension> <alterActions> <public> <alterInstallerHints> <remove key="xs:string" /> </alterInstallerHints> </public> </alterActions> </cspecExtension>
AlterActorProperties component
The AlterActorProperties component declares alterations (removals and overrides) associated with the Propertys declared in ActorProperties of a Cspec as identified by the name attribute in the enclosing Public. This includes addition of new Property components.
<cspecExtension> <alterActions> <public> <alterActorProperties> [ <property/> | <remove/> ] * </alterActorProperties> </public> </alterActions> </cspecExtension>
Remove component
Denotes the removal of a Property in ActorProperties component. See also: Remove.
<cspecExtension> <alterActions> <public> <alterActorProperties> <remove key="xs:string" /> </alterActorProperties> </public> </alterActions> </cspecExtension>
AlterActions AlterProperties component
The AlterProperties component declares alterations (removals and overrides) associated with the Propertys declared in Properties of a Cspec as identified by the name attribute in the enclosing Public. This includes addition of new Property components.
<cspecExtension> <alterActions> <public> <alterProperties> [ <property/> | <remove/> ] * </alterProperties> </public> </alterActions> </cspecExtension>
Remove component
Denotes the removal of a Property in Properties component. See also: Remove.
<cspecExtension> <alterActions> <public> <alterProperties> <remove key="xs:string" /> </alterProperties> </public> </alterActions> </cspecExtension>
AlterPrerequisites component
The AlterPrerequisites component declares alterations (removals and overrides) associated with the Prerequisites declared in a Cspec.
AlterPrerequisites components inherit all the properties of Prerequisites. In addition, they allow to declare alterations (removals and overrides) associated with the Prerequisites InstallerHints and Attribute components of matching names declared in a Cspec.
<cspecExtension> <alterActions> <public> <alterPrerequisites rebase="xs:string" ? alias="xs:string" ? includePattern="xs:string" ? excludePattern="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> <attribute/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints/> | <alterAttribute /> | <remove/> ] * </alterPrerequisites> </public> </alterActions> </cspecExtension>
AlterPrerequisites inherits all the attributes of Prerequisites.
AlterPrerequisites AlterInstallerHints component
The AlterInstallerHints component declares alterations (removals and overrides) associated with the Propertys declared in InstallerHints of a Cspec as identified by the name attribute in the enclosing Public. This includes additions of new Property components.
<cspecExtension> <alterActions> <public> <alterPrerequisites> <alterInstallerHints> [ <property/> | <remove/> ] * </alterInstallerHints> </alterPrerequisites> </public> </alterActions> </cspecExtension>
=Remove component=
Denotes the removal of a Property in InstallerHints component. See also: Remove.
<cspecExtension> <alterActions> <public> <alterPrerequisites> <alterInstallerHints> <remove key="xs:string" /> </alterInstallerHints> </alterPrerequisites> </public> </alterActions> </cspecExtension>
AlterPrerequisites AlterAttribute component
The AlterAttribute component declares alterations (removals and overrides) associated with the Attribute of the matching name declared in Attributes of a Cspec as identified by the name attribute in the enclosing Public.
<cspecExtension> <alterActions> <public> <alterPrerequisites> <alterAttribute name="xs:string" component="xs:string" ? optional="xs:boolean" ? contributor="xs:boolean" ? /> </alterPrerequisites> </public> </alterActions> </cspecExtension>
AlterAttribute inherits all the attributes of Attribute in Cspec.
Remove component
Denotes the removal of the Attribute with matching name declared in Prerequisites of a Cspec as identified by the name attribute in the enclosing Public. See also: Remove.
<cspecExtension> <alterActions> <public> <alterPrerequisites> <remove name="xs:string" /> </alterPrerequisites> </public> </alterActions> </cspecExtension>
AlterProducts component
The AlterProducts component declares alterations (removals and overrides) associated with matching Products declared in Cspec.
NOTE that the structure of Products in Cspec is replicated. Alterations at any level are identified by matching the names of the declared Products artifacts and directives.
<cspecExtension> <alterActions> <public> <alterProducts> [ <public/> | <private/> | <removeProduct/> | <removePath/> ] * </alterProducts> </public> </alterActions> </cspecExtension>
=AlterProducts Public/Private=
Public and Private AlterProducts components inherit all the properties of Products Public/Private. In addition, they allow to declare alterations (removals and overrides) associated with the Products' InstallerHints and Path components of matching name/path declared in a Cspec.
<cspecExtension> <alterActions> <public> <alterProducts> <public name="xs:string" ? base="xs:string" ? path="xs:string" ? type="xs:string" ? > <documentation/> ? <!-- INHERITED FROM CSPEC !!! >>> --> [ <installerHints/> | <path/> ] * <!-- <<< INHERITED FROM CSPEC !!! --> [ <alterInstallerHints/> | <removePath/> ] * </public> </alterProducts> </public> </alterActions> </cspecExtension>
Public and Private inherit all attribute information items from Products Public/Private.
==AlterProducts Public/Private AlterInstallerHints component==
The AlterInstallerHints component declares alterations (removals and overrides) associated with the Propertys declared in InstallerHints of a Cspec as identified by the name attribute in the enclosing Public. This includes the addition of new Property components.
<cspecExtension> <alterActions> <public> <alterProducts> <public> <alterInstallerHints> [ <property/> | <remove/> ] * </alterInstallerHints> </public> </alterProducts> </public> </alterActions> </cspecExtension>
===Remove component===
Denotes the removal of a Property in AlterInstallerHints component. See also: Remove.
<cspecExtension> <alterActions> <public> <alterProducts> <public> <alterInstallerHints> <remove key="xs:string" /> <alterInstallerHints/> </public> </alterProducts> </public> </alterActions> </cspecExtension>
==AlterProducts Public/Private RemovePath component==
Denotes the removal of the Path with matching path declared in Products of a Cspec as identified by the name attribute in the enclosing Public. See also: Remove.
<cspecExtension> <alterActions> <public> <alterProducts> <public> <removePath path="xs:string" /> </public> </alterProducts> </public> </alterActions> </cspecExtension>
=RemoveProduct component=
Denotes the removal of the Product with matching name declared in Actions of a Cspec as identified by the name attribute in the enclosing Public. See also: Remove.
<cspecExtension> <alterActions> <public> <alterProducts> <removeProduct name="xs:string" /> </alterProducts> </public> </alterActions> </cspecExtension>
=RemovePath component=
Denotes the removal of the Path with matching path declared in Products of a Cspec as identified by the name attribute in the enclosing Public. See also: Remove.
<cspecExtension> <alterActions> <public> <alterProducts> <removePath path="xs:string" /> </alterProducts> </public> </alterActions> </cspecExtension>
Remove component
Denotes the removal of Actions with matching name declared in a Cspec as identified by the name attribute in the enclosing Public. See also: Remove.
<cspecExtension> <alterActions> <remove name="xs:string" /> </alterActions> </cspecExtension>
BOM (Bill of Materials)
A complete reference of the BOM will be included in this document in the near future. As reusable output of the Buckminster framework BOM's are not intended for editing. For this reason the language reference focuses on other artifact types first.
MSPEC (Materialization Specification)
A materialization specification may be appointed for the materialization process in order to control certain properties of the process - specifically where components will be materialized (location) and how the materializer should behave if components already exist in the specified locations (conflict resolution).
A materialization specification is always tied to either a BOM (Bill of Materials) or a CQUERY (Component Query) which will either specify or resolve to the components that should be materialized.
MSPEC pseudo-schema
The following pseudo-schema provides an overview of the XML vocabulary used to describe a materialization specification. It is fully expanded with the exception of those components that are part of the Buckminster property model shared across all Buckminster artifacts. An XML style comment indicates where the element syntax with regard to child elements is not fully expanded.
NOTE that the pseudo-schema is navigable. Each element links to the document section explaining the structure and semantics of the element.
<mspec name="xs:string" materializer="xs:string" shortDesc="xs:string" url="com:URL" installLocation="xs:string" conflictResolution="md:ConflictResolution" > <documentation/> ? <mspecNode namePattern="xs:string" materializer="xs:string" category="xs:string" resourcePath="com:URL" exclude="xs:boolean" installLocation="xs:string" conflictResolution="md:ConflictResolution" > * <unpack expand="xs:boolean" suffix="xs:string" /> ? [ <property key="com:propertyKey" value="xs:string" mutable="xs:boolean" ? /> | <propertyElement> <!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--> </propertyElement> ] * </mspecNode> * [ <property key="com:propertyKey" value="xs:string" mutable="xs:boolean" ? /> | <propertyElement> <!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--> </propertyElement> ] * </mspec>
Mspec component
The Mspec is represented by an mspec
XML element information item which serves as the root element of a materialization specification artifact (that is a ".mspec" file).
An Mspec is a complete representation of a materialization directive. It denotes
- URLs to either a BOM (Bill of Materials) or a CQUERY (Component Query),
- directives for component materialization locations
- and conflict resolution strategies.
Mspec is a container for one or many MspecNodes, and Property and PropertyElement components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for Mspec.
<mspec name="xs:string" materializer="xs:string" shortDesc="xs:string" url="com:URL" installLocation="xs:string" conflictResolution="md:ConflictResolution" > <documentation/> ? <mspecNode/> * [ <property/> | <propertyElement> ] * </mspec>
The mspec
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
name | xs:string | - | The name of the this Mspec which typically relates to the artifact that is being materialized. |
materializer | xs:string | filesystem
... |
Specifies the target type of the materialization process. |
shortDesc | xs:string | - | The value of this attribute should provide a brief description of the Mspec. It is intended as a digest of the full documentation item that might be provided in the artifact and could be used when displaying MSPEC artifacts in an external tool. If present it does not influence the Buckminster materialization process. |
url | com:URL | - | A url to either a BOM or a CQUERY which provides or resolves to the set of components for materialization to which this Mspec should be applied. |
installLocation | xs:string | - | The target location for the materialized components. |
conflictResolution | md:ConflictResolution | UPDATE
FAIL KEEP REPLACE |
Specifies the conflict resolution policy that must be observed by the materializer when encountering components due four materialization in the installLocation. Buckminster specifies for conflict resolution approaches:
|
MspecNode component
The MspecNode components provide fine-grained materialization directives for individual components or families of components matching a component name pattern.
The MspecNode is a container for an optional Unpack component and for one or many Property and PropertyElement components which are represented with correspondingly named XML element information items.
The non-expanded pseudo-schema shows the immediate element and attribute information items for MspecNode.
<mspec> <mspecNode namePattern="xs:string" materializer="xs:string" category="xs:string" resourcePath="com:URL" exclude="xs:boolean" installLocation="xs:string" conflictResolution="md:ConflictResolution" > * <unpack/> ? [ <property/> | <propertyElement> ] * </mspecNode> </mspec>
The mspecNode
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
namePattern | xs:string | - | A regular expression string providing a component name pattern that will be used to match components specified in the BOM or a CQUERY referenced by this Mspec. The directives in this MspecNode will be applied to the components with a matching component name. |
materializer | xs:string | filesystem
... |
The materializer type to be used for components matching namePattern. |
category | xs:string | feature
plugin |
The directives in this MspecNode will be applied to the components with a component name matching namePattern AND which are of the type specified in category. Buckminster supports only two categories: feature and plugin relating to Eclipse component types. |
resourcePath | com:URL | - | - |
exclude | xs:boolean | - | If true , components matching namePattern will be excluded from materialization.
|
installLocation | xs:string | - | Specifies the installLocation relative to the installLocation in Mspec to which components matching namePattern should be materialized. |
conflictResolution | md:ConflictResolution | UPDATE
FAIL KEEP REPLACE |
Specifies the conflict resolution policy for components matching namePattern that must be observed by the materializer when encountering components due for materialization in the installLocation. Buckminster specifies four conflict resolution approaches:
|
Unpack component
The Unpack component provides a directive controlling the uncompression and expansion of materialized artifacts. These directives are applied to the artifacts specified in the enclosing MSpecNode component. Artifacts in the MSpecNode component will be uncompressed and possibly expanded if the appropriate unpack properties are set.
The non-expanded pseudo-schema shows the immediate attribute information items for Unpack.
<mspec> <mspecNode> <unpack expand="xs:boolean" suffix="xs:string" /> </mspecNode> </mspec>
The unpack
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
expand | xs:boolean | true
false |
If set to true , the artifact referenced by the enclosing MSpecNode will be expanded. Otherwise, it will only be unpacked. The semantics of unpack and expand depend on the compression format (ie. tar.gz, zip, etc).
|
suffix | xs:string | - | The suffix indicates which type of unpack/uncompression utility will have to be applied (i.e. GZ, ZIP, etc). This may be necessary if the necessary information can not be inferred from the resource URL. |
The Buckminster component meta-data language defines a number of concepts which are shared by the six artifact types. The most important is the properties framework.
Property Framework
Properties are defined using the Property and PropertyElement components. Both types may be contained in the following:
The following sections describe the structure and semantics of those two types of components. The pseudo-schemas focus on the described elements only and do not show the potential containers. If the semantics of Property and PropertyElement components vary for different containers this is stated explicitly.
Property component
A Property allows to declare a property that can be referenced by any artifact component in a given resolution context. References to a property are typically made using the common syntax ${PROPERTYKEY}. References to properties can be given anywhere except within regular expressions.
Apart from properties declared using either Property or PropertyElement Buckminster supports built-in properties, which may be set using the above elements:
- Target platform properties; the defaults are set by the target platform that the used build environment (build tool, workspace, target platform preferences) points to:
- target.os - the target platform operating system (typical values are aix, linux, macosx, solaris, win32)
- target.ws - the target platform windowing system (typical values are carbon, gtk, motif, wpf, win32)
- target.arch - the target platform architecture (typical values are ppc, x86, x86_64)
- target.nl - the target platform locale (typical values are en_US, de_DE, etc)
- Eclipse environment properties:
- eclipse.home - the installation path of the local Eclipse instance
- workspace.root - the path to a given workspace
- localhost - the host name
- System properties are available as well such as common JVM properties for example.
- Workspace properties passed through string substitution mechanism.
The Property component is represented by a property
XML element information item. The non-expanded pseudo-schema shows the attribute information items for Property. It does not contain any element information items.
... <property key="com:propertyKey" value="xs:string" mutable="xs:boolean" ? /> ...
The property
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
propertyKey | com:propertyKey | allows [A-Za-z0-9_.${}] | The value of this attribute provides the unique name by which other components can refer to the declared property. References to a property are typically of the form ${PROPERTYKEY}. Properties can not be referenced inside regular expressions. |
value | xs:string | - | The value of this attribute declares the value associated with the property referenced by propertyKey. |
mutable | xs:boolean | true
false |
If true the declared property value can be overwritten by another property declaration.
The semantics of property mutability have to be viewed with regard to the context in which properties can be declared. The different types of properties can be viewed as a stack consisting of system properties, named properties and string substitutions at the bottom of the stack. All of those properties are mutable. The next level of the properties consists of properties defined in RMap artifacts, then global CQuery properties and finally CQuery properties defined in AdvisorNodes. Properties can be overwritten top-down in this stack unless they are declared immutable. |
PropertyElement component
A PropertyElement allows to declare a property which needs to be assigned a property value that is the result of a function defined as part of PropertyElement. Within PropertyElement a set of functions can be referenced and arbitrarily nested through the appropriate elements to arrive at the property value. Elements representing those functions must be contained within PropertyElement.
PropertyElement is a container for zero or many Constant, Format, PropertyRef, Replace, ToLower and ToUpper components.
The PropertyElement component is represented by a propertyElement
XML element information item. The non-expanded pseudo-schema shows the element and attribute information items for PropertyElement.
... <propertyElement key="com:propertyKey" mutable="xs:boolean" ? > [ <constant value="xs:string" /> | <format format="xs:string"> [ <constant value="xs:string" /> | <format ...> <!-- EXPANDED AS ENCLOSING ELEMENT --> </format> | <propertyRef key="com:propertyKey" /> | <replace <!-- SEE BELOW FOR DETAILS --> </replace> | <toLower> <!-- SEE BELOW FOR DETAILS --> </toLower> | <toUpper> <!-- SEE BELOW FOR DETAILS --> </toUpper> | <split pattern="xs:string" style="com:splitType" ? limit="xs:integer" ? > [ <constant/> | <format/> | <propertyRef/> | <replace/> | <split/> | <toLower/> | <toUpper/> ]* <!-- SEE OTHER PARTS FOR DETAILS --> </split> ] * </format> | <propertyRef key="com:propertyKey" /> | <replace pattern="xs:string" ? replacement="xs:string" ? quotePattern="xs:boolean" ? > <match pattern="xs:string" replacement="xs:string" quotePattern="xs:boolean" ? /> * [ <constant/> | <format/> | <propertyRef/> | <replace/> | <split/> | <toLower/> | <toUpper/> ]* <!-- SEE OTHER PARTS FOR DETAILS --> </replace> | <toLower> [ <constant/> | <format/> | <propertyRef/> | <replace/> | <split/> | <toLower/> | <toUpper/> ]* <!-- SEE OTHER PARTS FOR DETAILS --> </toLower> | <toUpper> [ <constant/> | <format/> | <propertyRef/> | <replace/> | <split/> | <toLower/> | <toUpper/> ]* <!-- SEE OTHER PARTS FOR DETAILS --> </toUpper> ] </propertyElement> ...
The propertyElement
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
propertyKey | com:propertyKey | allows [A-Za-z0-9_.${}] | The value of this attribute provides the unique name by which other components can refer to the declared property. References to a property are typically of the form ${PROPERTYKEY}. Properties can not be referenced inside regular expressions. |
mutable | xs:boolean | true
false |
If true the declared property value can be overwritten by another property declaration.
The semantics of property mutability have to be viewed with regard to the context in which properties can be declared. The different types of properties can be viewed as a stack consisting of system properties, named properties and string substitutions at the bottom of the stack. All of those properties are mutable. The next level of the properties consists of properties defined in RMap artifacts, then global CQuery properties and finally CQuery properties defined in AdvisorNodes. Properties can be overwritten top-down in this stack unless they are declared immutable. |
Constant component
A Constant represents one of the functions that may be used to define a value for a property defined with PropertyElement. The semantics of a property declaration with PropertyElement and Constant are equivalent to a property declaration with Property.
The Constant component is represented by a constant
XML element information item.
... <propertyElement> <constant value="xs:string" /> </propertyElement> ...
The constant
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
value | xs:string | - | The value of this attribute declares the value associated with the property referenced by propertyKey in the enclosing PropertyElement. |
Format component
Format allows to define a property value as a complex message sequence partially composed of references to enclosed parameters. The children defined for a Format provide the parameters that can be referenced in this context. NOTE that only the immediate children are considered as referencable parameters. They are referenced by there position in the sequence of children using a string substitution format (i.e. {0} for the first parameter).
The Format component is represented by a format
XML element information item. It is a container for zero to many Constant, Format, PropertyRef, Replace, ToLower, ToUpper and Split components which must occur in sequence. They are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by format.
... <propertyElement> <format format="xs:string"> [ <constant/> | <format/> | <propertyRef/> | <replace/> | <split/> | <toLower/> | <toUpper/> ]* </format> </propertyElement> ...
The format
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
format | xs:string | - | The value of this attribute declares the value associated with the property referenced by propertyKey in the enclosing PropertyElement.
The property value is assumed to be a message sequence partially composed of references to enclosed parameters. The function outputs represented by the contained children (Constant, Format, PropertyRef, Replace, ToLower, ToUpper and Split) provide the parameters that can be referenced in the property value. Only the immediate children of the Format are considered as referencable parameters. They are referenced by there position in the sequence of children using a string substitution format (i.e. {0} for the first parameter). NOTE that certain functions may produce multiple parameters for referencing (Split). |
Split component
A Split represents a split function based on a given regular expression. Its output is a set of parameters that can be referenced within a message sequence defined by an enclosing Format. They are referenced by there position index in the split sequence offset by any potentially available parameters defined through preceding siblings (i.e. if a split produces two groups and the Split is preceded by a Constant, than the parameter by the latter would be referenced with {0} and the parameters resulting from the Split would be referred to as {1} and {2}.
NOTE that Split must always be the last element in a sequence in order to ensure that the indices by which preceding parameters are referenced are not changed by the output of a split.
The input to the Split is provided by the enclosed children. If multiple immediate children are defined their output is concatenated in sequence in order to produce the input to the function.
The Split component is represented by a split
XML element information item. It is a container for a required Match and zero to many Constant, Format, PropertyRef, Split, Replace, ToLower, ToUpper components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by split.
... <propertyElement> <split pattern="xs:string" style="com:splitType" ? limit="xs:integer" ? > [ <constant/> | <format/> | <propertyRef/> | <split/> | <replace/> | <toLower/> | <toUpper/> ]* </split> </propertyElement> ...
The split
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
pattern | xs:string | - | Defines the regular expression that serves as a split boundary when applied to the input string. |
style | com.splitType | unquoted
quoted groups |
The value of this attribute determines how the provided pattern is interpreted:
|
limit | xs:integer | - | Defines a limit for the outputs of the split which will be available for referencing by enclosing functions. |
PropertyRef component
A PropertyRef allows to reference a property defined with Property or PropertyElement as well as ALL properties available in the resolution context (System properties, etc as well).
The PropertyRef component is represented by a propertyRef
XML element information item. The non-expanded pseudo-schema shows the element information items directly contained by propertyRef.
... <propertyElement> <propertyRef key="com:propertyKey" /> </propertyElement> ...
The propertyRef
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
key | com:propertyKey | - | The name of a property available in the resolution context. No special syntax is required for the reference (only the plain property name). |
Replace component
A Replace defines a function that allows to replace a given input with a replacement string based on a regular expression pattern with matching groups.
The input of Replace is provided by the enclosed children excluding Match. If multiple immediate children are defined their output is concatenated in sequence in order to produce the input to the function.
The Replace component is represented by a replace
XML element information item. It is a container for a required zero to many Match and zero to many Constant, Format, PropertyRef, Replace, Split, ToLower, ToUpper components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by replace.
... <propertyElement> <replace pattern="xs:string" ? replacement="xs:string" ? quotePattern="xs:boolean" ? > [ <constant/> | <format/> | <propertyRef/> | <replace/> | <split/> | <toLower/> | <toUpper/> ]* <match/> * </replace> </propertyElement> ...
The replace
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
pattern | xs:string | - | A regular expression containing groups which can be referenced by the replacement string in the replacement attribute. The regular expression will be applied to the input which is either one or many of Constant, Format, PropertyRef, Replace, Split, ToLower, ToUpper. If multiple components of those types are present the immediate children of Replace are concatenated in sequence in order to form the input.
An example would be the transformation of i.e. a version identifier containing "." which will be replaced by "_". The groups defined in the regular expression would capture the content between the "." characters. NOTE that this is an optional attribute since the replace logic may be captured instead by a Match. If this attribute is present it requires the replacement attribute to be defined and precludes the use of Match. |
replacement | xs:string | - | Defines the output of the replace function. The attribute contains the replacement string which will at least partially be composed of references to the groups captured by the regular expression defined in pattern.
NOTE that this is an optional attribute since the replace logic may be captured instead by a Match. If this attribute is present it requires the pattern to be defined on Replace and precludes the use of Match. |
quotePattern | xs:boolean | true
false |
If true the regular expression defined in pattern is interpreted as if quoted. This is a convenience mechanism which does not require special characters in the expression to be escaped. |
Match component
A Match provides a more sophisticated and flexible replacement mechanism and caters for cases where an input may have to be matched against multiple patterns with potentially different replacement strings. An example would be the transformation of i.e. a version identifier potentially containing different types of separators (i.e. ".", "-", "#") which will have to be replaced by "_". All three cases would be captured by one Match each with either the same or different replacement strings associated with each. If multiple Matchs appear they are evaluated in the order of appearance.
The input of Match is provided by its siblings of type Constant, Format, PropertyRef, Replace, Split, ToLower, ToUpper. If multiple siblings are defined their output is concatenated in sequence in order to produce the input to the Match function.
The Match component is represented by a match
XML element information item. The non-expanded pseudo-schema shows the attribute information items directly contained by match.
... <propertyElement> <replace> <match pattern="xs:string" replacement="xs:string" quotePattern="xs:boolean" ? /> * </replace> </propertyElement> ...
The match
element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):
Attribute | Type | Values | Semantics |
---|---|---|---|
pattern | xs:string | - | A regular expression containing groups which can be referenced by the replacement string in the replacement attribute. The regular expression will be applied to the input which is either one or many of Constant, Format, PropertyRef, Replace, Split, ToLower, ToUpper appearing as siblings of Match. If multiple components of those types are present the siblings of Match are concatenated in sequence in order to form the input. |
replacement | xs:string | - | Defines the output of the enclosing Replace. The attribute contains the replacement string which will at least partially be composed of references to the groups captured by the regular expression defined in the pattern attribute of Match. |
quotePattern | xs:boolean | true
false |
If true the regular expression defined in pattern is interpreted as if quoted. This is a convenience mechanism which does not require special characters in the expression to be escaped. |
ToLower component
A ToLower represents a function transforming all characters in a given input value to lower case. The input of ToLower is provided by the enclosed children. If multiple immediate children are defined their output is concatenated in sequence in order to produce the input to the function.
The ToLower component is represented by a toLower
XML element information item. It is a container for zero to many Constant, Format, PropertyRef, Replace, Split, ToLower, ToUpper components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by toLower.
... <propertyElement> <toLower> [ <constant/> | <format/> | <propertyRef/> | <replace/> | <split/> | <toLower/> | <toUpper/> ]* </toLower> </propertyElement> ...
The toLower
element has no attributes.
ToUpper component
A ToUpper represents a function transforming all characters in a given input value to upper case. The input of ToUpper is provided by the enclosed children. If multiple immediate children are defined their output is concatenated in sequence in order to produce the input to the function.
The ToUpper component is represented by a toUpper
XML element information item. It is a container for zero to many Constant, Format, PropertyRef, Replace, Split, ToLower, ToUpper components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by toUpper.
... <propertyElement> <toUpper> [ <constant/> | <format/> | <propertyRef/> | <replace/> | <split/> | <toLower/> | <toUpper/> ]* </toUpper> </propertyElement> ...
The toUpper
element has no attributes.