Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Buckminster component meta-data language 1.0 (Reference)"

(VersionConverter component)
(Replacing page with '{{Backlink|Buckminster Project}} This page has been deprecated. Please use our book [http://www.eclipse.org/downloads/download.php?file=/tools/buckminster/doc/BuckyBook.pdf Th...')
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{Backlink|Buckminster Project}}
 
{{Backlink|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''
+
This page has been deprecated. Please use our book [http://www.eclipse.org/downloads/download.php?file=/tools/buckminster/doc/BuckyBook.pdf The Definitive Guide]
  
=Introduction=
+
[[Category:Buckminster]] [[Category:Buckminster Artifacts]]
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 [[Buckminster meta-data language 1.0 (Primer)|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.
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Prefix
+
! Namespace
+
! Source
+
! Schema 
+
|- valign="top"
+
| '''xs'''
+
| http://www.w3.org/2001/XMLSchema
+
| Defined in the W3C XML Schema specification (Part [http://www.w3.org/TR/2007/PR-wsdl20-20070523/#XMLSchemaP1 1] & [http://www.w3.org/TR/2007/PR-wsdl20-20070523/#XMLSchemaP2 2])
+
| -
+
|- valign="top"
+
| '''com'''
+
| http://www.eclipse.org/buckminster/Common-1.0
+
| Defined in the Buckminster meta-data language
+
| [http://www.eclipse.org/buckminster/schemas/common-1.0.xsd common-1.0.xsd]
+
|- valign="top"
+
| '''rm'''
+
| http://www.eclipse.org/buckminster/RMap-1.0
+
| Defined in the Buckminster meta-data language
+
| [http://www.eclipse.org/buckminster/schemas/rmap-1.0.xsd rmap-1.0.xsd]
+
|- valign="top"
+
| '''cq'''
+
| http://www.eclipse.org/buckminster/CQuery-1.0
+
| Defined in the Buckminster meta-data language
+
| [http://www.eclipse.org/buckminster/schemas/cquery-1.0.xsd cquery-1.0.xsd]
+
|- valign="top"
+
| '''cs'''
+
| http://www.eclipse.org/buckminster/CSpec-1.0
+
| Defined in the Buckminster meta-data language
+
| [http://www.eclipse.org/buckminster/schemas/cspec-1.0.xsd cspec-1.0.xsd]
+
|- valign="top"
+
| '''md'''
+
| http://www.eclipse.org/buckminster/MetaData-1.0
+
| Defined in the Buckminster meta-data language
+
| [http://www.eclipse.org/buckminster/schemas/metadata-1.0.xsd metadata-1.0.xsd]
+
|- valign="top"
+
| '''mpv'''
+
| http://www.eclipse.org/buckminster/MavenProvider-1.0
+
| Defined in the Buckminster meta-data language
+
| [http://www.eclipse.org/buckminster/schemas/maven-provider-1.0.xsd 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|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 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 <code>attributeFormDefault</code> to be <code>unqualified</code>. Consult the W3C XML Schema recommendation for details on this ([http://www.w3.org/TR/xmlschema-1/ 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 [[#CQUERY|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 <code>$HOME</code>, <code>$CLOSEST_MIRROR</code>).
+
 
+
 
+
==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 component|rmap]]>
+
    <documentation/> ?
+
    [
+
      <[[#Property component|property]]
+
            '''key="com:propertyKey"'''
+
            '''value="xs:string"'''
+
            mutable="xs:boolean" ? />
+
    |
+
      <[[#PropertyElement component|propertyElement]]>
+
        ''&lt;!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--&gt;''
+
      </propertyElement>
+
    |
+
      <[[#SearchPath component|searchPath]]
+
            '''name="xs:string"''' >
+
        '''<[[#Provider component|provider]]'''
+
                  '''readerType="xs:string"'''
+
                  '''componentTypes="xs:string"'''
+
                  '''componentType="xs:string"''' '''&lt;!-- DEPRECATED --&gt;'''
+
                  managedCategories="xs:string" ? '''&lt;!-- DEPRECATED --&gt;'''
+
                  mutable="xs:boolean" ?
+
                  source="xs:boolean" ? >
+
            <documentation/> ?
+
            <[[#Provider Matcher component|matcher]]
+
                  '''base="xs:string'''>
+
              [
+
                <[[#Provider Match component|match]]
+
                      name="xs:string"
+
                      optional="xs:boolean"
+
                      '''pattern="xs:string"'''
+
                      prefix="xs:string"
+
                      suffix="xs:string" />
+
                |
+
                <[[#Provider Group component|group]]
+
                      name="xs:string"
+
                      optional="xs:boolean">
+
                    [
+
                      <[[#Provider Group Name component|name]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" />
+
                    |
+
                      <[[#Provider Group Version component|version]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" />
+
                    |
+
                      <[[#Provider Group Timestamp component|timestamp]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" />
+
                    |
+
                      <[[#Provider Group Revision component|revision]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" />
+
                    |
+
                      <[[#Provider Group Os component|os]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" />
+
                    |
+
                      <[[#Provider Group Ws component|ws]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" />
+
                    |
+
                      <[[#Provider Group Arch component|arch]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" />
+
                    |
+
                      <[[#Provider Group Nl component|nl]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" />
+
                    |
+
                      <[[#Provider Match component|match]]
+
                            name="xs:string"
+
                            optional="xs:boolean"
+
                            '''pattern="xs:string"'''
+
                            prefix="xs:string"
+
                            suffix="xs:string" /> 
+
                    ]*                     
+
                </group>
+
              ]+
+
            </matcher>
+
            '''<[[#Uri component|uri]]>'''
+
              ''&lt;!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--&gt;''
+
            '''</uri>'''
+
            <[[#Provider Digest component|digest]]
+
                  '''algorithm="xs:string"''' />
+
            <[[#VersionConverter component|versionConverter]]
+
                  '''type="xs:string"''' >
+
              <[[#Transform component|transform]]
+
                    '''toPattern="xs:string"'''
+
                    '''toReplacement="xs:string"'''
+
                    '''fromPattern="xs:string"'''
+
                    '''fromReplacement="xs:string"''' > *
+
            </versionConverter> ?
+
        '''</provider> +'''
+
      </searchPath>
+
    |
+
      <[[#Locator component|locator]]
+
            '''pattern="xs:string"'''
+
            '''searchPathRef="xs:string"''' />
+
    |
+
      <[[#Redirect component|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 <code>rmap</code> 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 component|SearchPath]]''''', '''''[[#Locator component|Locator]]''''', '''''[[#Redirect component|Redirect]]''''', '''''[[#Property component|Property]]''''' and '''''[[#PropertyElement component|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 component|property]]/> | <[[#PropertyElement component|propertyElement]]/> | <[[#SearchPath component|searchPath]]/> | <[[#Locator component|locator]]/> | <[[#Redirect component|redirect]]/> ]*
+
  '''</rmap>'''
+
 
+
The <code>documentation</code> element may contain mixed content and should be used to provide contextual documentation of the RMAP and its contained elements. This applies whereever the <code>documentation</code> 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 '''''SearchPath'''''s. The defined '''''SearchPath'''''s 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 '''''[[#Provider component|Provider]]'''''s. 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 '''''[[#AdvisorNode component|AdvisorNode]]'''''s defined for the '''''[[#ComponentQuery component|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 component|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 <code>searchPath</code> XML element information item. It is a container for required '''''[[#Provider component|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 component|rmap]]>''
+
    '''<searchPath'''
+
            '''name="xs:string"''' >
+
      '''<[[#Provider component|provider]]/>''' +
+
      <documentation/> ?
+
    '''</searchPath>'''
+
''</rmap>''
+
 
+
 
+
The <code>searchPath</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 <code>provider</code> XML element information item. It is a container for a required '''''[[#Uri component|Uri]]''''' and an optional '''''[[#VersionConverter component|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 component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        '''<provider'''
+
                  '''readerType="xs:string"'''
+
                  '''componentTypes="xs:string"'''
+
                  '''componentType="xs:string"''' '''&lt;!-- DEPRECATED --&gt;'''
+
                  managedCategories="xs:string" ? '''&lt;!-- DEPRECATED --&gt;'''
+
                  mutable="xs:boolean" ?
+
                  source="xs:boolean" ? >
+
            <documentation/> ?
+
            <[[#Provider Matcher component|matcher]]/> ?
+
            '''<[[#Uri component|uri]]/>'''
+
            <[[#Provider Digest component|digest]]/> ?
+
            <[[#VersionConverter component|versionConverter]]/> ?
+
        '''</provider> +'''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
 
+
The <code>provider</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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:
+
 
+
*'''cvs''' - a reader capable of navigating and reading CVS repositories. 
+
*'''svn''' - a reader capable of navigating and reading Subversion repositories. The SVN repository reader assumes that any repository contains the three recommended directories <code>trunk</code>, <code>tags</code> and <code>branches</code>.
+
*'''maven''' -  a reader capable of navigating and reading Maven repositories. It is based on the ''url.catalog'' reader. Maven 2 features are not fully supported yet.
+
*'''p4''' - a reader capable of navigating and reading Perforce repositories.
+
*'''site.feature''' -  an update site reader or all locations that provided feature.xml, plugin.xml and/or site.xml files.
+
*'''eclipse.platform''' - a reader to obtain information from the target platform (most commonly your installed features and plugins). This reader will not materialize anything into your workspace. It will "resolve" using what's already present in your runtime or appointed platform.
+
*'''eclipse.import''' - a reader replicating the Eclipse feature and plugin import (from your platform or an arbitrary site). NOTE that the type of import (''binary'', ''linked'', or ''source'') is controlled using URL parameters in the repository [[#Locator component|Locator]].
+
*'''url''' - a reader capable of reading one single file appointed by an URL (typically a jar, dll, or other pre-compiled artifact). The file is treated as a component in its own right.
+
*'''url.catalog''' - reads files from a specific catalog (folder) appointed by a URL.
+
*'''url.zipped''' - reads individual files from a zip archive appointed by a URL.
+
*'''local''' - capable of reading existing components (i.e. previously materialised) just using the component meta-data.
+
 
+
Consult the information for the ''format'' attribute of '''''[[#Uri component|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 <code>org.eclipse.buckminster.core.readerTypes</code> extension point. The [[Extending Buckminster with a custom component reader]] document explains how this can be done.
+
|- valign="top"
+
| '''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 component|Provider]]. This information is essential in order for Buckminster to extract component dependency information which Buckminster automatically translates into its own dependency format ([[#CSPEC|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:
+
 
+
* '''osgi.bundle''' - standard component type for software assets maintained with Eclipse expecting  assets such as ''.project'' or ''plugin.xml'' files. Essentially, an Eclipse plugin.
+
*'''eclipse.feature''' - an Eclipse feature component.
+
*'''eclipse.site''' - a component that is an Eclipse update site.
+
* '''eclipse.project''' - ('''DEPRECATED !!!''' This is now an alias for ''componentTypes'' "osgi.bundle,eclipse.feature,buckminster"). Standard component type for software assets maintained with Eclipse expecting assets such as ''.project'' or ''plugin.xml'' files.
+
* '''eclipse.installed''' - ('''DEPRECATED !!!''' This is now an alias for ''componentTypes'' "osgi.bundle,eclipse.feature"). Refers to components that are deployed in your Eclipse runtime.
+
* '''jar''' - refers to components that are JAR files and can be treated as components in their own right. Buckminster will generate a CSPEC that has no dependencies. This type is intended to be used when you want to depend on a JAR known to be found using a common URL.
+
* '''maven''' - basically an extended JAR type but assuming Maven repository dependency information contained in a POM.
+
* '''buckminster''' - refers to software assets that have no derivable component specification information, or where a specific Component Type has not been created. Assumes that the owner of the asset has added a manually created (and maintained) [[#CSPEC|CSPEC]] inside the software asset. The reader will expect an included <code>buckminster.cspec</code>
+
* '''site.feature''' - refers to components found on an update site with the typical meta-data files. MUST BE used in combination with a ''site.feature'' component reader.
+
* '''bom''' - refers to a component which is a [[#BOM|BOM]] artifact as produced by the Buckminster resolution process. The Buckminster framework is capable of plugging the BOM information into the resolution process and result.
+
* '''unknown''' - indicates components for which no dependency information can be inferred or has been made available.
+
 
+
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"
+
| '''componentType'''
+
| xs:string
+
| -
+
| '''DEPRECATED !!!''' USE ''componentTypes'' INSTEAD !!!
+
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 ''componentType'' is required to configure the required reader. The component type indicates to the reader which component structure and meta-data to expect for the declared [[#Provider component|Provider]]. This information is essential in order for Buckminster to extract component dependency information which Buckminster automatically translates into its own dependency format ([[#CSPEC|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:
+
 
+
* '''eclipse.project''' - standard component type for software assets maintained with Eclipse expecting  assets such as ''.project'' or ''plugin.xml'' files. ('''DEPRECATED !!!''' This is now an alias for ''componentTypes'' "osgi.bundle,eclipse.feature,buckminster").
+
* '''eclipse.installed''' - refers to components that are deployed in your Eclipse runtime. ('''DEPRECATED !!!''' This is now an alias for ''componentTypes'' "osgi.bundle,eclipse.feature").
+
* '''jar''' - refers to components that are JAR files and can be treated as components in their own right. Buckminster will generate a CSPEC that has no dependencies. This type is intended to be used when you want to depend on a JAR known to be found using a common URL.
+
* '''maven''' - basically an extended JAR type but assuming Maven repository dependency information contained in a POM.
+
* '''buckminster''' - refers to software assets that have no derivable component specification information, or where a specific Component Type has not been created. Assumes that the owner of the asset has added a manually created (and maintained) [[#CSPEC|CSPEC]] inside the software asset.
+
* '''site.feature''' - refers to components found on an update site with the typical meta-data files. MUST BE used in combination with a ''site.feature'' component reader.
+
* '''bom''' - refers to a component which is a [[#BOM|BOM]] artifact as produced by the Buckminster resolution process. The Buckminster framework is capable of plugging the BOM information into the resolution process and result.
+
* '''unknown''' - indicates components for which no dependency information can be inferred or has been made available.
+
 
+
The specified ''componentType'' may be 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"
+
| managedCategories
+
| 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 ''managedCategories'' MUST BE a comma-separated list of component categories. Buckminster currently supports the two categories listed. They allow to distinguish between components which are of the same name but fall in either the category ''feature'' or ''plugin''.
+
 
+
The ''managedCategories'' attribute essentially defines a filter on the '''''[[#Provider component|Provider]]'''''. Through the specification of ''managedCategories'' the Provider can state that it can only handle requests for components of the specified category. This directly relates to the information specified by the ''category'' attribute in a '''''[[#RootRequest component|RootRequest]]''''' of a '''''[[#ComponentQuery component|ComponentQuery]]'''''. If such a request specifies no category or a category matched by ''managedCategories'' the Provider will handle the request, that is the Buckminster runtime will consult it during the resolution and materialization process.
+
 
+
If no managed categories are specified, the Provider is considered a handler for all categories.
+
|- valign="top"
+
| 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 component|AdvisorNode]]''''' given with a '''''[[#RootRequest component|RootRequest]]''''' in a '''''[[#ComponentQuery component|ComponentQuery]]'''''. Together they contribute to an internally computed '''''[[#Provider component|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:
+
*A component query may for example specify that it wants to REJECT providers with mutable content (see ''mutableLevel'' attribute for more details). In this case, assuming a Provider indicates ''mutable="true"'', the Buckminster runtime will skip this Provider during the resolution and materialization process.
+
*In a more complex example it may be that an AdvisorNode specifies a mutableLevel="DESIRE" and a sourceLevel="DESIRE". Assuming two matching Providers with a ''mutable''/''source'' combination of <code>true/true</code> and <code>true/false</code>. In this case the first Provider would be chosen as it would have a higher ranked "Provider score".
+
|- valign="top"
+
| 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 component|AdvisorNode]]''''' given with a '''''[[#RootRequest component|RootRequest]]''''' in a '''''[[#ComponentQuery component|ComponentQuery]]'''''. Together they contribute to an internally computed '''''[[#Provider component|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:
+
*see examples for the ''mutable'' attribute ...
+
|}
+
 
+
 
+
=====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 '''''[[#Provider Match component|Match]]''''' and '''''[[#Provider Group component|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 '''''[[#Provider Match component|Match]]''''' and '''''[[#Provider Group component|Group]]''''' components. 
+
 
+
The '''''Matcher''''' component is represented by a <code>matcher</code> XML element information item. It is a container for one or more '''''[[#Provider Match component|Match]]''''' and '''''[[#Provider Group component|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 component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            '''<matcher
+
                  '''base="xs:string"''' >'''
+
              [ <[[#Provider Match component|match]]/> | <[[#Provider Group component|group]]/> ]+
+
            '''</matcher>'''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>matcher</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 '''''[[#Provider Matcher component|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 '''''[[#Provider Matcher component|Matcher]]'''''. The result of the pattern match can be assigned to a variable which is referenceable by other elements (i.e. '''''[[#Uri component|Uri]]''''' within the '''''[[#Provider component|Provider]]''''' context.
+
 
+
The '''''Match''''' component is represented by a <code>match</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''match''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              '''<match'''
+
                    name="xs:string"
+
                    optional="xs:boolean"
+
                    '''pattern="xs:string"'''
+
                    prefix="xs:string"
+
                    suffix="xs:string" />
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>match</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''pattern'''
+
| xs:string
+
| -
+
| The pattern which will be applied to URLs in turn. It must be a valid regular expression.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 '''''[[#Provider Matcher component|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 '''''[[#Provider Matcher component|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 component|Uri]]''''' within the '''''[[#Provider component|Provider]]''''' context.
+
 
+
The '''''Group''''' component is represented by a <code>group</code> XML element information item. It is a container for zero to many '''''[[#Provider Group Name component|Name]]''''', '''''[[#Provider Group Version component|Version]]''''', '''''[[#Provider Group Timestamp component|Timestamp]]''''', '''''[[#Provider Group Revision component|Revision]]''''', '''''[[#Provider Group Os component|Os]]''''', '''''[[#Provider Group Ws component|Ws]]''''', '''''[[#Provider Group Arch component|Arch]]''''', '''''[[#Provider Group Nl component|Nl]]''''' and '''''[[#Provider Match component|Match]]''''' components. The non-expanded pseudo-schema shows the element and attribute information items contained by ''group''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              '''<group'''
+
                    name="xs:string"
+
                    optional="xs:boolean" />
+
                  [ <[[#Provider Group Name component|name]]/> | <[[#Provider Group Version component|version]]/> | <[[#Provider Group Timestamp component|timestamp ]]/> | <[[#Provider Group Revision component|revision]]/> | <[[#Provider Group Os component|os]]/>
+
                  | <[[#Provider Group Ws component|ws]]/> | <[[#Provider Group Arch component|arch]]/> | <[[#Provider Group Nl component|nl]]/> | <[[#Provider Match component|match]]/> ]*
+
              '''</group>'''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>group</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| 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 <code>name</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''name''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              ''<[[#Provider Group component|group]]>''
+
                  '''<name'''
+
                        name="xs:string"
+
                        optional="xs:boolean"
+
                        '''pattern="xs:string"'''
+
                        prefix="xs:string"
+
                        suffix="xs:string" '''/>'''
+
              ''</group>''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>name</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''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_-]+"
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 <code>version</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''version''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              ''<[[#Provider Group component|group]]>''
+
                  '''<version'''
+
                        name="xs:string"
+
                        optional="xs:boolean"
+
                        '''pattern="xs:string"'''
+
                        prefix="xs:string"
+
                        suffix="xs:string" '''/>'''
+
              ''</group>''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>version</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''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]+"
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 <code>timestamp</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''timestamp''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              ''<[[#Provider Group component|group]]>''
+
                  '''<timestamp'''
+
                        name="xs:string"
+
                        optional="xs:boolean"
+
                        '''pattern="xs:string"'''
+
                        prefix="xs:string"
+
                        suffix="xs:string" '''/>'''
+
              ''</group>''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>timestamp</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''pattern'''
+
| xs:string
+
| -
+
| The pattern which will be applied to URLs in turn. It must be a valid regular expression.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 <code>revision</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''revision''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              ''<[[#Provider Group component|group]]>''
+
                  '''<revision'''
+
                        name="xs:string"
+
                        optional="xs:boolean"
+
                        '''pattern="xs:string"'''
+
                        prefix="xs:string"
+
                        suffix="xs:string" '''/>'''
+
              ''</group>''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>revision</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''pattern'''
+
| xs:string
+
| -
+
| The pattern which will be applied to URLs in turn. It must be a valid regular expression.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 <code>os</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''os''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              ''<[[#Provider Group component|group]]>''
+
                  '''<os'''
+
                        name="xs:string"
+
                        optional="xs:boolean"
+
                        '''pattern="xs:string"'''
+
                        prefix="xs:string"
+
                        suffix="xs:string" '''/>'''
+
              ''</group>''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>os</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''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"
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 <code>ws</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''ws''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              ''<[[#Provider Group component|group]]>''
+
                  '''<ws'''
+
                        name="xs:string"
+
                        optional="xs:boolean"
+
                        '''pattern="xs:string"'''
+
                        prefix="xs:string"
+
                        suffix="xs:string" '''/>'''
+
              ''</group>''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>ws</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''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"
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 <code>arch</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''arch''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              ''<[[#Provider Group component|group]]>''
+
                  '''<arch'''
+
                        name="xs:string"
+
                        optional="xs:boolean"
+
                        '''pattern="xs:string"'''
+
                        prefix="xs:string"
+
                        suffix="xs:string" '''/>'''
+
              ''</group>''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>arch</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''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"
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 <code>nl</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ''nl''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#Provider Matcher component|matcher]]>''
+
              ''<[[#Provider Group component|group]]>''
+
                  '''<nl'''
+
                        name="xs:string"
+
                        optional="xs:boolean"
+
                        '''pattern="xs:string"'''
+
                        prefix="xs:string"
+
                        suffix="xs:string" '''/>'''
+
              ''</group>''
+
            ''</matcher>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>nl</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| name
+
| xs:string
+
| -
+
| The name of a variable by which the result of the match can be referenced within the '''''[[#Provider component|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.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| true
+
'''false'''
+
| Denotes if this part is optional or must be matched.
+
|- valign="top"
+
| '''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"
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 component|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 <code>uri</code> XML element information item. It is a container for optional '''''[[#Constant component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''[[#Replace component|Replace]]''''', '''''[[#Split component|Split]]''''', '''''[[#ToLower component|ToLower]]''''' and '''''[[#ToUpper component|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 component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            '''<uri'''
+
                  '''format="xs:string"''' '''>'''
+
              [ <com:constant/> | <com:format/> | <com:propertyRef/> |
+
                <com:replace/> | <com:split/> | <com:toLower/> | <com:toUpper/> ] *
+
            '''</uri>
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
 
+
The <code>uri</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|Provider]]''''' in the '''''[[#SearchPath component|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 "<code>:pserver:anonymous@dev.eclipse.org:/cvsroot/technology,org.eclipse.dash/{0}</code>". 
+
 
+
EXAMPLES FOR ALL COMPONENT READER TYPES:
+
* ...
+
|}
+
 
+
 
+
<includeonly>
+
<pre>
+
<rm:uri format=" :Pserver:anonymous@dev.eclipse.org:/cvsroot/technology,org.eclipse.buckminster/test/{0}">
+
    <bc:replace pattern="^buckminster\.test\.(.+)" replacement="$1" quotePattern="false">
+
    <bc:propertyRef key="buckminster.component" />
+
    </bc:replace>
+
  </rm:uri>
+
 
+
<rm:uri format="http://www.ibiblio.org/maven"/>
+
</pre>
+
</includeonly>
+
 
+
=====Provider Digest component=====
+
A '''''Digest''''' ...
+
 
+
The '''''Digest''''' component is represented by a <code>digest</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items directly contained by ''digest''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            '''<digest
+
                  '''algorithm="xs:string"''' >'''
+
            '''</digest>'''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>digest</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''algorithm'''
+
| xs:string
+
| -
+
| -
+
|}
+
 
+
 
+
 
+
=====VersionConverter component=====
+
A '''''VersionConverter''''' specifies how a component reader for a specific component type declared by  the enclosing '''''[[#Provider component|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 <code>versionConverter</code> XML element information item. It is a container for optional '''''[[#Transform component|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 component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            '''<versionConverter
+
                  '''type="xs:string"''' >'''
+
              <[[#Transform component|transform]]/> *
+
            '''</versionConverter>'''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>versionConverter</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''type'''
+
| xs:string
+
| -
+
| The value of this attribute specifies which type of version converter the component reader specified by the '''''[[#Provider component|Provider]]''''' should use. The conversion can be customized through declarations in the '''''[[#Transform component|Transform]]''''' enclosed by the '''''VersionConverter'''''.
+
 
+
* '''branch''' - creates a ''version selector'' referencing the latest version on a branch named from the plain version, i.e. "3.1.0" will be translated into "3.1.0/LATEST".
+
* '''tag''' - creates a ''version selector'' referencing the plain version as a tag on the default branch. i.e. "3.1.0" will be translated into "main/3.1.0". With the tag converter it is possible to use a change number or timestamp instead of the tag.
+
 
+
The specified version converter ''type'' may be a custom type which must be declared using the Buckminster <code>org.eclipse.buckminster.core.versionConverters</code> extension point. The [[Extending Buckminster with a custom version converter]] document explains how this can be done.
+
|-
+
| '''versionType'''
+
| xs:string
+
| 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 component|VersionConverter ]]''''' must be done. A sequence of '''''Transform'''''s 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 <code>transform</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items for ''transform''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    ''<[[#SearchPath component|searchPath]]>''
+
        ''<[[#Provider component|provider]]>''
+
            ''<[[#VersionConverter component|versionConverter ]]>''
+
              '''<transform
+
                    '''toPattern="xs:string"'''
+
                    '''toReplacement="xs:string"'''
+
                    '''fromPattern="xs:string"'''
+
                    '''fromReplacement="xs:string"''' />'''
+
            ''</versionConverter>''
+
        ''</provider>''
+
      ''</searchPath>''
+
''</rmap>''
+
 
+
The <code>transform</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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):
+
*Given is a version string ''3.1.0''.
+
*Assuming a first '''''Transform ''''' with <code>fromPattern="\."</code> and <code>fromReplacement="_"</code>, the version name ''3.1.0'' would be mapped to ''3_1_0''.
+
*Furthermore, assuming a second '''''Transform''''' with <code>fromPattern="^(.*)$"</code> and <code>fromReplacement="v$1"</code> the transformed ''3_1_0'' would be mapped further to ''v3_1_0''.
+
|- valign="top"
+
| '''fromReplacement'''
+
| xs:string
+
| -
+
| ''fromReplacement'' builds a pair with the attribute ''fromPattern''.
+
 
+
SEE DETAILED EXPLANATION FOR THE ''fromPattern'' ATTRIBUTE.
+
|- valign="top"
+
| '''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''):
+
*Given is a previously transformed version string ''v3_1_0''.
+
*Assuming the second '''''Transform ''''' with <code>toPattern="^v(.*)$"</code> and <code>toReplacement="$1"</code>, the version name ''v3_1_0'' would be mapped to ''3_1_0''.
+
*Furthermore, assuming the first '''''Transform''''' with <code>toPattern="_"</code> and <code>toReplacement="."</code> the transformed ''3_1_0'' would be mapped back to ''3.1.0''.
+
|- valign="top"
+
| '''toReplacement'''
+
| xs:string
+
| -
+
| ''toReplacement'' builds a pair with the attribute ''toPattern''.
+
 
+
SEE DETAILED EXPLANATION FOR THE ''toPattern'' ATTRIBUTE.
+
|}
+
 
+
<includeonly>
+
<pre>
+
<rm:versionConverter type="tag">
+
    <!-- Converts 1.0.0.M1sp002 to v1_0_0_M1sp002 by first converting
+
    all '.' to '_' and then prefixing the result with 'v'. The
+
    convertsion is bidirectional
+
    -->
+
    <rm:transform fromPattern="\." fromReplacement="_"
+
    toPattern="_" toReplacement="." />
+
    <rm:transform fromPattern="^(.*)$" fromReplacement="v$1"
+
    toPattern="^v(.*)$" toReplacement="$1" />
+
  </rm:versionConverter>
+
</pre>
+
</includeonly>
+
 
+
===Locator component===
+
A '''''Locator''''' acts as a pointer to a '''''[[#SearchPath component|SearchPath]]''''' (defined in the enclosing '''''[[#Rmap component|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|CQUERY]] or from [[#CSPEC|CSPEC]]s which may be resolved recursively as part of the former.
+
 
+
The framework will consult the '''''Locator'''''s (and '''''[[#Redirect component|Redirect]]'''''s) in order to find the search path holding the information to analyse and obtain the components required to resolve a component query. An '''''[[#Rmap component|Rmap]]''''' may specify multiple '''''Locator'''''s (and '''''[[#Redirect component|Redirect]]'''''s). 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 '''''Locator'''''s (and '''''[[#Redirect component|Redirect]]'''''s) in the order in which they appear in the '''''[[#Rmap component|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 component|Redirect]]''''') pattern matches the queried component.
+
 
+
'''NOTE''' that different locators in an '''''[[#Rmap component|Rmap]]''''' may point to the same '''''[[#SearchPath component|SearchPath]]'''''.   
+
 
+
The '''''Locator''''' component is represented by a <code>locator</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items for ''locator''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    '''<locator'''
+
            '''pattern="xs:string"'''
+
            '''searchPathRef="xs:string"'''/>
+
''</rmap>''
+
 
+
The <code>locator</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|SearchPath]]''''' with the name given in the '''''Locator''''''s <code>searchPathRef</code> attribute which refers to the name given in '''''[[#SearchPath component|SearchPath]]''''''s <code>name</code> attribute.
+
|- valign="top"
+
| '''searchPathRef'''
+
| xs:string
+
| -
+
| Specifies the name of the search path (as given in a '''''[[#SearchPath component|SearchPath]]''''''s <code>name</code> attribute in the enclosing '''''[[#Rmap component|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 <code>pattern</code> attribute.
+
 
+
'''NOTE''' that different locators in an '''''[[#Rmap component|Rmap]]''''' may point to the same '''''[[#SearchPath component|SearchPath]]'''''.
+
|}
+
 
+
 
+
===Redirect component===
+
A '''''Redirect''''' acts as a pointer to an '''''[[#Rmap component|Rmap]]''''' URL for component requests matching a component name pattern specified by the Redirect.
+
 
+
Redirect effectively works like an import for '''''[[#Locator component|Locator]]'''''s, '''''Redirect'''''s and '''''[[#SearchPath component|SearchPath]]'''''s in the appointed external Rmap.  Just as a '''[[#Locator component|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|CQUERY]] or from [[#CSPEC|CSPEC]]s which may be resolved recursively as part of the former.
+
 
+
The framework will consult the Redirects (and '''[[#Locator component|Locator]]'''s) in order to find the search path holding the information to analyse and obtain the components required to resolve a component query. An '''''[[#Rmap component|Rmap]]''''' may specify multiple Redirects (and '''[[#Locator component|Locator]]'''s). 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 '''[[#Locator component|Locator]]'''s in the current Rmap.
+
 
+
'''NOTE''' that the resolver will traverse the '''''Redirect'''''s (and '''[[#Locator component|Locator]]'''s) in the order in which they appear in the '''''[[#Rmap component|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 component|Locator]]''') pattern matches the queried component.
+
 
+
'''NOTE''' that different redirects in an '''''[[#Rmap component|Rmap]]''''' may point to the same Rmap URL.
+
 
+
The '''''Redirect''''' component is represented by a <code>redirect</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items for ''redirect''.
+
 
+
''<[[#Rmap component|rmap]]>''
+
    '''<redirect'''
+
            '''pattern="xs:string"'''
+
            '''href="com:URL"''' />
+
''</rmap>''
+
 
+
The <code>redirect</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|Rmap]] specified as a URL in the '''''Redirect''''''s <code>href</code> attribute.
+
|- valign="top"
+
| '''href'''
+
| com:URL
+
| -
+
| Specifies the URL of an external '''''[[#Rmap component|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 <code>pattern</code> attribute.
+
 
+
'''NOTE''' that different redirects in an '''''[[#Rmap component|Rmap]]''''' may point to the same external Rmap URL.
+
|}
+
 
+
==RMAP sample==
+
<pre>
+
<?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>
+
</pre>
+
 
+
 
+
 
+
 
+
=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 [[#RMAP (Resource Map)|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 component|componentQuery]]
+
      resourceMap="xs:string" ?
+
      properties="xs:string" ?
+
      shortDesc="xs:string" ?
+
      failOnResolveException="xs:boolean" ?>
+
    <documentation/> ?
+
    '''<[[#RootRequest component|rootRequest]]'''
+
          '''name="xs:string"'''
+
          category="xs:string" ?  '''&lt;!-- DEPRECATED --&gt;'''
+
          componentType="xs:string" ?
+
          versionDesignator="xs:string" ?
+
          versionType="xs:string" ? '''>'''
+
    [
+
      <[[#Property component|property]]
+
            '''key="com:propertyKey"'''
+
            '''value="xs:string"'''
+
            mutable="xs:boolean" ? />
+
    |
+
      <[[#PropertyElement component|propertyElement]]>
+
        ''&lt;!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--&gt;''
+
      </propertyElement>
+
    |
+
      <[[#AdvisorNode component|advisorNode]]
+
            '''namePattern="xs:string"'''
+
            category="xs:string" ?  '''&lt;!-- DEPRECATED --&gt;'''
+
            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" ?    ''&lt;!-- NOT YET SUPPORTED --&gt;''
+
            branch="xs:string" ?              ''&lt;!-- NOT YET SUPPORTED --&gt;''
+
            resolutionPath="xs:string" ? />    ''&lt;!-- NOT YET SUPPORTED --&gt;''   
+
        <documentation/> ?
+
        [
+
          <[[#Property component|property]]
+
                '''key="com:propertyKey"'''
+
                '''value="xs:string"'''
+
                mutable="xs:boolean" ? />
+
          |
+
          <[[#PropertyElement component|propertyElement]]>
+
              ''&lt;!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--&gt;''
+
          </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 <code>componentQuery</code> 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 (Resource Map)|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 component|RootRequest]]''''' and optional '''''[[#AdvisorNode component|AdvisorNode]]''''', '''''[[#Property component|Property]]''''' and '''''[[#PropertyElement component|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 component|rootRequest]]>'''
+
    [ <[[#Property component|property]]/> | <[[#PropertyElement component|propertyElement]]/> | <[[#AdvisorNode component|advisorNode]]/> ] *
+
'''</componentQuery>'''
+
 
+
The <code>componentQuery</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| resourceMap
+
| xs:string
+
| -
+
| The value of this attribute MUST BE a URL referencing a Buckminster [[#RMAP (Resource Map)|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 component|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 <code>org.eclipse.buckminster.core.queryResolvers</code> extension point. Buckminster provides reference implementations for two resolvers: 'local' and 'rmap'. [[Extending Buckminster with a custom query resolver]] explains the details of doing this.
+
|- valign="top"
+
| 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).
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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 component|RootRequest]]''''' specifies the top-level component that Buckminster should resolve and/or materialize as part of '''''[[#ComponentQuery component|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 <code>rootRequest</code> 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 component|componentQuery]]>''
+
    '''<rootRequest'''
+
          '''name="xs:string"'''
+
          category="xs:string" ? '''&lt;!-- DEPRECATED --&gt;'''
+
          componentType="xs:string" ?
+
          versionDesignator="xs:string" ?
+
          versionType="xs:string" ? '''/>'''
+
''</componentQuery>''
+
 
+
The <code>rootRequest</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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. <code>org.eclipse.buckminster.core</code>).
+
 
+
NOTE that the name may point to a virtual component which is an assembly of multiple physical (or virtual) components.
+
|- valign="top"
+
| 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 component|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 component|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 component|RootRequest]]''''' states that it will expect a certain component category from the Provider. We can distinguish the following scenarios:
+
*IF a ''RootRequest'' specifies no category
+
*OR IF ''RootRequest'' specifies a category that is matched by ''managedCategories'' on a ''Provider'',
+
**THEN Buckminster will consult this Provider during the resolution and materialization process.
+
*IF a ''RootRequest'' specifies a category AND NO ''managedCategories'' are specified on a ''Provider'',
+
**THEN Buckminster will consider that Provider to handle all categories and will consult this Provider during the resolution and materialization process.
+
*IF a ''RootRequest'' specifies a category AND it matches none of the ''managedCategories'' specified on a ''Provider'',
+
**THEN Buckminster will skip this Provider during the resolution and materialization process.
+
 
+
Buckminster supports the two listed categories. Support for custom component categories can be added via the <code>org.eclipse.buckminster.core.componentCategory</code> extension point. [[Extending Buckminster with a custom component category]] explains the details of doing this.
+
|- valign="top"
+
| componentType
+
| xs:string
+
| -
+
| NOTE that this attribute replaces the ''category'' attribute. Consult the documentation on the extended notion of componentTypes in the [[#Provider component|Provider]] section.
+
 
+
The value of this attribute specifies a component type requirement that MUST BE observed by Buckminster when resolving the enclosing '''''[[#ComponentQuery component|ComponentQuery]]'''''.
+
 
+
Together with the ''componentTypes'' attribute in '''''[[#Provider component|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 component|RootRequest]]''''' states that it will expect a certain component type from the Provider. We can distinguish the following scenarios:
+
*IF a ''RootRequest'' specifies no component type
+
*OR IF ''RootRequest'' specifies a component type that is matched by ''componentTypes'' on a ''Provider'',
+
**THEN Buckminster will consult this Provider during the resolution and materialization process.
+
*IF a ''RootRequest'' specifies a component type AND it matches none of the ''componentTypes'' specified on a ''Provider'',
+
**THEN Buckminster will skip this Provider during the resolution and materialization process.
+
|- valign="top"
+
| 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:
+
*'''[1.2.3, 4.5.6)''' designates versions in the range ''1.2.3 <= x < 4.5.6''
+
*'''[1.2.3, 4.5.6]''' designates versions in the range ''1.2.3 <= x <= 4.5.6''
+
*'''(1.2.3, 4.5.6)''' designates versions in the range ''1.2.3 < x < 4.5.6''
+
*'''(1.2.3, 4.5.6]''' designates versions in the range ''1.2.3 < x <= 4.5.6''
+
*'''1.2.3''' designates versions in the range ''1.2.3 <= x'' (meaning 1.2.3 or later)
+
*'''[1.2.3, 1.2.3]''' designates versions in the range ''1.2.3 <= x <= 1.2.3'' (meaning version 1.2.3 only)
+
|- valign="top"
+
| 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.
+
 
+
*'''OSGi''' - expects a version format of "[0-9].[0-9].[0-9].[a-zA-Z0-9_-]" such as 3.2.0.RC_beta-1.
+
*'''String''' - there are no constraints on what the string can contain except for the special characters designating a version range (see ''versionDesignator''). Versions of type String are compared according to the Java String compare mechanism.
+
*'''Timestamp''' - compares versions formatted as timestamps in ascending order.
+
*'''Triplet''' - is like OSGi with the exception that a version without a qualifier is considered lexically greater then a version that has a qualifier. I.e. 1.0.0 is greater then 1.0.0.beta.
+
 
+
Buckminster provides reference implementations for the four specified version types and provides an extension point <code>org.eclipse.buckminster.core.versionTypes</code> to define custom types. [[Extending Buckminster with a custom version type]] explains the details of doing this.
+
|}
+
 
+
===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 component|ComponentQuery]]''''' for which the AdvisorNode is defined. It is a container for optional '''''[[#Property component|Property]]''''' and '''''[[#PropertyElement component|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 component|RootRequest]]''''' for a ''ComponentQuery''.
+
 
+
The '''''AdvisorNode''''' component is represented by a <code>advisorNode</code> XML element information item. The non-expanded pseudo-schema shows the attribute and element information items for ''AdvisorNode''.
+
 
+
''<[[#ComponentQuery component|componentQuery]]>''
+
      '''<advisorNode'''
+
            '''namePattern="xs:string"'''
+
            category="xs:string" ? '''&lt;!-- DEPRECATED --&gt;'''
+
            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" ?  ''&lt;!-- ATTRIBUTE NOT YET SUPPORTED --&gt;''
+
            branch="xs:string" ?            ''&lt;!-- ATTRIBUTE NOT YET SUPPORTED --&gt;''
+
            resolutionPath="xs:string" ? '''>'''  ''&lt;!-- ATTRIBUTE NOT YET SUPPORTED --&gt;''
+
+
        [ <[[#Property component|property]]/> | <[[#PropertyElement component|propertyElement]]/> ] *
+
      '''</advisorNode>'''
+
</componentQuery>
+
 
+
The <code>advisorNode</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''namePattern'''
+
| xs:string
+
| -
+
| The value of this attribute specifies a component name pattern in regular expression syntax (see [http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html#sum 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.
+
|- valign="top"
+
| 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 '''''[[#Provider component|Provider]]'''''s 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.
+
 
+
 
+
|- valign="top"
+
| componentType
+
| xs:string
+
| -
+
| NOTE that this attribute replaces the ''category'' attribute. Consult the documentation on the extended notion of componentTypes in the [[#Provider commponent)|Provider]] section.
+
 
+
The value of this attribute declares that components matching the ''namePattern'' must be of a particular component type. Specifically, the matched '''''[[#Provider component|Provider]]'''''s must declare this component type as part of their ''componentTypes''.
+
|- valign="top"
+
| 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|CSPEC]] for a component matching the ''namePattern'' are resolved by Buckminster. By default Buckminster would resolve all dependencies of a component.
+
 
+
EXAMPLE:
+
*Assume a component defines an attribute for component tests contained in a component XYZ. Those tests have a dependency on JUnit. If we are interested in this part/attribute of the component only this dependency has to be resolved. If we are interested in another part of this component Buckminster would not have to resolve the JUnit dependency. By specifying the attribute/part we are interested in Buckminster will focus on resolving those dependencies only rather than all of them.
+
|- valign="top"
+
| prune
+
| xs:boolean
+
| true
+
false
+
| When set to <code>true</code> Buckminster will perform a transitive dependency pruning on the component matching ''namePattern'' and all its dependant components. The pruning properties set in the [[#CSPEC|CSPEC]]s of components will control which dependencies will be pruned.
+
|- valign="top"
+
| mutableLevel
+
| cq:Feasability
+
| '''INDIFFERENT'''
+
REJECT
+
 
+
DESIRE
+
 
+
REQUIRE
+
| The ''mutableLevel'' attribute has to be interpreted in connection with the ''mutable'' attribute specified by a '''''[[#Provider component|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 component|Provider]]''''' in an '''''[[#Rmap component|Rmap]]'''''. Together they contribute to an internally computed '''''[[#Provider component|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:
+
*A component query may for example specify that it wants to REJECT providers with mutable content (see ''mutableLevel'' attribute for more details). In this case, assuming a Provider indicates ''mutable="true"'', the Buckminster runtime will skip this Provider during the resolution and materialization process.
+
*In a more complex example it may be that an AdvisorNode specifies a mutableLevel="DESIRE" and a sourceLevel="DESIRE". Assuming two matching Providers with a ''mutable''/''source'' combination of <code>true/true</code> and <code>true/false</code>. In this case the first Provider would be chosen as it would have a higher ranked "Provider score".
+
|- valign="top"
+
| sourceLevel
+
| cq:Feasability
+
| '''INDIFFERENT'''
+
REJECT
+
 
+
DESIRE
+
 
+
REQUIRE
+
| The ''sourceLevel'' attribute has to be interpreted in connection with the ''source'' attribute specified by a '''''[[#Provider component|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.
+
|- valign="top"
+
| allowCircularDependency
+
| xs:boolean
+
| '''false'''
+
true
+
| If set to <code>false</code> (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 <code>true</code> Buckminster will continue the resolution process despite circular dependencies and will ensure that a component is resolved only once.
+
|- valign="top"
+
| skipComponent
+
| xs:boolean
+
| '''false'''
+
true
+
| If set to <code>true</code> the Buckminster resolver will skip the resolution of a component matching the ''namePattern''. By default all components are resolved.
+
|- valign="top"
+
| 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 <code>false</code> Buckminster will NOT USE installed components for components that match the ''namePattern''.
+
 
+
EXAMPLE:
+
*Assuming Buckminster should resolve and materialize the Buckminster source into the workspace. In this case Buckminster would by default resolve the request for the Buckminster component using the Buckminster platform installation - which does not contain source. This would be an example where ''useInstalled'' should be set to <code>false</code>.
+
|- valign="top"
+
| 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 <code>false</code> if previous materializations should not be used for components matching the ''namePattern''.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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:
+
*Assume a request points to a Maven component which has a POM file that is automatically translated into a [[#CSPEC|CSPEC]] by Buckminster. Furthermore, we will assume that the POM actually appoints dependencies on the component (matching ''namePattern'') which are invalid or conflict with dependencies on the the same component handled elsewhere during resolution. In this case the version specified in this attribute will be used instead of the invalid or old version references inferred from the POM.
+
|- valign="top"
+
| 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.
+
 
+
*'''OSGi''' - expects a version format of "[0-9].[0-9].[0-9].[a-zA-Z0-9_-]" such as 3.2.0.RC_beta-1.
+
*'''String''' - there are no constraints on what the string can contain except for the special characters designating a version range (see ''versionDesignator''). Versions of type String are compared according to the Java String compare mechanism.
+
*'''Timestamp''' - compares versions formatted as timestamps in ascending order.
+
*'''Triplet''' - is like OSGi with the exception that a version without a qualifier is considered lexically greater then a version that has a qualifier. I.e. 1.0.0 is greater then 1.0.0.beta.
+
 
+
Buckminster provides reference implementations for the four specified version types and provides an extension point <code>org.eclipse.buckminster.core.versionTypes</code> to define custom types. [[Extending Buckminster with a custom version type]] explains the details of doing this.
+
|- valign="top"
+
| 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 (Resource Map)|RMAP]] URL in a '''''[[ComponentQuery component|ComponentQuery]]'''''). If the value of this attribute is <code>false</code> Buckminster will not attempt a remote resolution otherwise it will.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| branch
+
| xs:string
+
| -
+
| '''ATTRIBUTE NOT YET SUPPORTED.'''
+
Eventually, this will aid in incorporating specific component branches independent of versions.
+
|- valign="top"
+
| 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 component|cspec]]
+
      '''name="xs:string"'''
+
      category="xs:string"  '''&lt;!-- DEPRECATED --&gt;'''
+
      componentType="xs:string" ?
+
      version="xs:string"
+
      versionType="xs:string"
+
      shortDesc="xs:string" >
+
    <documentation/> ?
+
    [
+
      <[[#Dependencies component|dependencies]]>
+
        <[[#Dependency component|dependency]]
+
              '''name="xs:string"'''
+
              category="xs:string" ?
+
              versionDesignator="xs:string" ?
+
              versionType="xs:string" ?>
+
            <[[#ObtainedFrom component|obtainedFrom]]
+
                  '''attribute="xs:string"'''
+
                  '''component="xs:string"''' /> ?
+
        </dependency> *
+
      </dependencies>
+
    |
+
      <[[#Generators component|generators]]>
+
        <[[#Generator component|generator]]
+
              '''attribute="xs:string"'''
+
              '''generates="xs:string"'''
+
              component="xs:string" ? /> *
+
      </generators> 
+
    |
+
      <[[#Artifacts component|artifacts]]>
+
        [
+
          <[[#Public/Private Artifacts|public]]
+
                '''name="xs:string"'''
+
                base="xs:string" ?
+
                path="xs:string" ?
+
                type="xs:string" ? >
+
              <documentation/> ?
+
              [
+
                <[[#Artifacts InstallerHints component|installerHints]]>
+
                  <[[#Property component|property]]
+
                        '''value="xs:string"'''
+
                        '''key="com:PropertyKey"'''
+
                        mutable="xs:boolean" ? /> *
+
                </installerHints>
+
              |
+
                <[[#Artifacts Path component|path]]
+
                      '''path="xs:string"''' />
+
              ] *
+
          </public>
+
          |
+
          <[[#Public/Private Artifacts|private]] ...
+
              ''&lt;!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /artifacts/public ... SEE ABOVE --&gt;''
+
          </private>
+
          ] *
+
      </artifacts>
+
    |
+
      <[[#Groups component|groups]]>
+
        [
+
          <[[#Public/Private Groups|public]]
+
                '''name="xs:string"'''
+
                rebase="xs:string" ? >
+
              <documentation/> ?
+
              [
+
                <[[#Groups InstallerHints component|installerHints]]>
+
                  <[[#Property component|property]]
+
                        '''value="xs:string"'''
+
                        '''key="com:PropertyKey"'''
+
                        mutable="xs:boolean" ? />
+
                </installerHints>
+
              |
+
                <[[#Groups Attribute component|attribute]]
+
                      '''name="xs:string"'''
+
                      component="xs:string" ?
+
                      optional="xs:boolean" ?
+
                      contributor="xs:boolean" ? />
+
              ] *
+
          </public>
+
          |
+
          <[[#Public/Private Groups|private]] ...
+
              ''&lt;!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /groups/public ... SEE ABOVE --&gt;''
+
          </private>
+
          ] *     
+
      </groups>
+
    |
+
      <[[#Actions component|actions]]>
+
        [
+
          <[[#Public/Private Actions|public]]
+
                '''name="xs:string"'''
+
                actor="xs:string" ? >
+
              <documentation/> ?
+
              [
+
                <[[#Actions InstallerHints component|installerHints]]>
+
                  <[[#Property component|property]]
+
                        '''value="xs:string"'''
+
                        '''key="com:PropertyKey"'''
+
                        mutable="xs:boolean" ? /> *
+
                </installerHints>
+
              |
+
                <[[#ActorProperties component|actorProperties]]>
+
                  <[[#Property component|property]]
+
                        '''value="xs:string"'''
+
                        '''key="com:PropertyKey"'''
+
                        mutable="xs:boolean" ? /> *
+
                </actorProperties>
+
              |
+
                <[[#Actions Properties component|properties]]>
+
                  <[[#Property component|property]]
+
                        '''value="xs:string"'''
+
                        '''key="com:PropertyKey"'''
+
                        mutable="xs:boolean" ? /> *
+
                </properties>
+
              |
+
                <[[#Prerequisites component|prerequisites]]
+
                      rebase="xs:string" ?
+
                      alias="xs:string" ?
+
                      includePattern="xs:string" ?
+
                      excludePattern="xs:string" ? >
+
                  <documentation/> ?
+
                  [
+
                    <[[#Prerequisites InstallerHints component|installerHints]]>
+
                        <[[#Property component|property]]
+
                              '''value="xs:string"'''
+
                              '''key="com:PropertyKey"'''
+
                              mutable="xs:boolean" ? />
+
                    </installerHints>
+
                    |
+
                    <[[#Prerequisites Attribute component|attribute]]
+
                          name="xs:string" ?
+
                          component="xs:string" ?
+
                          alias="xs:string" ?
+
                          optional="xs:boolean" ?
+
                          contributor="xs:boolean" ? />
+
                    ] *
+
                </prerequisites>
+
              |
+
                <[[#Products component|products]]
+
                      alias="xs:string" ?
+
                      base="xs:string" ?
+
                      upToDatePolicy="xs:string" ?
+
                      filecount="xs:integer" ?
+
                      pattern="xs:string" ?
+
                      replacement="xs:string" ? >
+
                  [
+
                    <[[#Products Path component|path]]
+
                          '''path="xs:string"''' />
+
                    |
+
                    [
+
                      <[[#Products Public/Private|public]]
+
                            name="xs:string" ?
+
                            base="xs:string" ?
+
                            path="xs:string" ?
+
                            type="xs:string" ? >
+
                          <documentation/> ?
+
                          [
+
                            <[[#=Products Public/Private InstallerHints component=|installerHints]]>
+
                              <property
+
                                    '''value="xs:string"'''
+
                                    '''key="com:PropertyKey"'''
+
                                    mutable="xs:boolean" ? />
+
                            </installerHints>
+
                          |
+
                            <[[#=Products Public/Private Path component=|path]]
+
                                  '''path="xs:string"''' />
+
                          ] *
+
                      </public>
+
                      |
+
                      <[[#Products Public/Private|private]] ...
+
                          ''&lt;!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /actions/public/products/public ... SEE ABOVE --&gt;''
+
                      </private>
+
                      ] *
+
                    ] *
+
                </products>
+
              ] *
+
          </public>
+
          |
+
          <[[#Public/Private Actions|private]] ...
+
              ''&lt;!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /actions/public ... SEE ABOVE --&gt;''
+
          </private>
+
          ] *             
+
      </actions>   
+
    ] *
+
</cspec>
+
 
+
==Cspec component==
+
The '''''Cspec''''' is represented by a <code>cspec</code> 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 component|Dependencies]]''''', '''''[[#Generators component|Generators]]''''', '''''[[#Artifacts component|Artifacts]]''''', '''''[[#Groups component|Groups]]''''' and  '''''[[#Actions component|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 component|dependencies]]/> | <[[#Generators component|generators]]/> | <[[#Artifacts component|artifacts]]/> | <[[#Groups component|groups]]/> | <[[#Actions component|actions]]/> ] *
+
'''</cspec>'''
+
 
+
The <code>cspec</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 '''''[[#CQUERY (Component Query)|CQUERY]]s''''' and '''''[[#RMAP (Resource Map)|RMAP]]s'''''. NOTE that the version information is not part of the name, but is provided in a separate attribute. 
+
|- valign="top"
+
| 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 component|Provider]]''''' and may be required by the resolver when specified in a CQUERY's '''''[[#RootRequest component|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''.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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.
+
 
+
*'''OSGi''' - expects a version format of "[0-9].[0-9].[0-9].[a-zA-Z0-9_-]" such as 3.2.0.RC_beta-1.
+
*'''String''' - there are no constraints on what the string can contain except for the special characters designating a version range (see ''versionDesignator''). Versions of type String are compared according to the Java String compare mechanism.
+
*'''Timestamp''' - compares versions formatted as timestamps in ascending order.
+
*'''Triplet''' - is like OSGi with the exception that a version without a qualifier is considered lexically greater then a version that has a qualifier. I.e. 1.0.0 is greater then 1.0.0.beta.
+
 
+
Buckminster provides reference implementations for the four specified version types and provides an extension point <code>org.eclipse.buckminster.core.versionTypes</code> to define custom types. [[Extending Buckminster with a custom version type]] explains the details of doing this.
+
|- valign="top"
+
| 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]]'''''.
+
 
+
'''''Cspec''''' is a container for one or many '''''[[#Dependency component|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 component|cspec]]>''
+
    '''<dependencies>'''
+
      <[[#Dependency component|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 component|Artifacts]]''''', '''''[[#Groups component|Groups]]''''' or '''''[[#Actions component|Actions]]'''''.
+
 
+
The semantics of the '''''Dependency''''' have to be interpreted exactly as '''''[[#ComponentQuery component|ComponentQuery's]]''''' '''''[[#RootRequest component|RootRequest]]'''''. The Buckminster resolver will have to interprete the dependency as a component request with the resolution context (the [[#RMAP (Resource Map)|RMAP]]) being provided by the original '''''[[#ComponentQuery component|ComponentQuery]]'''''.
+
 
+
'''''Dependency''''' is a container for an optional '''''[[#ObtainedFrom component|ObtainedFrom]]''''' component ('''!!!!!DEPRECATED!!!!!''' - consult '''''[[#Generators component|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 component|cspec]]>''
+
    ''<[[#Dependencies component|dependencies]]>''
+
      '''<dependency'''
+
            '''name="xs:string"'''
+
            category="xs:string" ?  '''&lt;!-- DEPRECATED --&gt;'''
+
            componentType="xs:string" ?
+
            versionDesignator="xs:string" ?
+
            versionType="xs:string" ?>
+
          <[[#ObtainedFrom component|obtainedFrom]]/> ?
+
      '''</dependency>'''
+
    ''</dependencies>''
+
''</cspec>''
+
 
+
The <code>Dependency</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''name'''
+
| xs:string
+
| -
+
| The name of a component that the component captured by this [[#CSPEC (Component Specification)|CSPEC]] depends on.
+
|- valign="top"
+
| 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 component|RootRequest]]'''''.
+
|- valign="top"
+
| componentType
+
| xs:string
+
| -
+
| NOTE that this attribute replaces the ''category'' attribute. Consult the documentation on the extended notion of componentTypes in the [[#Provider component|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 component|RootRequest]]'''''.
+
|- valign="top"
+
| 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 component|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:
+
*'''[1.2.3, 4.5.6)''' designates versions in the range ''1.2.3 <= x < 4.5.6''
+
*'''[1.2.3, 4.5.6]''' designates versions in the range ''1.2.3 <= x <= 4.5.6''
+
*'''(1.2.3, 4.5.6)''' designates versions in the range ''1.2.3 < x < 4.5.6''
+
*'''(1.2.3, 4.5.6]''' designates versions in the range ''1.2.3 < x <= 4.5.6''
+
*'''1.2.3''' designates versions in the range ''1.2.3 <= x'' (meaning 1.2.3 or later)
+
*'''[1.2.3, 1.2.3]''' designates versions in the range ''1.2.3 <= x <= 1.2.3'' (meaning version 1.2.3 only)
+
|- valign="top"
+
| 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 component|RootRequest]]'''''.
+
 
+
*'''OSGi''' - expects a version format of "[0-9].[0-9].[0-9].[a-zA-Z0-9_-]" such as 3.2.0.RC_beta-1.
+
*'''String''' - there are no constraints on what the string can contain except for the special characters designating a version range (see ''versionDesignator''). Versions of type String are compared according to the Java String compare mechanism.
+
*'''Timestamp''' - compares versions formatted as timestamps in ascending order.
+
*'''Triplet''' - is like OSGi with the exception that a version without a qualifier is considered lexically greater then a version that has a qualifier. I.e. 1.0.0 is greater then 1.0.0.beta.
+
 
+
Buckminster provides reference implementations for the four specified version types and provides an extension point <code>org.eclipse.buckminster.core.versionTypes</code> to define custom types. [[Extending Buckminster with a custom version type]] explains the details of doing this.
+
|}
+
 
+
 
+
=====ObtainedFrom component=====
+
'''!!!!!DEPRECATED!!!!!''' - consult '''''[[#Generators component|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 component|Dependency]]'''''.
+
 
+
'''''ObtainedFrom''''' allows to declare a '''''[[#Dependency component|Dependency]]''''' on a component X which is obtained (i.e. generated) via an attribute y in a component Z. The  enclosing '''''[[#Dependency component|Dependency]]''''' would refer to X which would be qualified through the contained ''ObtainedFrom''. NOTE that the [[#Dependencies component|dependencies]] would have to declare a [[#Dependency component|dependency]] on Z as well.
+
 
+
The non-expanded pseudo-schema shows the attribute information items for ''Cspec''.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    ''<[[#Dependencies component|dependencies]]>''
+
      ''<[[#Dependency component|dependency]]>''
+
          '''<obtainedFrom'''
+
                '''attribute="xs:string"'''
+
                '''component="xs:string"''' />
+
      ''</dependency>''
+
    ''</dependencies>''
+
''</cspec>''
+
 
+
The <code>obtainedFrom</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''attribute'''
+
| xs:string
+
| -
+
| Specifies the name of the ''attribute'' from which the component declared in the enclosing [[#Dependency component|Dependency]] can be obtained from. NOTE that the component that declares this attribute is specified in the ''component'' attribute.
+
|- valign="top"
+
| '''component'''
+
| xs:string
+
| -
+
| Specifies the ''component'' which defines the ''attribute'' from which the component declared in the enclosing [[#Dependency component|Dependency]] can be obtained from.
+
|}
+
 
+
===Generators component===
+
The '''''Generators''''' component declares all '''''[[#Generator component|Generator]]'''''s applicable to this '''''[[#Cspec component|Cspec]]''''' and the dependant component tree.
+
 
+
'''''Generators''''' is a container for one or many '''''[[#Generator component|Generator]]''''' components which are represented with correspondingly named XML element information items.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    '''<generators>'''
+
      <[[#Generator component|generator]]/> *
+
    '''</generators>''' 
+
''</cspec>''
+
 
+
 
+
====Generator component====
+
The '''''Generator''''' component has a similar purpose to the deprecated '''''[[#ObtainedFrom component|ObtainedFrom]]''''' but removes its limitation with regard to the applicable scope.
+
 
+
The semantics of '''''[[#ObtainedFrom component|ObtainedFrom]]''''' required that every dependant component in the dependency tree rooted from a given '''''[[#Cspec component|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 component|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 component|Dependency]]''''' in a given '''''[[#Cspec component|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 component|Cspec]]''''' and all dependant ones would than only declare '''''[[#Dependency component|Dependency]]'''''s on X and Z to allow a successful resolution.
+
 
+
The non-expanded pseudo-schema shows the immediate attribute information items for ''Generator''.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    ''<[[#Generators component|generators]]>''
+
      '''<generator'''
+
            '''attribute="xs:string"'''
+
            '''generates="xs:string"'''
+
            component="xs:string" ? />
+
    ''</generators>'' 
+
''</cspec>''
+
 
+
The <code>generator</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|Cspec]]'''''.
+
|- valign="top"
+
| '''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 component|Dependency]]'''' in given '''''[[#Cspec component|Cspec]]''''' and all components in its dependency tree.
+
|- valign="top"
+
| 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 component|Cspec]]'''''.
+
|}
+
 
+
===Artifacts component===
+
The '''''Artifacts''''' component captures one of three approaches (the others are '''''[[#Groups component|Groups]]''''' and '''''[[#Actions component|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/Private Artifacts|Public]]''''' or '''''[[#Public/Private Artifacts|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 component|cspec]]>''
+
    '''<artifacts>'''
+
      [ <[[#Public/Private Artifacts|public]]/> | <[[#Public/Private Artifacts|private]]/> ] *
+
    '''</artifacts>'''
+
''</cspec>''
+
 
+
 
+
====Public/Private Artifacts====
+
'''''Public''''' and '''''Private''''' components contained in an '''''[[#Artifacts component|Artifacts]]''''' component represent the root of a component attribute declaration of type '''''[[#Artifacts component|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 component|Cspec]]''''' that contains this declaration as well as any other '''''[[#Cspec component|Cspec]]''''' that references the local component specification as a dependency.
+
*'''''Private''''' - a private attribute declaration is accessible ONLY from within the local '''''[[#Cspec component|Cspec]]''''' that contains this declaration.
+
 
+
'''''Artifacts''''' is a container for a optional '''''[[#Artifacts InstallerHints component|InstallerHints]]''''' and '''''[[#Artifacts Path component|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 component|cspec]]>''
+
    ''<[[#Artifacts component|artifacts]]>''
+
      '''<public'''
+
            '''name="xs:string"'''
+
            base="xs:string" ?
+
            path="xs:string" ?
+
            type="xs:string" ? >
+
          <documentation/> ?
+
          [ <[[#Artifacts InstallerHints component|installerHints]]/> | <[[#Artifacts Path component|path]]/> ]*   
+
      '''</public>'''
+
    ''</artifacts>''
+
''</cspec>''
+
 
+
The <code>public</code> and <code>private</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|Cspec]]''''' will have to reference both the attribute and its containing component.
+
|- valign="top"
+
| 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''.
+
|- valign="top"
+
| 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 '''''<code>[[#Artifacts Path component|path]]</code>''''' element. It covers the case where the component attribute declaration will only contain one resource (file or folder).
+
|- valign="top"
+
| type
+
| xs:string
+
| -
+
| -
+
|}
+
 
+
 
+
=====Artifacts InstallerHints component=====
+
The '''''InstallerHints''''' component captures information that must be interpreted in the context of '''''[[#Actions component|Actions]]'''''.
+
 
+
NOTE that - originating from a specific internal requirement - this is an evolving concept which provides a general purpose mechanism through the declaration of '''''[[#Property component|Property]]'''''s, 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 component|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 component|cspec]]>''
+
    ''<[[#Artifacts component|artifacts]]>''
+
      ''<[[#Public/Private Artifacts|public]]>''
+
          '''<installerHints>'''
+
            <[[#Property component|property]]/> *
+
          '''</installerHints>'''
+
      ''</public>''
+
    ''</artifacts>''
+
''</cspec>''
+
 
+
=====Artifacts Path component=====
+
The '''''Path''''' component specifies the same information as the ''path'' attribute in the enclosing '''''[[#Public/Private Artifacts|Public]]''''' or '''''[[#Public/Private Artifacts|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/Private Artifacts|Public]]''''' or '''''[[#Public/Private Artifacts|Private]]''''' components.
+
 
+
The non-expanded pseudo-schema shows the attribute information items for ''Artifacts''.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    ''<[[#Artifacts component|artifacts]]>''
+
      ''<[[#Public/Private Artifacts|public]]>''
+
          '''<path'''
+
                '''path="xs:string"''' '''/>'''
+
      ''</public>''
+
    ''</artifacts>''
+
''</cspec>''
+
 
+
The <code>path</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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/Private Artifacts|Public]]''''' or '''''[[#Public/Private Artifacts|Private]]''''' components.
+
 
+
If a component attribute declaration specifies only one path the ''path'' attribute in the enclosing '''''[[#Public/Private Artifacts|Public]]''''' or '''''[[#Public/Private Artifacts|Private]]''''' components may be used for convenience. 
+
|}
+
 
+
===Groups component===
+
The '''''Groups''''' component captures one of three approaches (the others are '''''[[#Artifacts component|Artifacts]]''''' and '''''[[#Actions component|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 component|Artifacts]]''''', '''''[[#Actions component|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/Private Groups|Public]]''''' or '''''[[#Public/Private Groups|Private]]''''' component for which '''''Groups''''' serves as a container.
+
 
+
The non-expanded pseudo-schema shows the immediate element information items for ''Groups''.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    '''<groups>'''
+
      [ <[[#Public/Private Groups|public]]/> | <[[#Public/Private Groups|private]]/> ] *     
+
    '''</groups>'''
+
''</cspec>''
+
 
+
 
+
====Public/Private Groups====
+
'''''Public''''' and '''''Private''''' components contained in a '''''[[#Groups component|Groups]]''''' component represents the root of a component attribute group declaration of type '''''[[#Groups component|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 component|Cspec]]''''' that contains this declaration as well as any other '''''[[#Cspec component|Cspec]]''''' that references the local component specification as a dependency.
+
*'''''Private''''' - a private group declaration is accessible ONLY from within the local '''''[[#Cspec component|Cspec]]''''' that contains this declaration.
+
 
+
'''''Artifacts''''' is a container for a optional '''''[[#Artifacts InstallerHints component|InstallerHints]]''''' and '''''[[#Groups Attribute component|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 component|cspec]]>''
+
    ''<[[#Groups component|groups]]>''
+
      '''<public'''
+
            '''name="xs:string"'''
+
            rebase="xs:string" ? >
+
          <documentation/> ?
+
          [ <[[#Groups InstallerHints component|installerHints]]/> <[[#Groups Attribute component|attribute]]/> ] *
+
      '''</public>''' 
+
    ''</groups>''
+
''</cspec>''
+
 
+
The <code>public</code> and <code>private</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|Cspec]]''''' will have to reference both the group and its containing component.
+
|- valign="top"
+
| 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 component|Groups]]''''' have the same structure as '''''[[#Artifacts InstallerHints component|InstallerHints]]''''' declared in '''''[[#Artifacts component|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 component|Groups]]'''''. It holds a reference to one of '''''[[#Artifacts component|Artifacts]]''''', '''''[[#Groups component|Groups]]''''' or '''''[[#Actions component|Actions]]'''''. 
+
 
+
The non-expanded pseudo-schema shows the immediate attribute information items for ''Attribute''.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    ''<[[#Groups component|groups]]>''
+
      ''<[[#Public/Private Groups|public]]>''
+
          '''<attribute'''
+
                '''name="xs:string"'''
+
                component="xs:string" ?
+
                optional="xs:boolean" ?
+
                contributor="xs:boolean" ? '''/>'''
+
      ''</public>''
+
    ''</groups>''
+
''</cspec>''
+
 
+
The <code>attribute</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''name'''
+
| xs:string
+
| -
+
| The name of '''''[[#Artifacts component|Artifacts]]''''', '''''[[#Groups component|Groups]]''''' or '''''[[#Actions component|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''.
+
|- valign="top"
+
| component
+
| xs:string
+
| -
+
| The component which holds the attribute specified in ''name''.
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| '''true'''
+
false
+
| If <code>true</code>, 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.
+
|- valign="top"
+
| 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 component|Groups]]''''' and '''''[[#Artifacts component|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 component|Artifacts]]''''', '''''[[#Groups component|Groups]]''''' or indeed '''''[[#Actions component|Actions]]''''' as '''''[[#Prerequisites component|Prerequisites]]'''''.
+
 
+
'''''Actions''''' is a container for zero or many '''''[[#Public/Private Actions|Public]]''''' and '''''[[#Public/Private Actions|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 component|cspec]]>''
+
    '''<actions>'''
+
      [ <[[#Public/Private Actions|public]]> | <[[#Public/Private Actions|private]]> ] *             
+
    '''</actions>'''   
+
''</cspec>''
+
 
+
 
+
====Public/Private Actions====
+
'''''Public''''' and '''''Private''''' components contained in an '''''[[#Actions component|Actions]]''''' component represent the root of a component attribute declaration of type '''''[[#Actions component|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 component|Cspec]]''''' that contains this declaration as well as any other '''''[[#Cspec component|Cspec]]''''' that references the local component specification as a dependency.
+
*'''''Private''''' - a private action declaration is accessible ONLY from within the local '''''[[#Cspec component|Cspec]]''''' that contains this declaration.
+
 
+
'''''Public'''''/'''''Private''''' are containers for a optional '''''[[#Actions InstallerHints component|InstallerHints]]''''', '''''[[#ActorProperties component|ActorProperties]]''''', '''''[[#Actions Properties component|Properties]]''''', '''''[[#Prerequisites component|Prerequisites]]''''' and '''''[[#Products component|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 component|cspec]]>''
+
    ''<[[#Actions component|actions]]>''
+
      '''<public'''
+
            '''name="xs:string"'''
+
            actor="xs:string" ?
+
            enabled="xs:boolean" ? >
+
          <documentation/> ?
+
          [ <[[#Actions InstallerHints component|installerHints]]/> | <[[#ActorProperties component|actorProperties]]/> | <[[#Actions Properties component|properties]]/> | <[[#Prerequisites component|prerequisites]]/> | <[[#Products component|products]]/> ] *
+
      '''</public>'''       
+
    ''</actions>''   
+
''</cspec>''
+
 
+
The <code>public</code> and <code>private</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|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:
+
 
+
*Internal Action (an action for which no actor needs to be specified):
+
**'''eclipse.clean''' - requests a clean build from the Eclipse build system
+
**'''eclipse.build''' - requests a full build from the Eclipse build system
+
*"Well-Known" Action (an action that Buckminster actively looks for and calls at certain points during the resolution and materialization process):
+
**'''buckminster.prebind''' - called by the "workspace" materializer after it has completed the download but before the component is bound to the Eclipse workspace. This action is not expected to have a product. Its primary purpose is to rearrange things or copy things into a project.
+
**'''buckminster.bind.entrypoint''' (deprecated) - similar to ''buckminster.prebind''. The difference is that this action must produce the actual project to be bound. The ''buckminster.prebind'' and  ''buckminster.bind.entrypoint'' are mutually exclusive. Both can be specified but only the latter will get called.
+
|- valign="top"
+
| actor
+
| xs:string
+
| ant
+
| Buckminster currently supports one type of actor:
+
*'''ant''' - Actions specifying this actor will make use of Ant and reference Ant scripts that perform the required action.
+
 
+
NOTE that Buckminster's support for actors can be extended via the <code>org.eclipse.buckminster.core.actor</code> extension point.
+
|}
+
<!--
+
|- valign="top"
+
| enabled
+
| xs:boolean
+
| '''true'''
+
false
+
| -
+
|- valign="top"
+
| always
+
| xs:boolean
+
| true
+
'''false'''
+
| -
+
|- valign="top"
+
| assignConsoleSupport
+
| xs:boolean
+
| '''true'''
+
false
+
| -
+
|}
+
-->
+
 
+
=====Actions InstallerHints component=====
+
The '''''InstallerHints ''''' components declared in '''''[[#Actions component|Actions]]''''' have the same structure as '''''[[#Artifacts InstallerHints component|InstallerHints]]''''' declared in '''''[[#Artifacts component|Artifacts]]'''''. Consult this definition for a description of the syntax and semantics.
+
 
+
=====ActorProperties component=====
+
The '''''ActorProperties''''' component serves as container for '''''[[#Property component|property]]'''''s which will be supplied for the specific ''actor'' defined in the enclosing '''''[[#Public/Private Actions|Public]]''''' or '''''[[#Public/Private Actions|Private]]''''' '''''[[#Actions component|Actions]]'''''. They provide the required context in order to allow the ''actor'' specified for and action to execute. (Also see '''''[[#Actions Properties component|Properties]]''''').
+
 
+
Currently, ANT actors are supported and the following properties 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 <code>org.eclipse.ant.buildScripts</code> extension point.
+
 
+
Those properties are supplied using the standard '''''[[#Property component|property]]''''' component with the listed property names as keys.
+
 
+
The non-expanded pseudo-schema shows the immediate element information items for ''ActorProperties''.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    ''<[[#Actions component|actions]]>''
+
      ''<[[#Public/Private Actions|public]]>''
+
          '''<actorProperties>'''
+
            <[[#Property component|property]]/> *
+
          '''</actorProperties>'''
+
      ''</public>''
+
    ''</actions>''   
+
''</cspec>''
+
 
+
=====Actions Properties component=====
+
The '''''Properties''''' component component serves as container for '''''[[#Property component|Property]]'''''s which will be supplied for the specific ''actor'' defined in the enclosing '''''[[#Public/Private Actions|Public]]''''' or '''''[[#Public/Private Actions|Private]]''''' '''''[[#Actions component|Actions]]'''''.
+
 
+
Whereas '''''[[#ActorProperties component|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|property]]''''' component with the listed property names as keys.
+
 
+
The non-expanded pseudo-schema shows the immediate element information items for ''Properties''.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    ''<[[#Actions component|actions]]>''
+
      ''<[[#Public/Private Actions|public]]>''
+
          '''<properties>'''
+
            <[[#Property component|property]]/> *
+
          '''</properties>'''
+
      ''</public>''
+
    ''</actions>''   
+
''</cspec>''
+
 
+
=====Prerequisites component=====
+
The '''''Prerequisites''''' component summarizes all dependencies for the enclosing '''''[[#Public/Private Actions|Public]]''''' or '''''[[#Public/Private Actions|Private]]''''' '''''[[#Actions component|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 component|Actions]]''''' may reference other '''''[[#Artifacts component|Artifacts]]''''', '''''[[#Groups component|Groups]]''''' or indeed '''''[[#Actions component|Actions]]''''' as '''''Prerequisites'''''.
+
 
+
'''''Prerequisites''''' can also be interpreted as an inline group.
+
 
+
'''''Prerequisites''''' is a container for a one or many '''''[[#Prerequisites InstallerHints component|InstallerHints]]''''' and '''''[[#Prerequisites Attribute component|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 component|cspec]]>''
+
    ''<[[#Actions component|actions]]>''
+
      ''<[[#Public/Private Actions|public]]>''
+
          '''<prerequisites'''
+
                rebase="xs:string" ?
+
                alias="xs:string" ?
+
                includePattern="xs:string" ?
+
                excludePattern="xs:string" ? >
+
            <documentation/> ?
+
            [ <[[#Prerequisites InstallerHints component|installerHints]]> | <[[#Prerequisites Attribute component|attribute]]/> ] *
+
          '''</prerequisites>'''
+
      ''</public>''
+
    ''</actions>''   
+
''</cspec>''
+
 
+
 
+
The <code>prerequisites</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| rebase
+
| xs:string
+
| -
+
| Provides a folder path which overrides the ''base'' specified in the '''''[[#Prerequisites Attribute component|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.
+
|- valign="top"
+
| 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|Public/Private]] [[#Actions component|Actions]]'''''  and does NOT provide a reference that may be used anywhere else.
+
|- valign="top"
+
| includePattern
+
| xs:string
+
| -
+
| A regular expression intended to define inclusion rules for component/attributes identifiers of the form <code>&lt;componentName&gt;#&lt;attributeName&gt;</code>. Based on the ''includePattern'' '''''[[#Actions component|Actions]]'''''prerequisites supplied by the appointed attribute will be included if the match the pattern.
+
|- valign="top"
+
| excludePattern
+
| xs:string
+
| -
+
| A regular expression intended to define exclusion rules for component/attributes identifiers of the form <code>&lt;componentName&gt;#&lt;attributeName&gt;</code>. Based on the ''excludePattern'' '''''[[#Actions component|Actions]]'''''prerequisites 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 component|Prerequisites ]]''''' have the same structure as '''''[[#Artifacts InstallerHints component|InstallerHints]]''''' declared in '''''[[#Artifacts component|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 component|Prerequisites]]''''' declared for the enclosing '''''[[#Actions component|Actions]]'''''. 
+
 
+
The non-expanded pseudo-schema shows the immediate attribute information items for ''Attribute''.
+
 
+
''<[[#Cspec component|cspec]]>''
+
    ''<[[#Actions component|groups]]>''
+
      ''<[[#Public/Private Actions|public]]>''
+
          ''<[[#Prequisites component|prerequisites]]>''
+
            '''<attribute'''
+
                  '''name="xs:string"'''
+
                  component="xs:string" ?
+
                  alias="xs:string" ?
+
                  optional="xs:boolean" ?
+
                  contributor="xs:boolean" ? '''/>'''
+
          ''</prerequisites>''
+
      ''</public>''
+
    ''</actions>''
+
''</cspec>''
+
 
+
The <code>attribute</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''name'''
+
| xs:string
+
| -
+
| The name of '''''[[#Artifacts component|Artifacts]]''''', '''''[[#Groups component|Groups]]''''' or '''''[[#Actions component|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 '''''[[#Cspec component|Cspec]]'''''s the component name will have to be specified in ''component''.
+
|- valign="top"
+
| component
+
| xs:string
+
| -
+
| The component which holds the attribute specified in ''name''.
+
|- valign="top"
+
| alias
+
| xs:string
+
| -
+
| If specified the ''alias'' provides a means for more fine-grained, focused references to '''''[[#Prequisites component|Prerequisites]]''''' in actor scripts (currently only Ant scripts).
+
|- valign="top"
+
| optional
+
| xs:boolean
+
| '''true'''
+
false
+
| If <code>true</code>, 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.
+
|- valign="top"
+
| contributor
+
| xs:boolean
+
| '''true'''
+
false
+
| If <code>false</code>, the referenced attribute will NOT be considered when calculating the "up to date policy".
+
|}
+
 
+
=====Products component=====
+
The '''''Products''''' component describes the products of '''''[[#Actions component|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 '''''[[#Products Path component|Path]]''''' OR one or many '''''[[#Public/Private Products|Public]]''''' and '''''[[#Public/Private Products|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 component|cspec]]>''
+
    ''<[[#Actions component|actions]]>''
+
      ''<[[#Public/Private Actions|public]]>''
+
          '''<products'''
+
                alias="xs:string" ?
+
                base="xs:string" ?
+
                upToDatePolicy="xs:string" ?
+
                filecount="xs:integer" ?
+
                pattern="xs:string" ?
+
                replacement="xs:string" ? >
+
            [ <[[#Products Path component|path]]/>
+
              |
+
              [ <[[#Products Public/Private|public]]/> | <[[#Products Public/Private|private]]/> ]*
+
            ]*
+
          '''</products>'''
+
      ''</public>''
+
    ''</actions>''   
+
''</cspec>''
+
 
+
 
+
The <code>products</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| 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|Public/Private]] [[#Actions component|Actions]]'''''  and does NOT provide a reference that may be used anywhere else.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| 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|Public/Private]] [[#Actions component|Actions]]''''' may not have to be executed. The ''upToDatePolicy'' specifies how Buckminster should compare the existing products against an action's '''''[[#Prerequisites component|Prerequisites]]'''''. 
+
 
+
The following policies can be chosen, some of which may require additional information:
+
 
+
*'''''DEFAULT''''' - All products must be declared using explicit paths where all paths denote files rather then directories. All files must exist and all files must be younger then the youngest artifact among the prerequisites.
+
*'''''COUNT''''' - At least ''fileCount'' number of files in the product must be younger then the youngest artifact in the prerequisites.
+
*'''''MAPPER''''' - Each product artifact is matched to a corresponding prerequisite. The match is verbatim or using a regular expression ''pattern'' and a ''replacement''. All files must match and be younger then their respective match. Can also be combined with ''fileCount'' to express a requirement for additional files
+
*'''''NOT_EMPTY''''' - At least one product artifact must be present and all found product artifacts must be younger then the youngest artifact among the prerequisites.
+
 
+
NOTE that this is a convenience mechanism. External changes to the products may cause the applied ''upToDatePolicy'' to deliver an erroneous result.
+
|- valign="top"
+
| fileCount
+
| xs:integer
+
| -
+
| Must be interpreted together with the ''upToDatePolicy'' if '''''COUNT''''' or '''''MAPPER''''' are specified as an up to date policy. 
+
|- valign="top"
+
| pattern
+
| xs:string
+
| -
+
| Must be interpreted together with the ''upToDatePolicy'' if '''''MAPPER''''' is specified as an up to date policy. 
+
|- valign="top"
+
| 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 component|Products]]''''' have the same structure as '''''[[#Artifacts Path component|Path]]''''' declared in '''''[[#Artifacts component|Artifacts]]'''''. Consult this definition for a description of the syntax and semantics.
+
 
+
 
+
======Products Public/Private======
+
'''''Public''''' and '''''Private''''' components contained in an '''''[[#Products component|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 component|Cspec]]''''' that contains this declaration as well as any other '''''[[#Cspec component|Cspec]]''''' that references the local component specification as a dependency.
+
*'''''Private''''' - a private product declaration is accessible ONLY from within the local '''''[[#Cspec component|Cspec]]''''' that contains this declaration.
+
 
+
'''''Public'''''/'''''Private''''' are containers for one or many '''''[[#=Products Public/Private InstallerHints component=|InstallerHints]]''''' and '''''[[##=Products Public/Private Path component=|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 component|cspec]]>''
+
    ''<[[#Actions component|actions]]>''
+
      ''<[[#Public/Private Actions|public]]>''
+
          ''<[[#Products component|products]]>''
+
            '''<public'''
+
                  name="xs:string" ?
+
                  base="xs:string" ?
+
                  path="xs:string" ?
+
                  type="xs:string" ? >
+
                <documentation/> ?
+
                [ <[[#=Products Public/Private InstallerHints component=|installerHints]]/> | <[[#=Products Public/Private Path component=|path]]/> ] *
+
            '''</public>'''
+
          ''</products>''
+
      ''</public>''
+
    ''</actions>''   
+
''</cspec>''
+
 
+
 
+
The <code>public</code> and <code>private</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|Cspec]]''''' will have to reference both the attribute and its containing component.
+
|- valign="top"
+
| 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''.
+
|- valign="top"
+
| 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 '''''<code>[[#=Products Public/Private Path component=|path]]</code>''''' element. It covers the case where the component attribute declaration will only contain one resource (file or folder).
+
|- valign="top"
+
| type
+
| xs:string
+
| -
+
| -
+
|}
+
 
+
=======Products Public/Private InstallerHints component=======
+
The '''''InstallerHints ''''' components declared in '''''[[#Products Public/Private|Products Public/Private]]''''' have the same structure as '''''[[#Artifacts InstallerHints component|InstallerHints]]''''' declared in '''''[[#Artifacts component|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|Products Public/Private]]''''' have the same structure as '''''[[#Artifacts Path component|Path]]''''' declared in '''''[[#Artifacts component|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 component|cspecExtension]]
+
      category="xs:string"
+
      version="xs:string"
+
      versionType="xs:string"
+
      shortDesc="xs:string" >
+
    <documentation/> ?
+
    ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
    [ <[[#Dependencies component|dependencies]]/> | <[[#Generators component|generators]]/> | <[[#Artifacts component|artifacts]]/> | <[[#Groups component|groups]]/> | <[[#Actions component|actions]]/> ] *
+
    ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
    [
+
      <[[#AlterDependencies component|alterDependencies]]>
+
        [
+
          <[[#Dependency component|dependency]]/> * ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
          |
+
          <[[#Remove component|remove]]
+
              '''name="xs:string"''' />
+
          ] *
+
      </alterDependencies>
+
    |
+
      <[[#AlterArtifacts component|alterArtifacts]]>
+
        [
+
          <[[#Public/Private AlterArtifacts|public]]
+
                '''name="xs:string"'''
+
                base="xs:string" ?
+
                path="xs:string" ?
+
                type="xs:string" ? >
+
              <documentation/> ?
+
              ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
              [ <[[#Artifacts InstallerHints component|installerHints]]/> | <[[#Artifacts Path component|path]]/> ]*
+
              ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
              [
+
                <[[#AlterArtifacts AlterInstallerHints component|alterInstallerHints]]>
+
                  [
+
                    <[[#Property component|property]]
+
                          '''value="xs:string"'''
+
                          '''key="com:PropertyKey"'''
+
                          mutable="xs:boolean" ? /> *
+
                    |
+
                    <[[#Remove component|remove]]
+
                          '''key="xs:string"''' />
+
                  ] *
+
                </alterInstallerHints>
+
              |
+
                <[[#RemovePath component|removePath]]
+
                      '''path="xs:string"''' />
+
              ] *
+
          </public>
+
          |
+
          <[[#Public/Private AlterArtifacts|private]] ...
+
              ''&lt;!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /alterArtifacts/public ... SEE ABOVE --&gt;''
+
          </private>
+
          |
+
          <[[#Remove component|remove]]
+
              '''name="xs:string"''' />
+
          ] *
+
      </alterArtifacts>
+
    |
+
      <[[#AlterGroups component|alterGroups]]>
+
        [
+
          <[[#Public/Private AlterGroups|public]]
+
                '''name="xs:string"'''
+
                rebase="xs:string" ? >
+
              <documentation/> ?
+
              ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
              [ <[[#Groups InstallerHints component|installerHints]]/> <[[#Groups Attribute component|attribute]]/> ] *
+
              ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
              [
+
                <[[#AlterGroups AlterInstallerHints component|alterInstallerHints]]>
+
                  [
+
                    <[[#Property component|property]]
+
                          '''value="xs:string"'''
+
                          '''key="com:PropertyKey"'''
+
                          mutable="xs:boolean" ? /> *
+
                    |
+
                    <[[#Remove component|remove]]
+
                          '''key="xs:string"''' />
+
                  ] *
+
                </alterInstallerHints>
+
              |
+
                <[[#AlterGroups AlterAttribute component|alterAttribute]]
+
                      '''name="xs:string"'''
+
                      component="xs:string" ?
+
                      optional="xs:boolean" ?
+
                      contributor="xs:boolean" ? />
+
              |
+
                <[[#Remove component|remove]]
+
                      '''name="xs:string"''' />
+
              ] *
+
          </public>
+
          |
+
          <[[#Public/Private AlterGroups|private]] ...
+
              ''&lt;!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /groups/public ... SEE ABOVE --&gt;''
+
          </private>
+
          |
+
          <[[#Remove component|remove]]
+
              '''name="xs:string"''' />
+
          ] *     
+
      </alterGroups>
+
    |
+
      <[[#AlterActions component|alterActions]]>
+
        [
+
          <[[#Public/Private AlterActions|public]]
+
                '''name="xs:string"'''
+
                actor="xs:string" ? >
+
              <documentation/> ?
+
              ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
              [ <[[#Actions InstallerHints component|installerHints]]/> | <[[#ActorProperties component|actorProperties]]/> | <[[#Actions Properties component|properties]]/> | <[[#Prerequisites component|prerequisites]]/> | <[[#Products component|products]]/> ] *
+
              ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
              [
+
                <[[#AlterActions AlterInstallerHints component|alterInstallerHints]]>
+
                  [
+
                    <[[#Property component|property]]
+
                          '''value="xs:string"'''
+
                          '''key="com:PropertyKey"'''
+
                          mutable="xs:boolean" ? /> *
+
                    |
+
                    <[[#Remove component|remove]]
+
                          '''key="xs:string"''' />
+
                  ] *
+
                </alterInstallerHints>
+
              |
+
                <[[#AlterActorProperties component|alterActorProperties]]>
+
                  [
+
                    <[[#Property component|property]]
+
                          '''value="xs:string"'''
+
                          '''key="com:PropertyKey"'''
+
                          mutable="xs:boolean" ? /> *
+
                    |
+
                    <[[#Remove component|remove]]
+
                          '''key="xs:string"''' />
+
                  ] *
+
                </alterActorProperties>
+
              |
+
                <[[#AlterActions AlterProperties component|alterProperties]]>
+
                  [
+
                    <[[#Property component|property]]
+
                          '''value="xs:string"'''
+
                          '''key="com:PropertyKey"'''
+
                          mutable="xs:boolean" ? /> *
+
                    |
+
                    <[[#Remove component|remove]]
+
                          '''key="xs:string"''' />
+
                  ] *
+
                </alterProperties>
+
              |
+
                <[[#AlterPrerequisites component|alterPrerequisites]]
+
                      rebase="xs:string" ?
+
                      alias="xs:string" ? 
+
                      includePattern="xs:string" ?
+
                      excludePattern="xs:string" ? >
+
                  <documentation/> ?
+
                  ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
                  [ <[[#Groups InstallerHints component|installerHints]]/> <[[#Groups Attribute component|attribute]]/> ] *
+
                  ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
                  [
+
                    <[[#AlterPrerequisites AlterInstallerHints component|alterInstallerHints]]>
+
                        [
+
                          <[[#Property component|property]]
+
                                '''value="xs:string"'''
+
                                '''key="com:PropertyKey"'''
+
                                mutable="xs:boolean" ? /> *
+
                        |
+
                          <[[#Remove component|remove]]
+
                                '''key="xs:string"''' />
+
                        ] *
+
                    </alterInstallerHints>
+
                    |
+
                    <[[#AlterPrerequisites AlterAttribute component|alterAttribute]]
+
                          '''name="xs:string"'''
+
                          component="xs:string" ?
+
                          optional="xs:boolean" ?
+
                          contributor="xs:boolean" ? />
+
                    |
+
                    <[[#Remove component|remove]]
+
                          '''name="xs:string"''' />
+
                    ] *
+
                </alterPrerequisites>
+
              |
+
                <[[#AlterProducts component|alterProducts]]>
+
                  [
+
                    <[[#AlterProducts Path component|path]]
+
                          '''path="xs:string"''' />
+
                    |
+
                    [
+
                      <[[#AlterProducts Public/Private|public]]
+
                            name="xs:string" ?
+
                            base="xs:string" ?
+
                            path="xs:string" ?
+
                            type="xs:string" ? >
+
                          <documentation/> ?
+
                          ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
                          [ <[[#=Products Public/Private InstallerHints component=|installerHints]]/> <[[#=Products Public/Private Path component=|path]]/> ] *
+
                          ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
                          [
+
                            <[[#AlterProducts Public/Private AlterInstallerHints component|alterInstallerHints]]>
+
                              [
+
                                <[[#Property component|property]]
+
                                      '''value="xs:string"'''
+
                                      '''key="com:PropertyKey"'''
+
                                      mutable="xs:boolean" ? /> *
+
                                |
+
                                <[[#Remove component|remove]]
+
                                      '''key="xs:string"''' />
+
                              ] *
+
                            </alterInstallerHints>
+
                          |
+
                            <[[#RemovePath component|removePath]]
+
                                  '''path="xs:string"''' />
+
                          ] *
+
                      </public>
+
                      |
+
                      <[[#AlterProducts Public/Private|private]] ...
+
                          ''&lt;!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /actions/public/products/public ... SEE ABOVE --&gt;''
+
                      </private>
+
                      |
+
                      <[[#RemoveProduct component|removeProduct]]
+
                            '''name="xs:string"''' />
+
                      |
+
                      <[[#RemovePath component|removePath]]
+
                            '''path="xs:string"''' />
+
                      ] *
+
                    ] *
+
                </alterProducts>
+
              ] *
+
          </public>
+
          |
+
          <[[#Public/Private AlterActions|private]] ...
+
              ''&lt;!-- ATTRIBUTES AND ELEMENTS IDENTICAL TO /actions/public ... SEE ABOVE --&gt;''
+
          </private>
+
          |
+
          <[[#Remove component|remove]]
+
              '''name="xs:string"''' />
+
          ] *             
+
      </alterActions>   
+
    ] *
+
</cspecExtension>
+
 
+
==CspecExtension component==
+
The '''''CspecExtension''''' is represented by a <code>cspecExtension</code> 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 (Component Specification)|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 (Component Specification)|CSPEC]]''''' and allows to both declare and alter (override and remove) CSPEC elements.
+
 
+
'''''CspecExtension''''' inherits all the container properties of '''''[[#Cspec component|Cspec]]''''' component with regard to the elements. In addition, it is a container for one or many '''''[[#AlterDependencies component|AlterDependencies]]''''', '''''[[#AlterArtifacts component|AlterArtifacts]]''''', '''''[[#AlterGroups component|AlterGroups]]''''' and  '''''[[#AlterActions component|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 component|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/> ?
+
    ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
    [ <[[#Dependencies component|dependencies]]/> | <[[#Generators component|generators]]/> | <[[#Artifacts component|artifacts]]/> | <[[#Groups component|groups]]/> | <[[#Actions component|actions]]/> ] *
+
    ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
    [ <[[#AlterDependencies component|alterDependencies]]/> | <[[#AlterArtifacts component|alterArtifacts]]/> | <[[#AlterGroups component|alterGroups]]/> | <[[#AlterActions component|alterActions]]/> ] *
+
'''</cspecExtension>'''
+
 
+
The <code>cspecExtension</code> element has the same attributes as '''''[[#Cspec component|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 component|Dependencies]]''''' information.
+
 
+
'''''AlterDependencies ''''' is a container for one or many '''''[[#Dependency component|Dependency]]''''' (inherited from the '''''[[#CSPEC (Component Specification)|CSPEC]]''''' conceptual model) and '''''[[#Remove component|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 component|cspecExtension]]>''
+
    '''<alterDependencies>'''
+
      [
+
        <[[#Dependency component|dependency]]/> * ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
        |
+
        <[[#Remove component|remove]]/>
+
        ] *
+
    '''</alterDependencies>'''
+
''</cspecExtension>''
+
 
+
====Remove component====
+
The '''''Remove''''' component captures the removal of '''''[[#CSPEC (Component Specification)|CSPEC]]''''' artifacts in various places in the '''''[[#CspecExtension component|CspecExtension]]'''''.
+
 
+
NOTE that the removal context is defined by the enclosing element and the remove action is then applied to the corresponding '''''[[#CSPEC (Component Specification)|CSPEC]]''''' artifacts of the given name.
+
 
+
The '''''Remove''''' may be applied to '''''[[#Dependencies component|Dependencies]]''''', '''''[[#Artifacts component|Artifacts]]''''', '''''[[#Groups component|Groups]]''''', '''''[[#Actions component|Actions]]''''' as well as '''''[[#Attributes component|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 component|cspecExtension]]>''
+
    ''<[[#AlterDependencies component|alterDependencies]]>''
+
      '''<remove'''
+
            '''name="xs:string"''' '''/>'''
+
    ''</alterDependencies>''
+
''</cspecExtension>''
+
 
+
The <code>remove</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''name'''
+
| xs:string
+
| -
+
| The name of the artifacts/component attributes which should be removed from the '''''[[#CSPEC (Component Specification)|CSPEC]]'''''.
+
|}
+
 
+
===AlterArtifacts component===
+
The '''''AlterArtifacts''''' component declares alterations (removals and overrides) associated with the '''''[[#Artifacts component|Artifacts]]''''' declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
It is a container for '''''[[#Public/Private AlterArtifacts|Public]]''''', '''''[[#Public/Private AlterArtifacts|Private]]''''' and '''''[[#Remove component|Remove]]'''''. The latter allows to declare the removal of a named '''''[[#Artifacts component|Artifacts]]''''' declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
NOTE that the structure of '''''[[#Artifacts component|Artifacts]]''''' in '''''[[#Cspec component|Cspec]]'''''
+
is replicated. Alterations at any level are identified by the artifact name as provided in the '''''[[#Artifacts component|Artifacts]]''''' declarations.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    '''<alterArtifacts>'''
+
      [ <[[#Public/Private AlterArtifacts|public]]> | <[[#Public/Private AlterArtifacts|private]]/> | <[[#Remove component|remove]]> ] *
+
    '''</alterArtifacts>'''
+
''</cspecExtension>''
+
 
+
 
+
====Public/Private AlterArtifacts====
+
'''''Public''''' and '''''Private''''' ''AlterArtifact'' components inherit all the properties of '''''[[#Public/Private Artifacts|Public/Private Artifacts]]'''''. In addition, they allow to declare alterations (removals and overrides) associated with the '''''[[#Artifacts component|Artifacts]]'''''
+
'''''[[#Artifacts InstallerHints component|InstallerHints]]''''' and '''''[[#Artifacts Attribute component|Attribute]]''''' components of matching ''name''s declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterArtifacts component|alterArtifacts]]>''
+
        '''<public'''
+
              '''name="xs:string"'''
+
              base="xs:string" ?
+
              path="xs:string" ?
+
              type="xs:string" ? '''>'''
+
            <documentation/> ?
+
            ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
            [ <[[#Artifacts InstallerHints component|installerHints]]/> | <[[#Artifacts Path component|path]]/> ]*
+
            ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
            [ <[[#AlterArtifacts AlterInstallerHints component|alterInstallerHints]]/> | <[[#RemovePath component|removePath]]/> ] *
+
        '''</public>'''
+
    ''</alterArtifacts>''
+
''</cspecExtension>''
+
 
+
'''''Public''''' and '''''Private''''' ''AlterArtifact'' inherits all the attributes of '''''[[#Public/Private Artifacts|Public/Private Artifacts]]'''''.
+
 
+
 
+
=====AlterArtifacts AlterInstallerHints component=====
+
The '''''AlterInstallerHints''''' component declares alterations (removals and overrides) associated with the '''''[[#Property component|Property]]'''''s declared in '''''[[#Artifacts InstallerHints component|InstallerHints]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterArtifacts|Public]]'''''. This includes addition of new '''''[[#Property component|Property]]''''' components.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterArtifacts component|alterArtifacts]]>''
+
      ''<[[#Public/Private AlterArtifacts|public]]>''
+
          '''<alterInstallerHints>'''
+
            [ <[[#Property component|property]]/> | <[[#Remove component|remove]]/> ] *
+
          '''</alterInstallerHints>'''
+
      ''</public>''
+
    ''</alterArtifacts>''
+
''</cspecExtension>''
+
 
+
 
+
======Remove component======
+
Denotes the removal of a '''''[[#Property component|Property]]''''' in '''''[[#AlterArtifacts AlterInstallerHints component|AlterInstallerHints]]''''' component. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterArtifacts component|alterArtifacts]]>''
+
      ''<[[#Public/Private AlterArtifacts|public]]>''
+
          ''<[[#Artifacts InstallerHints component|installerHints]]>''
+
            '''<remove'''
+
                  '''key="xs:string"''' '''/>'''
+
          ''</alterInstallerHints>''
+
      ''</public>''
+
    ''</alterArtifacts>''
+
''</cspecExtension>''
+
 
+
=====RemovePath component=====
+
Denotes the removal of a '''''[[#Artifacts Path component|Path]]''''' in '''''[[#AlterArtifacts AlterInstallerHints component|AlterInstallerHints]]''''' component. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterArtifacts component|alterArtifacts]]>''
+
      ''<[[#Public/Private AlterArtifacts|public]]>''
+
          '''<removePath'''
+
                '''path="xs:string"''' '''/>'''
+
      ''</public>''
+
    ''</alterArtifacts>''
+
''</cspecExtension>''
+
 
+
====Remove component====
+
Denotes the removal of the '''''[[#Artifacts component|Artifacts]]''''' component with the matching ''name''. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterArtifacts component|alterArtifacts]]>''
+
        '''<remove'''
+
            '''name="xs:string"''' />
+
    ''</alterArtifacts>''
+
''</cspecExtension>''
+
 
+
===AlterGroups component===
+
The '''''AlterGroups''''' component declares alterations (removals and overrides) associated with the '''''[[#Groups component|Groups]]''''' declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
It is a container for '''''[[#Public/Private AlterGroups|Public]]''''', '''''[[#Public/Private AlterGroups|Private]]''''' and '''''[[#Remove component|Remove]]'''''. The latter allows to declare the removal of correspondingly named '''''[[#Groups component|Groups]]''''' declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
NOTE that the structure of '''''[[#Groups component|Groups]]''''' in '''''[[#Cspec component|Cspec]]'''''
+
is replicated. Alterations at any level are identified by the group name as provided in the '''''[[#Groups component|Groups]]''''' declarations.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    '''<alterGroups>'''
+
      [ <[[#Public/Private AlterArtifacts|public]]> | <[[#Public/Private AlterArtifacts|private]]/> | <[[#Remove component|remove]]> ] *
+
    '''</alterGroups>'''
+
''</cspecExtension>''
+
 
+
====Public/Private AlterGroups====
+
'''''Public''''' and '''''Private''''' ''AlterGroups'' components inherit all the properties of '''''[[#Public/Private Groups|Public/Private Groups]]'''''. In addition, they allow to declare alterations (removals and overrides) associated with the '''''[[#Groups component|Groups]]'''''
+
'''''[[#Groups InstallerHints component|InstallerHints]]''''' and '''''[[#Groups Attribute component|Attribute]]''''' components of matching ''name''s declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterGroups component|alterGroups]]>''
+
        '''<public'''
+
              '''name="xs:string"'''
+
              rebase="xs:string" ? '''>'''
+
            <documentation/> ?
+
            ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
            [ <[[#Groups InstallerHints component|installerHints]]/> | <[[#Groups Attribute component|attribute]]/> ]*
+
            ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
            [
+
              <[[#AlterGroups AlterInstallerHints component|alterInstallerHints]]/> | <[[#AlterGroups AlterAttribute component|alterAttribute ]]/> | <[[#Remove component|remove]]/> ] *
+
        '''</public>'''
+
    ''</alterGroups>''
+
''</cspecExtension>''
+
 
+
'''''Public''''' and '''''Private''''' ''AlterGroups'' inherits all the attributes of '''''[[#Public/Private Groups|Public/Private Groups]]'''''.
+
 
+
=====AlterGroups AlterInstallerHints component=====
+
The '''''AlterInstallerHints''''' component declares alterations (removals and overrides) associated with the '''''[[#Property component|Property]]'''''s declared in '''''[[#Groups InstallerHints component|InstallerHints]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterGroups|Public]]'''''. This includes additions of new '''''[[#Property component|Property]]''''' components.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterGroups component|alterGroups]]>''
+
      ''<[[#Public/Private AlterGroups|public]]>''
+
          '''<alterInstallerHints>'''
+
            [ <[[#Property component|property]]/> | <[[#Remove component|remove]]/> ] *
+
          '''</alterInstallerHints>'''
+
      ''</public>''
+
    ''</alterGroups>''
+
''</cspecExtension>''
+
 
+
======Remove component======
+
Denotes the removal of a '''''[[#Property component|Property]]''''' in '''''[[#AlterGroups AlterInstallerHints component|AlterInstallerHints]]''''' component. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterGroups component|alterGroups ]]>''
+
      ''<[[#Public/Private AlterGroups |public]]>''
+
          ''<[[#AlterGroups AlterInstallerHints component|alterInstallerHints]]>''
+
            '''<remove'''
+
                  '''key="xs:string"''' '''/>'''
+
          ''</alterInstallerHints>''
+
      ''</public>''
+
    ''</alterGroups >''
+
''</cspecExtension>''
+
 
+
=====AlterGroups AlterAttribute component=====
+
The '''''AlterAttribute''''' component declares alterations (removals and overrides) associated with the '''''[[#Groups Attribute component|Attribute]]''''' of the matching ''name'' declared in '''''[[#Groups component|Groups]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterGroups|Public]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterGroups component|alterGroups ]]>''
+
      ''<[[#Public/Private AlterGroups |public]]>''
+
          '''<alterAttribute'''
+
                '''name="xs:string"'''
+
                component="xs:string" ?
+
                optional="xs:boolean" ?
+
                contributor="xs:boolean" ? '''/>'''
+
      ''</public>''
+
    ''</alterGroups >''
+
''</cspecExtension>''
+
 
+
'''''AlterAttribute''''' inherits all the attributes of '''''[[#Groups Attribute component|Attribute]]''''' in '''''[[#Cspec component|Cspec]]'''''.
+
 
+
=====Remove component=====
+
Denotes the removal of the '''''[[#Groups Attribute component|Attribute]]''''' with matching ''name'' declared in '''''[[#Groups component|Groups]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterGroups|Public]]'''''. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterArtifacts component|alterArtifacts]]>''
+
      ''<[[#AlterGroups AlterAttribute component|alterAttribute ]]>
+
          '''<remove'''
+
            '''name="xs:string"''' />
+
      ''<alterAttribute>
+
    ''</alterArtifacts>''
+
''</cspecExtension>''
+
 
+
====Remove component====
+
Denotes the removal of the '''''[[#Groups component|Groups]]''''' component with the matching ''name''. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterGroups component|alterGroups]]>''
+
        '''<remove'''
+
            '''name="xs:string"''' />
+
    ''</alterGroups>''
+
''</cspecExtension>''
+
 
+
===AlterActions component===
+
The '''''AlterActions''''' component declares alterations (removals and overrides) associated with the '''''[[#Actions component|Actions]]''''' declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
It is a container for '''''[[#Public/Private AlterActions|Public]]''''', '''''[[#Public/Private AlterActions|Private]]''''' and '''''[[#Remove component|Remove]]'''''. The latter allows to declare the removal of correspondingly named '''''[[#Actions component|Actions]]''''' declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
NOTE that the structure of '''''[[#Actions component|Actions]]''''' in '''''[[#Cspec component|Cspec]]'''''
+
is replicated. Alterations at any level are identified by the group name as provided in the '''''[[#Actions component|Actions]]''''' declarations.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    '''<alterActions>'''
+
      [ <[[#Public/Private AlterActions|public]]/> | <[[#Public/Private AlterActions|private]]/> | <[[#Remove component|remove]]> ] *             
+
    '''</alterActions>'''   
+
''</cspecExtension>''
+
 
+
 
+
====Public/Private AlterActions====
+
'''''Public''''' and '''''Private''''' ''AlterActions'' components inherit all the properties of '''''[[#Public/Private Actions|Public/Private Actions]]'''''. In addition, they allow to declare alterations (removals and overrides) associated with the '''''[[#Actions component|Actions]]''''' and '''''[[#Actions InstallerHints component|InstallerHints]]''''', '''''[[#ActorProperties component|ActorProperties]]''''', '''''[[#Actions Properties component|Properties]]''''', '''''[[#Prerequisites component|Prerequisites]]''''' and '''''[[#Products component|Products]]''''' components of matching ''name''s declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
      ''<[[#AlterActions component|alterActions]]>''
+
        '''<public'''
+
                '''name="xs:string"'''
+
                actor="xs:string" ? '''>'''
+
              <documentation/> ?
+
              ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
              [ <[[#Actions InstallerHints component|installerHints]]/> | <[[#ActorProperties component|actorProperties]]/> | <[[#Actions Properties component|properties]]/> | <[[#Prerequisites component|prerequisites]]/> | <[[#Products component|products]]/> ] *
+
              ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
              [ <[[#AlterActions AlterInstallerHints component|alterInstallerHints]]/> | <[[#AlterActorProperties component|alterActorProperties]]/> | <[[#AlterActions AlterProperties component|alterProperties]]/> | <[[#AlterPrerequisites component|alterPrerequisites]]/> | <[[#AlterProducts component|alterProducts]]/> ] *
+
        '''</public>'''
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
'''''Public''''' and '''''Private''''' ''AlterActions'' inherits all the attributes of '''''[[#Public/Private Actions|Public/Private Actions]]'''''.
+
 
+
=====AlterActions AlterInstallerHints component=====
+
The '''''AlterInstallerHints''''' component declares alterations (removals and overrides) associated with the '''''[[#Property component|Property]]'''''s declared in '''''[[#Actions InstallerHints component|InstallerHints]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''. This includes addition of new '''''[[#Property component|Property]]''''' components.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
              '''<alterInstallerHints>'''
+
                [ <[[#Property component|property]]/> | <[[#Remove component|remove]]/> ] *
+
              '''</alterInstallerHints>'''
+
          ''</public>''       
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
======Remove component======
+
Denotes the removal of a '''''[[#Property component|Property]]''''' in '''''[[#Actions InstallerHints component|InstallerHints]]''''' component. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
              ''<[[#AlterActions AlterInstallerHints component|alterInstallerHints]]>''
+
                '''<remove'''
+
                      '''key="xs:string"''' '''/>'''
+
              ''</alterInstallerHints>''
+
          ''</public>''       
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
=====AlterActorProperties component=====
+
The '''''AlterActorProperties ''''' component declares alterations (removals and overrides) associated with the '''''[[#Property component|Property]]'''''s declared in '''''[[#ActorProperties component|ActorProperties]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''. This includes addition of new '''''[[#Property component|Property]]''''' components.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                '''<alterActorProperties>'''
+
                  [ <[[#Property component|property]]/> | <[[#Remove component|remove]]/> ] *
+
                '''</alterActorProperties>'''
+
          ''</public>''   
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
======Remove component======
+
Denotes the removal of a '''''[[#Property component|Property]]''''' in '''''[[#ActorProperties component|ActorProperties]]''''' component. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterActorProperties component|alterActorProperties]]>''
+
                    '''<remove'''
+
                          '''key="xs:string"''' '''/>'''
+
                ''</alterActorProperties>''
+
          ''</public>''   
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
=====AlterActions AlterProperties component=====
+
The '''''AlterProperties ''''' component declares alterations (removals and overrides) associated with the '''''[[#Property component|Property]]'''''s declared in '''''[[#Actions Properties component|Properties]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''. This includes addition of new '''''[[#Property component|Property]]''''' components.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                '''<alterProperties>'''
+
                  [ <[[#Property component|property]]/> | <[[#Remove component|remove]]/> ] *
+
                '''</alterProperties>'''
+
          ''</public>''   
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
======Remove component======
+
Denotes the removal of a '''''[[#Property component|Property]]''''' in '''''[[#Actions Properties component|Properties]]''''' component. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterActions AlterProperties component|alterProperties]]>''
+
                    '''<remove'''
+
                          '''key="xs:string"''' '''/>'''
+
                ''</alterProperties>''
+
          ''</public>''   
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
=====AlterPrerequisites component=====
+
The '''''AlterPrerequisites''''' component declares alterations (removals and overrides) associated with the '''''[[#Prerequisites component|Prerequisites]]''''' declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
'''''AlterPrerequisites''''' components inherit all the properties of '''''[[#Prerequisites component|Prerequisites]]'''''. In addition, they allow to declare alterations (removals and overrides) associated with the '''''[[#Prerequisites component|Prerequisites]]'''''
+
'''''[[#Prerequisites InstallerHints component|InstallerHints]]''''' and '''''[[#Prerequisites Attribute component|Attribute]]''''' components of matching ''name''s declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                '''<alterPrerequisites'''
+
                      rebase="xs:string" ?
+
                      alias="xs:string" ?
+
                      includePattern="xs:string" ?
+
                      excludePattern="xs:string" ? >
+
                  <documentation/> ?
+
                  ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
                  [ <[[#Groups InstallerHints component|installerHints]]/> <[[#Groups Attribute component|attribute]]/> ] *
+
                  ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
                  [ <[[#AlterGroups AlterInstallerHints component|alterInstallerHints]]/> | <[[#AlterGroups AlterAttribute component|alterAttribute ]]/> | <[[#Remove component|remove]]/> ] *
+
                '''</alterPrerequisites>'''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
'''''AlterPrerequisites''''' inherits all the attributes of '''''[[#Prerequisites component|Prerequisites]]'''''.
+
 
+
======AlterPrerequisites AlterInstallerHints component======
+
The '''''AlterInstallerHints''''' component declares alterations (removals and overrides) associated with the '''''[[#Property component|Property]]'''''s declared in '''''[[#Prerequisites InstallerHints component|InstallerHints]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''. This includes additions of new '''''[[#Property component|Property]]''''' components.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterPrerequisites component|alterPrerequisites]]>''
+
                  '''<alterInstallerHints>'''
+
                      [ <[[#Property component|property]]/> | <[[#Remove component|remove]]/> ] *
+
                  '''</alterInstallerHints>'''
+
                ''</alterPrerequisites>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
=======Remove component=======
+
Denotes the removal of a '''''[[#Property component|Property]]''''' in '''''[[#Prerequisites InstallerHints component|InstallerHints]]''''' component. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterPrerequisites component|alterPrerequisites]]>''
+
                  ''<[[#AlterPrerequisites AlterInstallerHints component|alterInstallerHints]]>''
+
                      '''<remove'''
+
                            '''key="xs:string"''' '''/>'''
+
                  ''</alterInstallerHints>''
+
                ''</alterPrerequisites>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
======AlterPrerequisites AlterAttribute component======
+
The '''''AlterAttribute''''' component declares alterations (removals and overrides) associated with the '''''[[#Groups Attribute component|Attribute]]''''' of the matching ''name'' declared in '''''[[#Prerequisites Attribute component|Attributes]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterPrerequisites component|alterPrerequisites]]>''
+
                  '''<alterAttribute'''
+
                        '''name="xs:string"'''
+
                        component="xs:string" ?
+
                        optional="xs:boolean" ?
+
                        contributor="xs:boolean" ? '''/>'''
+
                ''</alterPrerequisites>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
'''''AlterAttribute''''' inherits all the attributes of '''''[[#Groups Attribute component|Attribute]]''''' in '''''[[#Cspec component|Cspec]]'''''.
+
 
+
======Remove component======
+
Denotes the removal of the '''''[[#Prerequisites Attribute component|Attribute]]''''' with matching ''name'' declared in '''''[[#Prerequisites component|Prerequisites]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private Actions|Public]]'''''. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterPrerequisites component|alterPrerequisites]]>''
+
                  '''<remove'''
+
                        '''name="xs:string"''' '''/>'''
+
                ''</alterPrerequisites>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
======AlterProducts component======
+
The '''''AlterProducts''''' component declares alterations (removals and overrides) associated with matching '''''[[#Products component|Products]]''''' declared in '''''[[#Cspec component|Cspec]]'''''.
+
 
+
NOTE that the structure of '''''[[#Products component|Products]]''''' in '''''[[#Cspec component|Cspec]]'''''
+
is replicated. Alterations at any level are identified by matching the ''name''s of the declared '''''[[#Products component|Products]]''''' artifacts and directives.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                '''<alterProducts>'''
+
                    [ <[[#AlterProducts Public/Private|public]]/> | <[[#AlterProducts Public/Private|private]]/> | <[[#RemoveProduct component|removeProduct]]/> | <[[#RemovePath component|removePath]]/> ] *
+
                '''</alterProducts>'''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
=======AlterProducts Public/Private=======
+
'''''Public''''' and '''''Private''''' ''AlterProducts'' components inherit all the properties of '''''[[#Products Public/Private|Products Public/Private]]'''''. In addition, they allow to declare alterations (removals and overrides) associated with the '''''[[#Products component|Products']]'''''
+
'''''[[#=Products Public/Private InstallerHints component=|InstallerHints]]''''' and '''''[[#=Products Public/Private Path component=|Path]]''''' components of matching ''name''/''path'' declared in a '''''[[#Cspec component|Cspec]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterProducts component|alterProducts]]>''
+
                    '''<public'''
+
                            name="xs:string" ?
+
                            base="xs:string" ?
+
                            path="xs:string" ?
+
                            type="xs:string" ? '''>'''
+
                          <documentation/> ?
+
                          ''&lt;!-- INHERITED FROM CSPEC !!! &gt;&gt;&gt; --&gt;''
+
                          [ <[[#=Products Public/Private InstallerHints component=|installerHints]]/> | <[[#=Products Public/Private Path component=|path]]/> ] *
+
                          ''&lt;!-- &lt;&lt;&lt; INHERITED FROM CSPEC !!! --&gt;''
+
                          [ <[[#AlterProducts Public/Private AlterInstallerHints component|alterInstallerHints]]/> | <[[#RemovePath component|removePath]]/> ] *
+
                    '''</public>'''
+
                ''</alterProducts>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
'''''Public''''' and '''''Private''''' inherit all attribute information items from '''''[[#Products Public/Private|Products Public/Private]]'''''.
+
 
+
========AlterProducts Public/Private AlterInstallerHints component========
+
The '''''AlterInstallerHints''''' component declares alterations (removals and overrides) associated with the '''''[[#Property component|Property]]'''''s declared in '''''[[#Artifacts InstallerHints component|InstallerHints]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#AlterProducts Public/Private|Public]]'''''. This includes the addition of new '''''[[#Property component|Property]]''''' components.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterProducts component|alterProducts]]>''
+
                    ''<[[#AlterProducts Public/Private|public]]>''
+
                        '''<alterInstallerHints>'''
+
                          [ <[[#Property component|property]]/> | <[[#Remove component|remove]]/> ] *
+
                        '''</alterInstallerHints>'''
+
                    ''</public>''
+
                ''</alterProducts>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
=========Remove component=========
+
Denotes the removal of a '''''[[#Property component|Property]]''''' in '''''[[#AlterProducts Public/Private AlterInstallerHints component|AlterInstallerHints]]''''' component. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterProducts component|alterProducts]]>''
+
                    ''<[[#AlterProducts Public/Private|public]]>''
+
                        ''<[[#AlterProducts Public/Private AlterInstallerHints component|alterInstallerHints]]>''
+
                          '''<remove'''
+
                                '''key="xs:string"''' '''/>'''
+
                        ''<alterInstallerHints/>
+
                    ''</public>''
+
                ''</alterProducts>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
========AlterProducts Public/Private RemovePath component========
+
Denotes the removal of the '''''[[#=Products Public/Private Path component=|Path]]''''' with matching ''path'' declared in '''''[[#Products component|Products]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterProducts component|alterProducts]]>''
+
                    ''<[[#AlterProducts Public/Private|public]]>''
+
                        '''<removePath'''
+
                              '''path="xs:string"''' '''/>'''
+
                    ''</public>''
+
                ''</alterProducts>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
=======RemoveProduct component=======
+
Denotes the removal of the '''''[[#Product component|Product]]''''' with matching ''name'' declared in '''''[[#Actions component|Actions]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterProducts component|alterProducts]]>''
+
                  '''<removeProduct'''
+
                        '''name="xs:string"''' '''/>'''
+
                ''</alterProducts>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
=======RemovePath component=======
+
Denotes the removal of the '''''[[#=Products Public/Private Path component=|Path]]''''' with matching ''path'' declared in '''''[[#Products component|Products]]''''' of a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|alterActions]]>''
+
          ''<[[#Public/Private AlterActions|public]]>''
+
                ''<[[#AlterProducts component|alterProducts]]>''
+
                  '''<removePath'''
+
                        '''path="xs:string"''' '''/>'''
+
                ''</alterProducts>''
+
          ''</public>'' 
+
      ''</alterActions>''   
+
''</cspecExtension>''
+
 
+
====Remove component====
+
Denotes the removal of '''''[[#Actions component|Actions]]''''' with matching ''name'' declared in a '''''[[#Cspec component|Cspec]]''''' as identified by the ''name'' attribute in the enclosing '''''[[#Public/Private AlterActions|Public]]'''''. See also: '''''[[#Remove component|Remove]]'''''.
+
 
+
''<[[#CspecExtension component|cspecExtension]]>''
+
    ''<[[#AlterActions component|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)|BOM (Bill of Materials)]] or a [[#CQUERY (Component Query)|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 component|mspec]]
+
      '''name="xs:string"'''
+
      '''materializer="xs:string"'''
+
      shortDesc="xs:string"
+
      url="com:URL"
+
      installLocation="xs:string"
+
      conflictResolution="md:ConflictResolution" >
+
    <documentation/> ?
+
    <[[#MspecNode component|mspecNode]]
+
          '''namePattern="xs:string"'''
+
          '''materializer="xs:string"'''
+
          category="xs:string"
+
          resourcePath="com:URL"
+
          exclude="xs:boolean"
+
          installLocation="xs:string"
+
          conflictResolution="md:ConflictResolution" > *
+
      <[[#Unpack component|unpack]] 
+
            expand="xs:boolean"
+
            suffix="xs:string" /> ?
+
      [
+
        <[[#Property component|property]]
+
            '''key="com:propertyKey"'''
+
            '''value="xs:string"'''
+
            mutable="xs:boolean" ? />
+
        |
+
        <[[#PropertyElement component|propertyElement]]>
+
            ''&lt;!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--&gt;''
+
        </propertyElement>
+
      ] *
+
    </mspecNode> *
+
    [
+
      <[[#Property component|property]]
+
            '''key="com:propertyKey"'''
+
            '''value="xs:string"'''
+
            mutable="xs:boolean" ? />
+
    |
+
      <[[#PropertyElement component|propertyElement]]>
+
        ''&lt;!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION--&gt;''
+
      </propertyElement>
+
    ] *
+
</mspec>
+
 
+
==Mspec component==
+
The '''''Mspec''''' is represented by an <code>mspec</code> 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)|BOM (Bill of Materials)]] or a [[#CQUERY (Component Query)|CQUERY (Component Query)]],
+
*directives for component materialization locations
+
*and conflict resolution strategies.
+
 
+
'''''Mspec''''' is a container for one or many '''''[[#MspecNode component|MspecNode]]'''''s,  and '''''[[#Property component|Property]]''''' and '''''[[#PropertyElement component|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 component|mspecNode]]/> *
+
    [ <[[#Property component|property]]/> | <[[#PropertyElement component|propertyElement]]> ] *
+
'''</mspec>'''
+
 
+
The <code>mspec</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''name'''
+
| xs:string
+
| -
+
| The name of the this '''''Mspec''''' which typically relates to the artifact that is being materialized.
+
|- valign="top"
+
| '''materializer'''
+
| xs:string
+
| filesystem
+
...
+
| Specifies the target type of the materialization process.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| url
+
| com:URL
+
| -
+
| A ''url'' to either a '''''[[#BOM (Bill of Materials)|BOM]]''''' or a '''''[[#CQUERY (Component Query)|CQUERY]]''''' which provides or resolves to the set of components for materialization to which this ''Mspec'' should be applied.
+
|- valign="top"
+
| installLocation
+
| xs:string
+
| -
+
| The target location for the materialized components.
+
|- valign="top"
+
| 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:
+
*UPDATE - if encountering components of the same name in the ''installLocation'', the materializer will update them if the component version due to be materialized is more recent than the existing version.
+
*FAIL - if encountering components of the same name in the ''installLocation'', the materializer will fail and the materialization process will be aborted.
+
*KEEP - if encountering components of the same name in the ''installLocation'', the materializer will keep the existing component independent of the component version.
+
*REPLACE - if encountering components of the same name in the ''installLocation'', the materializer will replace the existing component independent of the component version.
+
|}
+
 
+
===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|Unpack]] component and for one or many '''''[[#Property component|Property]]''''' and '''''[[#PropertyElement component|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 component|mspec]]>''
+
    '''<mspecNode'''
+
          '''namePattern="xs:string"'''
+
          '''materializer="xs:string"'''
+
          category="xs:string"
+
          resourcePath="com:URL"
+
          exclude="xs:boolean"
+
          installLocation="xs:string"
+
          conflictResolution="md:ConflictResolution" > *
+
      <[[#Unpack component|unpack]]/> ?
+
      [ <[[#Property component|property]]/> | <[[#PropertyElement component|propertyElement]]> ] *
+
    '''</mspecNode>'''
+
''</mspec>''
+
 
+
The <code>mspecNode</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''namePattern'''
+
| xs:string
+
| -
+
| A regular expression string providing a component name pattern that will be used to match components specified in the '''''[[#BOM (Bill of Materials)|BOM]]''''' or a '''''[[#CQUERY (Component Query)|CQUERY]]''''' referenced by this '''''[[#Mspec component|Mspec]]'''''. The directives in this ''MspecNode'' will be applied to the components with a matching component name.
+
|- valign="top"
+
| '''materializer'''
+
| xs:string
+
| filesystem
+
...
+
| The materializer type to be used for components matching ''namePattern''.
+
|- valign="top"
+
| 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.
+
|- valign="top"
+
| resourcePath
+
| com:URL
+
| -
+
| -
+
|- valign="top"
+
| exclude
+
| xs:boolean
+
| -
+
| If <code>true</code>, components matching ''namePattern'' will be excluded from materialization.
+
|- valign="top"
+
| installLocation
+
| xs:string
+
| -
+
| Specifies the ''installLocation'' relative to the ''installLocation'' in '''''[[#Mspec component|Mspec]]''''' to which components matching ''namePattern'' should be materialized.
+
|- valign="top"
+
| 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:
+
*UPDATE - if encountering components of the same name in the ''installLocation'', the materializer will update them if the component version due to be materialized is more recent than the existing version.
+
*FAIL - if encountering components of the same name in the ''installLocation'', the materializer will fail and the materialization process will be aborted.
+
*KEEP - if encountering components of the same name in the ''installLocation'', the materializer will keep the existing component independent of the component version.
+
*REPLACE - if encountering components of the same name in the ''installLocation'', the materializer will replace the existing component independent of the component version.
+
|}
+
 
+
 
+
====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|MSpecNode]] component. Artifacts in the [[#MSpecNode component|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 component|mspec]]>''
+
    ''<[[#MSpecNode component|mspecNode]]>''
+
      '''<unpack'''
+
            expand="xs:boolean"
+
            suffix="xs:string" '''/>'''
+
    ''</mspecNode>''
+
''</mspec>''
+
 
+
The <code>unpack</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| expand
+
| xs:boolean
+
| '''true'''
+
false
+
| If set to <code>true</code>, the artifact referenced by the enclosing [[#MSpecNode component|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).
+
|- valign="top"
+
| 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.
+
|}
+
 
+
=Shared Language Concepts=
+
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 component|Property]]''''' and '''''[[#PropertyElement component|PropertyElement]]''''' components. Both types may be contained in the following:
+
 
+
*'''''[[#Rmap component|Rmap]]'''''
+
*'''''[[#ComponentQuery component|ComponentQuery]]'''''
+
*'''''[[#AdvisorNode component|AdvisorNode]]'''''
+
 
+
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 component|Property]]''''' and '''''[[#PropertyElement component|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 <code>property</code> 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 <code>property</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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.
+
|- valign="top"
+
| '''value'''
+
| xs:string
+
| -
+
| The value of this attribute declares the value associated with the property referenced by ''propertyKey''.
+
|- valign="top"
+
| 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 component|RMap]]''''' artifacts, then global '''''[[#CQuery component|CQuery]]''''' properties and finally '''''[[#CQuery component|CQuery]]''''' properties defined in '''''[[#AdvisorNode component|AdvisorNode]]s'''''. 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 component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''[[#Replace component|Replace]]''''', '''''[[#ToLower component|ToLower]]''''' and '''''[[#ToUpper component|ToUpper]]''''' components.
+
 
+
The '''''PropertyElement''''' component is represented by a <code>propertyElement</code> 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 component|constant]]
+
              '''value="xs:string"''' />
+
        |
+
        <[[#Format component|format]]
+
              '''format="xs:string"'''>
+
          [
+
            <[[#Constant component|constant]]
+
                  '''value="xs:string"''' />
+
            |
+
            <[[#Format component|format]] ...>
+
                ''&lt;!-- EXPANDED AS ENCLOSING ELEMENT --&gt;''
+
            </format>
+
            |
+
            <[[#PropertyRef component|propertyRef]]
+
                  '''key="com:propertyKey" />
+
            |
+
            <[[#Replace component|replace]]
+
                ''&lt;!-- SEE BELOW FOR DETAILS --&gt;''
+
            </replace>
+
            |
+
            <[[#ToLower component|toLower]]>
+
                ''&lt;!-- SEE BELOW FOR DETAILS --&gt;''
+
            </toLower>
+
            |
+
            <[[#ToUpper component|toUpper]]>
+
                ''&lt;!-- SEE BELOW FOR DETAILS --&gt;''
+
            </toUpper>
+
            |
+
            <[[#Split component|split]]
+
                  '''pattern="xs:string"'''
+
                  style="com:splitType" ?
+
                  limit="xs:integer" ? >
+
                [  <constant/> | <format/> | <propertyRef/> | <replace/>
+
                | <split/> | <toLower/> | <toUpper/> ]* ''&lt;!-- SEE OTHER PARTS FOR DETAILS --&gt;''
+
            </split>
+
            ] *
+
        </format>
+
        |
+
        <[[#PropertyRef component|propertyRef]]
+
                  '''key="com:propertyKey" />
+
        |
+
        <[[#Replace component|replace]]
+
              pattern="xs:string" ?
+
              replacement="xs:string" ?
+
              quotePattern="xs:boolean" ? >
+
            <[[#Match component|match]]
+
                '''pattern="xs:string"'''
+
                '''replacement="xs:string"'''
+
                quotePattern="xs:boolean" ? /> *
+
            [ <constant/> | <format/> | <propertyRef/> | <replace/>
+
            | <split/> | <toLower/> | <toUpper/> ]* ''&lt;!-- SEE OTHER PARTS FOR DETAILS --&gt;''
+
        </replace>
+
        |
+
        <[[#ToLower component|toLower]]>
+
            [ <constant/> | <format/> | <propertyRef/> | <replace/>
+
            | <split/> | <toLower/> | <toUpper/> ]* ''&lt;!-- SEE OTHER PARTS FOR DETAILS --&gt;''
+
        </toLower>
+
        |
+
        <[[#ToUpper component|toUpper]]>
+
            [ <constant/> | <format/> | <propertyRef/> | <replace/>
+
            | <split/> | <toLower/> | <toUpper/> ]* ''&lt;!-- SEE OTHER PARTS FOR DETAILS --&gt;''
+
        </toUpper>
+
        ]
+
    </propertyElement>
+
...
+
 
+
The <code>propertyElement</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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.
+
|- valign="top"
+
| 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 component|RMap]]''''' artifacts, then global '''''[[#CQuery component|CQuery]]''''' properties and finally '''''[[#CQuery component|CQuery]]''''' properties defined in '''''[[#AdvisorNode component|AdvisorNode]]s'''''. 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 component|PropertyElement]]'''''. The semantics of a property declaration with '''''[[#PropertyElement component|PropertyElement]]''''' and '''''Constant''''' are equivalent to a property declaration with '''''[[#Property component|Property]]'''''.
+
 
+
The '''''Constant''''' component is represented by a <code>constant</code> XML element information item.
+
 
+
...
+
    ''<[[#PropertyElement component|propertyElement]]>''
+
        '''<constant'''
+
              '''value="xs:string"''' />
+
    ''</propertyElement>''
+
...
+
 
+
The <code>constant</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''value'''
+
| xs:string
+
| -
+
| The value of this attribute declares the value associated with the property referenced by ''propertyKey'' in the enclosing '''''[[#PropertyElement component|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 <code>format</code> XML element information item. It is a container for zero to many '''''[[#Constant component|Constant]]''''', '''''Format''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''[[#Replace component|Replace]]''''', '''''[[#ToLower component|ToLower]]''''', '''''[[#ToUpper component|ToUpper]]''''' and '''''[[#Split component|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 component|propertyElement]]>''
+
        '''<format'''
+
              '''format="xs:string"'''>
+
          [ <[[#Constant component|constant]]/> | <format/> | <[[#PropertyRef component|propertyRef]]/> | <[[#Replace component|replace]]/> | <[[#Split component|split]]/> | <[[#ToLower component|toLower]]/> | <[[#ToUpper component|toUpper]]/> ]*
+
        '''</format>'''
+
    </propertyElement>
+
...
+
 
+
The <code>format</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''format'''
+
| xs:string
+
| -
+
| The value of this attribute declares the value associated with the property referenced by ''propertyKey'' in the enclosing '''''[[#PropertyElement component|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 component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''[[#Replace component|Replace]]''''', '''''[[#ToLower component|ToLower]]''''', '''''[[#ToUpper component|ToUpper]]''''' and '''''[[#Split component|Split]]''''') provide the parameters that can be referenced in the property value. Only the immediate children of the '''''[[#Format component|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 component|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 component|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 component|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 <code>split</code> XML element information item. It is a container for a required  '''''[[#Match component|Match]]''''' and zero to many '''''[[#Constant component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''Split''''', '''''[[#Replace component|Replace]]''''', '''''[[#ToLower component|ToLower]]''''', '''''[[#ToUpper component|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 component|propertyElement]]>''
+
        '''<split'''
+
              '''pattern="xs:string"'''
+
              style="com:splitType" ?
+
              limit="xs:integer" ? >
+
            [  <[[#Constant component|constant]]/> | <[[#Format component|format]]/> | <[[#PropertyRef component|propertyRef]]/>
+
            | <split/> | <[[#Replace component|replace]]/> | <[[#ToLower component|toLower]]/> | <[[#ToUpper component|toUpper]]/> ]*
+
        '''</split>'''
+
    ''</propertyElement>''
+
...
+
 
+
The <code>split</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''pattern'''
+
| xs:string
+
| -
+
| Defines the regular expression that serves as a split boundary when applied to the input string. 
+
|- valign="top"
+
| style
+
| com.splitType
+
| '''unquoted'''
+
quoted
+
 
+
groups
+
| The value of this attribute determines how the provided ''pattern'' is interpreted:
+
*'''unquoted''' - this is the default and the pattern is interpreted as a standard regular expression
+
*'''quoted''' - the pattern is interpreted as if quoted; this is a convenience mechanism which does not require special characters in the expression to be escaped
+
*'''groups''' - provides the means to use a more sophisticated split with groups defined in the regular expression becoming the result of the split
+
|- valign="top"
+
| 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 component|Property]]''''' or '''''[[#PropertyElement component|PropertyElement]]''''' as well as ALL properties available in the resolution context (System properties, etc as well).
+
 
+
The '''''PropertyRef''''' component is represented by a <code>propertyRef</code> XML element information item. The non-expanded pseudo-schema shows the element information items directly contained by ''propertyRef''.
+
 
+
...
+
    ''<[[#PropertyElement component|propertyElement]]>''
+
        '''<propertyRef'''
+
                  '''key="com:propertyKey" />
+
    ''</propertyElement>''
+
...
+
 
+
The <code>propertyRef</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|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 <code>replace</code> XML element information item. It is a container for a required zero to many '''''[[#Match component|Match]]''''' and zero to many '''''[[#Constant component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''Replace''''', '''''[[#Split component|Split]]''''', '''''[[#ToLower component|ToLower]]''''', '''''[[#ToUpper component|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 component|propertyElement]]>''
+
        '''<replace'''
+
              pattern="xs:string" ?
+
              replacement="xs:string" ?
+
              quotePattern="xs:boolean" ? >
+
            [  <[[#Constant component|constant]]/> | <[[#Format component|format]]/> | <[[#PropertyRef component|propertyRef]]/>
+
            | <replace/> | <[[#Split component|split]]/> | <[[#ToLower component|toLower]]/> | <[[#ToUpper component|toUpper]]/> ]*
+
            <[[#Match component|match]]/> *
+
        '''</replace>'''
+
    ''</propertyElement>''
+
...
+
 
+
The <code>replace</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| 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 component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''Replace''''', '''''[[#Split component|Split]]''''', '''''[[#ToLower component|ToLower]]''''', '''''[[#ToUpper component|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 component|Match]]'''''. If this attribute is present it requires the ''replacement'' attribute to be defined and precludes the use of '''''[[#Match component|Match]]'''''.
+
|- valign="top"
+
| 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 component|Match]]'''''. If this attribute is present it requires the ''pattern'' to be defined on '''''Replace''''' and precludes the use of '''''[[#Match component|Match]]'''''.
+
|- valign="top"
+
| 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 '''''Match'''''s appear they are evaluated in the order of appearance.
+
 
+
The input of '''''Match''''' is provided by its siblings of type '''''[[#Constant component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''[[#Replace component|Replace]]''''', '''''[[#Split component|Split]]''''', '''''[[#ToLower component|ToLower]]''''', '''''[[#ToUpper component|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 <code>match</code> XML element information item. The non-expanded pseudo-schema shows the attribute information items directly contained by ''match''.
+
 
+
...
+
    ''<[[#PropertyElement component|propertyElement]]>''
+
        ''<[[#Replace component|replace]]>''
+
            '''<match'''
+
                '''pattern="xs:string"'''
+
                '''replacement="xs:string"'''
+
                quotePattern="xs:boolean" ? /> *
+
        ''</replace>''
+
    ''</propertyElement>''
+
...
+
 
+
 
+
The <code>match</code> 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):
+
 
+
 
+
{| {{Greytable}}
+
|-
+
! Attribute
+
! Type
+
! Values
+
! Semantics
+
|- valign="top"
+
| '''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 component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''[[#Replace component|Replace]]''''', '''''[[#Split component|Split]]''''', '''''[[#ToLower component|ToLower]]''''', '''''[[#ToUpper component|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.
+
|- valign="top"
+
| '''replacement'''
+
| xs:string
+
| -
+
| Defines the output of the enclosing '''''[[#Replace component|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'''''.
+
|- valign="top"
+
| 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 <code>toLower</code> XML element information item. It is a container for zero to many '''''[[#Constant component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''[[#Replace component|Replace]]''''', '''''[[#Split component|Split]]''''', '''''ToLower''''', '''''[[#ToUpper component|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 component|propertyElement]]>''
+
        '''<toLower>'''
+
            [ <[[#Constant component|constant]]/> | <[[#Format component|format]]/> | <[[#PropertyRef component|propertyRef]]/> | <[[#Replace component|replace]]/> | <[[#Split component|split]]/> | <toLower/> | <[[#ToUpper component|toUpper]]/> ]*
+
        '''</toLower>'''
+
    ''</propertyElement>''
+
...
+
 
+
The <code>toLower</code> 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 <code>toUpper</code> XML element information item. It is a container for zero to many '''''[[#Constant component|Constant]]''''', '''''[[#Format component|Format]]''''', '''''[[#PropertyRef component|PropertyRef]]''''', '''''[[#Replace component|Replace]]''''', '''''[[#Split component|Split]]''''', '''''[[#ToLower component|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 component|propertyElement]]>''
+
        '''<toUpper>'''
+
            [ <[[#Constant component|constant]]/> | <[[#Format component|format]]/> | <[[#PropertyRef component|propertyRef]]/> | <[[#Replace component|replace]]/> | <[[#Split component|split]]/> | <[[#ToLower component|toLower]]/> | <toUpper/> ]*
+
        '''</toUpper>'''
+
    ''</propertyElement>''
+
...
+
 
+
The <code>toUpper</code> element has no attributes.
+
 
+
 
+
 
+
 
+
[[Category:Buckminster]] [[Category:Buckminster Artifacts]] [[Category:Buckminster Artifacts CSPEC]] [[Category:Buckminster Artifacts RMAP]] [[Category:Buckminster Artifacts CQUERY]] [[Category:Buckminster Artifacts BOM]] [[Category:Buckminster Artifacts MSPEC]]
+

Latest revision as of 06:07, 13 November 2009

< To: Buckminster Project

This page has been deprecated. Please use our book The Definitive Guide

Back to the top