Jump to: navigation, search

Difference between revisions of "Buckminster Aggregator User Guide"

(Creating a Maven-conformant p2 repo)
(Replacing page with 'The Buckmintster aggregator has move to b3. Please visit the [http://wiki.eclipse.org/Eclipse_b3/aggregator/manual B3 Aggregator Manual] page instead.')
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
=Introduction=
+
The Buckmintster aggregator has move to b3. Please visit the [http://wiki.eclipse.org/Eclipse_b3/aggregator/manual B3 Aggregator Manual] page instead.
The Aggregator is based on and part of the Buckminster project. Buckminster provides a versatile and adaptable framework supporting build, assembly and deployment processes. It supports a rich set of usecases. One of those - the aggregation of repositories - is the focus of the Buckminster Aggregator tool.
+
 
+
The Aggregator combines p2 repositories from various sources into a new aggregated p2 repository. It can also be configured to produce an aggregated repository that can be used as a p2 and Maven repository. There appears to be an  increasing need for delivering aggregated repositories. The reasons vary from licensing issues to organisational requirements:
+
#'''Owners of a p2 repo for a given project may not be in position to host all required or recommended components due to licensing issues''' - Buckminster's SVN support can serve as an example here, as it requires components available through the main Eclipse p2 repo as well as third-party components. Hence users have to visit several repos for a complete install.
+
#'''Projects want to provide convenient access to their products''' - Installation instructions requiring the user to visit several repos for a complete install are not uncommon. An aggregated repo for all those locations provides a convenient one-stop strategy. The aggregation may support mirroring all consumed p2 repos or simply providing an indirection via a composite repo.
+
#'''Organisations or teams want control over internally used components''' - It may be necessary to have gated access to relevant p2 repos and do an organisational "healthcheck" of those before internal distribution. Furthermore, internally used aggregated repos can provide a common basis for all organisational users.
+
 
+
The Aggregator tool is focused on supporting those specific requirements, rather than the complete set of usecases that Buckminster covers. Furthermore, it:
+
*is '''based on EMF models''' and as such is part of the transition of the Buckminster models to EMF-based models
+
*provides a '''simple user interface''' that does not delve into build specifics and should be accessible by a larger audience
+
*and the aggregation '''can be run headlessly''' once an aggregation definition has been created
+
 
+
=Installation=
+
Start by installing a fresh Eclipse 3.5 SDK from http://www.eclipse.org/downloads/ (The latest version used at the time of writing was http://download.eclipse.org/eclipse/downloads/drops/R-3.5.1-200909170800/index.php)
+
 
+
 
+
==Eclipse SDK installation==
+
{|
+
|- valign="top"
+
| Installation of the Aggregator is done via the Buckminster update site. The following steps describe am installation if the Aggregator editor and engine '''only'''. You may of course perform a complete install of Buckminster. (NOTE in that case though that the Subversive and Subclipse features are mutually exclusive.)
+
 
+
 
+
# Start your Eclipse installation and open the '''''Install New Software wizard'''''. You'll find in under the top menu ''Help''
+
# Click the ''Add...'' button and enter the URL <nowiki>http://download.eclipse.org/tools/buckminster/updates-3.5</nowiki> in the ''Location'' field.
+
# Select the '''''Buckminster Aggregator Editor''''' and click ''Next'' twice.
+
# Accept the Eclipse Public License and click ''Finish''
+
# Restart the IDE once the installation is finished.
+
 
+
|
+
[[Image:Buckminster_Install_Aggregator.png|thumb|right|480x300px|'''''Buckminster Aggregator Editor''''' selection]]
+
 
+
|}
+
 
+
==Headless installation==
+
Installation of the headless version of the Aggregator is similar to a typical headless Buckminster installation. The following steps focus on the installation of the headless Aggregator feature.
+
 
+
#Start by '''Downloading the (headless) director''' which can be found [http://www.eclipse.org/downloads/download.php?file=/tools/buckminster/products/director_latest.zip here] (you may also consult the main [http://www.eclipse.org/buckminster/downloads.html Buckminster Download page]).
+
#Next '''unpack the director''' to a location of your choice. You may want to set the <code>PATH</code> to include the install location and make the director accessible for additional use.
+
#'''Install Buckminster''' with the following command:
+
#*<code>director -r <HEADLESS_REPO>  -d <INSTALL_DIR>  -p Buckminster  -i org.eclipse.buckminster.cmdline.product</code> where
+
#**'''''-r <HEADLESS_REPO>''''' is the headless p2 update site: Current version is: http://download.eclipse.org/tools/buckminster/headless-3.5 (Check the download page for changes of the headless update site.)
+
#**'''''-d <INSTALL_DIR>''''' is the chosen install location of the headless Buckminster
+
#**'''''-p Buckminster''''' is the name of the p2 profile
+
#**'''''-i org.eclipse.cmdline.product''''' is the name of the IU you are installing
+
#'''Install the aggregator feature''' with the following command:
+
#*<code>buckminster install <REPO_URL> <HEADLESS_FEATURE></code> where
+
#**'''''<REPO_URL>''''' is again http://download.eclipse.org/tools/buckminster/headless-3.5
+
#**'''''<HEADLESS_FEATURE>''''' is <code>org.eclipse.buckminster.aggregator.engine.feature</code>
+
 
+
 
+
=Getting started with standard examples=
+
In the following we provide two simple examples that are easy to replicate and should highlight some of the features of the Aggregator.
+
The first example deals with the creation of two variations of a p2 repo. The second shows the Aggregator's Maven support.
+
 
+
==Aggregating a p2 repo==
+
The first sample aggregation is build around Buckminster and its support for Subversive. The objective of this aggregated repo is to:
+
*provide a "one-stop shop" experience
+
*conveniently pull in third-party components that are not hosted at Eclipse
+
*provide this repo as an indirection mechanism if required
+
 
+
===Mirroring contributions===
+
The example aggregation can be downloaded via the Buckminster project SVN and opened in an appropriately set up workbench: [http://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster/trunk/org.eclipse.buckminster.aggregator/samples/buckminster_galileo_mirrored.build buckminster_galileo_mirrored.build]
+
 
+
Buckminster provides support for Subversive. Apart from the Subversive components at Eclipse (http://www.eclipse.org/subversive/), a complete installation will also require Subversive SVN connectors provided by Polarion (http://community.polarion.com/projects/subversive/download/eclipse/2.0/update-site/).
+
We want to create a repo that combines all these components and makes them accessible from one location and for several pre-defined configurations.
+
 
+
[[Image:aggregator_sample_1.jpg|thumb|center|800x750px|'''''Buckminster Aggregator - Sample 1''''']]
+
 
+
This example already includes some of the more advanced aggregation features. Stepping through the model view from the top node the following components can be identified:
+
#The top node '''''Aggregator''''' groups all model definitions regarding '''''Configuration'''''s and '''''Contribution'''''s. Looking at the properties section at the bottom it is shown
+
#*the top node has been provided with a mandatory ''Label'' with the value "Galileo + Buckminster for Subversive"; this will also be the label that would be used when accessing the aggregated repo via the p2 update manager
+
#*the ''Build Root'' identifies the location to which the artifacts of the aggregated repo will be deployed 
+
#The aggregation is defined for three configurations (i.e. os=win32,ws=win32,arch=x86; etc)
+
#*any number of configurations can be defined
+
#*during the aggregation process all dependencies of the ''contributed'' components will be verified for all provided configurations, unless exceptions are defined (see below)
+
#The first '''''Contribution''''' to the aggregation is labeled "Galileo 3.5".
+
#*this contribution represents the simplest example of a contribution
+
#*one '''''Mapped Repository''''' is defined for this contribution (it could be multiple); all that is needed is a user-defined label and the URL of the repository that should be included
+
#*the result of this definition is that the complete Galileo p2 repo will be included in the aggregated repo
+
#The second '''''Contribution''''' is labeled "Subversive SVN connectors" and deals with the inclusion of bundles provided by Polarion. This contribution includes binary configuration-specific artifacts which are only available for win32. If a simple contribution would be defined the aggregation would fail for all non-win32 configurations, and hence the aggregation would fail as a whole.
+
#*this requires a definition of '''''Valid Configurations Rule'''''s that state exceptions
+
#*the rules defined for the the three components in question essentially state that the verification process for those components should only be performed for win32-based configurations
+
#The third '''''Contribution''''' is labeled "Buckminster (latest)". It shows another advanced feature - an '''''Exclusion Rule'''''.
+
#*the objective of the sample repo is to provide convenient setup of Buckminster with Subversive support. Since Buckminster's Subclipse and Subversive support are mutually exclusive, the features relevant for Subclipse can be excluded from the aggregated repo
+
#*this is done using an '''''Exclusion Rule''''' defined for each Installable Unit that should be excluded
+
#At the bottom of the model editor view a list of all included repos is displayed.
+
#*this list allows browsing the contents of all repos
+
#*this part of the model is not editable
+
 
+
The aggregation can be run by right-clicking any node in the model and selecting '''''Build Repository'''''.
+
This example was setup to use a mirroring approach for all contributed repos. Hence, the complete contents of all included can be found in the aggregated repos target location specified under '''''Build Root'''''.
+
 
+
INSERT OVERVIEW OF RESULTING STRUCTURE AND ARTIFACTS ... TBD !!!
+
 
+
Check the next section for a slightly different approach.
+
 
+
===Providing a repo indirection===
+
[[Image:aggregator_sample_not_mirrored.jpg|thumb|right|580x200px|'''''Buckminster Aggregator - mirroring disabled''''']]
+
Mirroring all repo artifacts of your aggregated contributions may neither seem prudent nor necessary. This can be avoided by changing one property for the defined contributions.
+
Each '''''Mapped Repository''''' has property called ''Mirror Artifacts'' which can be set to <code>false</code> in order to prevent copying all artifacts of the contributed repo to the aggregated repo.
+
 
+
The following [http://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster/trunk/org.eclipse.buckminster.aggregator/samples/buckminster_galileo_redirect.build buckminster_galileo_redirect.build] is a variation of the first example with the ''Mirror Artifacts'' property set to <code>false</code> for all contributed repos. Running this aggregation will result in a composite repository that provides an indirection to the contributed repos.
+
 
+
INSERT OVERVIEW OF RESULTING STRUCTURE AND ARTIFACTS ... TBD !!!
+
 
+
==Creating a Maven-conformant p2 repo==
+
[[Image:aggregator_sample_maven.jpg|thumb|right|580x200px|'''''Buckminster Aggregator - Maven result''''']]
+
A powerful feature of the Aggregator is the ability to create aggregated repos that can be consumed as Maven repos, that is providing the structure and artifacts required by Maven. Those repos can in fact be consumed both as p2 and Maven repos. This flexibility is provided due to p2's separation of meta-data about dependencies and the actual location of the referenced artifacts.
+
 
+
In order to create a Maven-conformant aggregate repo all that is required is to set the property '''''Maven Result''''' property of the '''''Aggregator''''' to <code>true</code>. The aggregation deployed to the '''''Build Root''''' location will be a Maven repo.
+
 
+
The sample [http://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster/trunk/org.eclipse.buckminster.aggregator/samples/buckminster_galileo_maven.build buckminster_galileo_maven.build] is a variation of the previous aggregations configured to produce a Maven repo.
+
 
+
INSERT OVERVIEW OF RESULTING STRUCTURE AND ARTIFACTS ... TBD !!!
+
 
+
=Headless support=
+
You will need a headless installation of Buckminster with the Aggregator feature installed.
+
 
+
==Running from the command line==
+
Just type:<pre>buckminster aggregate <options></pre>
+
 
+
For a detailed listing of the available options consult the next section.
+
 
+
==Command line options==
+
{| {{Greytable}}
+
|-
+
! Option
+
! Value
+
! Default
+
! Description
+
 
+
|- valign="top"
+
| '''--buildModel'''
+
| <path to build model>
+
| This value is required
+
| Appoints the aggregation definition that drives the execution
+
 
+
|- valign="top"
+
| '''--action'''
+
| VERIFY
+
 
+
BUILD
+
 
+
CLEAN
+
 
+
CLEAN_BUILD
+
 
+
| BUILD
+
| Specifies the type of the execution.
+
*'''VERIFY''' - verifies model validity and resolves dependencies; no artifacts are copied or created
+
*'''BUILD''' - performs the aggregation and creates the aggregated repository in the target location
+
*'''CLEAN''' - cleans all traces of previous aggregations in the specified target location
+
*'''CLEAN_BUILD''' - performs a CLEAN followed by a BUILD
+
 
+
|- valign="top"
+
| '''--buildId'''
+
| <string>
+
| build-<timestamp in the format yyyyMMddHHmm>
+
| Assigns a build identifier to the aggregation. The identifier is used to identify the build in notification emails. Defaults to: build-<timestamp> where <timestamp> is formatted according as yyyyMMddHHmm, i.e. build-200911031527
+
 
+
|- valign="top"
+
| '''--buildRoot'''
+
| <path to directory>
+
| ''buildRoot'' declared in the aggregation model
+
| Controls the output. Defaults to the build root defined in the aggregation definition.
+
 
+
|- valign="top"
+
| '''--production'''
+
| N/A
+
| N/A
+
| Indicates that the build is running in real production. That means that no mock emails will be sent. Instead, the contacts listed for each contribution will get emails when things go wrong.
+
 
+
|- valign="top"
+
| '''--emailFrom'''
+
| <email>
+
| Address of build master
+
| Becomes the sender of the emails sent from the aggregator.
+
 
+
|- valign="top"
+
| '''--mockEmailTo'''
+
| <email>
+
| ?
+
| Becomes the receiver of the mock-emails sent from the aggregator.
+
 
+
|- valign="top"
+
| '''--mockEmailCC'''
+
| <email>
+
| ?
+
| Becomes the CC receiver of the mock-emails sent from the aggregator.
+
 
+
|- valign="top"
+
| '''--logURL'''
+
| <url>
+
| N/A
+
| The URL that will be pasted into the emails. Should normally point to the a public URL for output log for the aggregator so that the receiver can browse the log for details on failures.
+
 
+
|- valign="top"
+
| '''--subjectPrefix'''
+
| <string>
+
| ?
+
| The prefix to use for the subject when sending emails. Defaults to the label defined in the aggregation definition. The subject is formatted as: "[<subjectPrefix>] Failed for build <buildId>"
+
 
+
|- valign="top"
+
| '''--smtpHost'''
+
| <host name>
+
| ''localhost''
+
| The SMTP host to talk to when sending emails. Defaults to "localhost".
+
 
+
|- valign="top"
+
| '''--smtpPort'''
+
| <port number>
+
| ''25''
+
| The SMTP port number to use when talking to the SMTP host. Default is 25.
+
 
+
|}
+
 
+
==Hudson integration==
+
TBD
+
 
+
=Aggregator model components and specific actions=
+
This section provides an in-depth description and reference of the Aggregator model, listing all model components, properties and available actions.
+
 
+
When referring to ... TBD (conventions)
+
 
+
==Global actions==
+
The following aggregator-specific actions are available via the context menu that can be invoked on any node in the Aggregator model editor:
+
*'''Clean Repository''' - cleans all traces of previous aggregations in the specified target location (''Build Root'')
+
*'''Verify Repository''' - verifies model validity and resolves dependencies; no artifacts are copied or created
+
*'''Build Repository''' - performs the aggregation and creates the aggregated repository in the target location (''Build Root'')
+
*'''Clean then Build Repository''' - performs a ''Clean'' followed by a ''Build''
+
 
+
==Aggregator==
+
The root node of any aggregation model is the Aggregator node. It specifies a number of global properties including the ''Build Root'' (the target location of the aggregated repository) as well as the repo structure (maven-conformant or classic p2 setup).
+
There are several child components some of which can be reference in other parts of the model: [[#Configuration|Configuration]], [[#Contribution|Contribution]], [[#Contact|Contact]], [[#Custom Category|Custom Category]], [[#Validation Repository|Validation Repository]], [[#Maven Mapping|Maven Mapping]].
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Buildmaster
+
| <[[#Contact|Contact]]>?
+
| -
+
| Specifies an optional build master that will be notified of progress and problems if sending of mail is enabled. This is a reference to any [[#Contact|Contact]] that has been added to this Aggregator model.
+
 
+
|- valign="top"
+
|Build Root
+
| <urn>
+
| -
+
| This is a required property specifying the target location of the aggregated repository.
+
 
+
|- valign="top"
+
|Description
+
| <string>
+
| -
+
| An optional description of the aggregated repository that would be visible if accessing the aggregated repository via the p2 update manager.
+
 
+
|- valign="top"
+
|Label
+
| <string>
+
| -
+
| A required label that will be used for the aggregated repository. This would be visible as the repo label if accessing the aggregated repository via the p2 update manager.
+
 
+
|- valign="top"
+
|Maven Mappings
+
| <[[#Maven Mapping|Maven Mapping]]>*
+
| -
+
| References [[#Maven Mapping|Maven Mapping]]s added as children to the Aggregator model root node. See [[#Maven Mapping|Maven Mapping]] for details.
+
 
+
|- valign="top"
+
|Maven Result
+
| '''true'''
+
'''false'''
+
| false
+
| Controls the output structure of the aggregated repo. If '''true''', the aggregated repo will be Maven-conformant. Both the structure and meta-data of the aggregated repository will follow the conventions required by Maven.
+
NOTE that due to the flexibility of p2 (separation of meta-data about dependencies and location of artifacts) the aggregated repo will also function as a valid p2 repository.
+
 
+
|- valign="top"
+
|Packed Strategy
+
| '''Copy'''
+
'''Verify'''
+
 
+
'''Unpack as Sibling'''
+
 
+
'''Unpack'''
+
 
+
'''Skip'''
+
 
+
| Copy
+
| This property controls how packed artifacts found in contributed repositories are handled when building the Aggregation:
+
*'''Copy''' - if the source contains packed artifacts, copy and store them verbatim. No further action
+
*'''Verify''' - same as ''copy'' but unpack the artifact and then discard the result
+
*'''Unpack as Sibling''' - same as ''copy'' but unpack the artifact and store the result as a sibling
+
*'''Unpack''' - use the packed artifact for data transfer but store it in unpacked form
+
*'''Skip''' - do not consider packed artifacts. This option will require unpacked artifacts in the source
+
 
+
|- valign="top"
+
|Sendmail
+
| '''false'''
+
'''true'''
+
| false
+
| Controls whether or not emails are sent when errors are detected during the aggregation process. A value of <code>false</code> disables sending of emails. This includes mock emails.
+
 
+
|- valign="top"
+
|Type
+
| '''S'''
+
'''I'''
+
 
+
'''N'''
+
 
+
'''M'''
+
 
+
'''C'''
+
 
+
'''R'''
+
| S
+
| Indicates the Aggregation type. This is an annotation merely for the benefit of the build master. It is not visible in the resulting repo.
+
*'''S''' - stable
+
*'''I''' - integration
+
*'''N''' - nightly
+
*'''M''' - milestone
+
*'''C''' - continuous
+
*'''R''' - release
+
 
+
|}
+
 
+
===Configuration===
+
An Aggregation may have one or more Configuration definitions. The aggregated repo will be verified for all added configurations. If dependencies for any of the given configurations fails the aggregation as a whole fails. It is however possible to specify exceptions for individual [[#Contribution|Contribution]]s.
+
 
+
A Configuration is a combination of the following properties:
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Architecture
+
|'''X86'''
+
 
+
'''PPC'''
+
 
+
'''X86_64'''
+
| -
+
|Specifies the architecture for which this configuration should be verified.
+
 
+
|- valign="top"
+
|Operating System
+
|'''Win32'''
+
 
+
'''Linux'''
+
 
+
'''MacOSX'''
+
| -
+
|Specifies the operating system for which this configuration should be verified.
+
 
+
|- valign="top"
+
|Window System
+
|'''Win32'''
+
 
+
'''GTK'''
+
 
+
'''Carbon'''
+
 
+
'''cocoa'''
+
| -
+
|Specifies the windowing system for which this configuration should be verified.
+
 
+
|}
+
 
+
===Contribution===
+
Contributions are the key element of any aggregation. Contributions specify which repositories, or parts thereof (category, feature, product, IU), and according to which constraints they should be included in the aggregated repository.
+
A contribution definition may consist of several [[#Mapped Repository|Mapped Repository]] and [[#Maven Mapping|Maven Mapping]] components.
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Contacts
+
| '''<[[#Contact|Contact]]>'''*
+
| -
+
| Zero or more references to [[#Contact|Contact]]s defined in the given Aggregator model. The referenced contacts will be notified if aggregation errors related to the contribution as a whole occur.
+
 
+
|- valign="top"
+
|Description
+
| <string>
+
| -
+
| Optional description of the contribution. This serves documentation purposes and will not end up in the aggregated repository.
+
 
+
|- valign="top"
+
|Enabled
+
| '''true'''
+
'''false'''
+
| true
+
| Disables (false) or enables (true) the contribution for the aggregation process. Note that this may lead to missing dependencies and hence verification errors.
+
 
+
|- valign="top"
+
|Label
+
| <string>
+
| -
+
| Mandatory label for this contribution.
+
 
+
|- valign="top"
+
|Maven Mappings
+
| '''<[[#Maven Mapping|Maven Mapping]]>'''*
+
| -
+
| See [[#Maven Mapping|Maven Mapping]] for details ...
+
 
+
|}
+
 
+
 
+
====Mapped Repository====
+
A [[#Contribution|Contribution]] may define several Mapped Repositories defining the actual content of the contribution. The Aggregator provides a fine-grained control over the contribution from each Mapped Repository through references to [[#Product|Product]]s, [[#Bundle|Bundle]]s, [[#Feature|Feature]]s, [[#Category|Category]]s, [[#Exclusion Rule|Exclusion Rule]]s, [[#Valid Configuration Rule|Valid Configuration Rule]]s.
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Category Prefix
+
| <string>
+
| -
+
| A prefix added to this repositories' label when displayed in the p2 update manager. In the absence of custom categories this allows a useful grouping of repositories in an aggregated repository.
+
 
+
|- valign="top"
+
|Description
+
| <string>
+
| -
+
| Description of the Mapped Repository. For documentation purposes only.
+
 
+
|- valign="top"
+
|Enabled
+
| '''true'''
+
'''false'''
+
| true
+
| Controls whether a Mapped Repository is considered as part of the Contribution. Setting this property to <code>false</code> excludes the repository from the verification and aggregation process.
+
 
+
|- valign="top"
+
|Location
+
| <URL>
+
|
+
| This specifies the location of the repository that should be added to the enclosing Contribution and is a required property.
+
 
+
|- valign="top"
+
|Mirror Artifacts
+
| '''true'''
+
'''false'''
+
| true
+
| Controls whether the contents (artifacts) of the specified repository will be copied to the target location of the aggregated repository.
+
 
+
|}
+
 
+
 
+
=====Product=====
+
Defining Product components allows to add individual Eclipse products to the aggregation (when defined as part of the repository) rather than the complete contents of a given [[#Mapped Repository|Mapped Repository]].
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Enabled
+
| '''true'''
+
'''false'''
+
| true
+
| Controls whether a Product is considered as part of the Contribution. Setting this property to <code>false</code> excludes the product from the verification and aggregation process.
+
 
+
|- valign="top"
+
|Installable Unit
+
| <product IU>
+
| -
+
| A reference to the product to be included in the aggregation.
+
 
+
|- valign="top"
+
|Valid Configurations
+
| <[[#Configuration|Configuration]]>'''*'''
+
| -
+
| References to zero or more configurations for which this product has to be verified. If no references are given the product has to be verified for all [[#Configuration|Configuration]]s defined for the aggregation.
+
 
+
|}
+
 
+
 
+
=====Category=====
+
Defining Category components allows to add individual categories provided by the contributed repository rather than the complete contents of a given [[#Mapped Repository|Mapped Repository]].
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Enabled
+
|'''true'''
+
'''false'''
+
| true
+
| Controls whether a repository Category is considered as part of the Contribution. Setting this property to <code>false</code> excludes the category from the verification and aggregation process.
+
 
+
|- valign="top"
+
|Installable Unit
+
| <IU>
+
| -
+
| A reference to the category to be included in the aggregation.
+
 
+
|- valign="top"
+
|Label Override
+
| <string>
+
| -
+
| New category name used instead of the default name.
+
 
+
|- valign="top"
+
|Valid Configurations
+
| <[[#Configuration|Configuration]]>*
+
| -
+
| References to zero or more configurations for which those category's contents have to be verified. If no references are given the category has to be verified for all [[#Configuration|Configuration]]s defined for the aggregation.
+
 
+
|}
+
 
+
 
+
=====Bundle=====
+
Defining Bundle components allows to add individual Eclipse bundles to the aggregation rather than the complete contents of a given [[#Mapped Repository|Mapped Repository]].
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Enabled
+
|'''true'''
+
'''false'''
+
| true
+
| Controls whether a referenced bundle is considered as part of the Contribution. Setting this property to <code>false</code> excludes the bundle from the verification and aggregation process.
+
 
+
|- valign="top"
+
|Installable Unit
+
| <IU>
+
| -
+
| A reference to the bundle to be included in the aggregation.
+
 
+
|- valign="top"
+
|Valid Configurations
+
|<[[#Configuration|Configuration]]>*
+
| -
+
| References to zero or more configurations for which the referenced bundle has to be verified. If no references are given the bundle has to be verified for all [[#Configuration|Configuration]]s defined for the aggregation.
+
 
+
|}
+
 
+
 
+
=====Feature=====
+
Defining Feature components allows to add individual Eclipse features to the aggregation (when defined as part of the repository) rather than the complete contents of a given [[#Mapped Repository|Mapped Repository]].
+
Furthermore, this component provides the means to group features implicitly into [[#Custom Category|Custom Category]]s.
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Categories
+
| <[[#Custom Category|Custom Category]]>*
+
| -
+
| Optionally references the [[#Custom Category|Custom Category]]s into which the feature should be placed upon aggregation. The relationship to the custom category is bi-directional so adding the feature to a custom category will update this property automatically in the [[#Custom Category|Custom Category]] definition, and vice versa.
+
 
+
|- valign="top"
+
|Enabled
+
|'''true'''
+
'''false'''
+
| true
+
| Controls whether a referenced feature is considered as part of the Contribution. Setting this property to <code>false</code> excludes the feature from the verification and aggregation process.
+
 
+
|- valign="top"
+
|Installable Unit
+
|<IU>
+
| -
+
| A reference to the feature to be included in the aggregation.
+
 
+
|- valign="top"
+
|Valid Configurations
+
| <[[#Configuration|Configuration]]>*
+
| -
+
| References to zero or more configurations for which the referenced feature has to be verified. If no references are given the feature has to be verified for all [[#Configuration|Configuration]]s defined for the aggregation.
+
 
+
|}
+
 
+
 
+
=====Exclusion Rule=====
+
Exclusion Rules are another tool providing control over the aggregated repository. An exclusion rule may reference any bundle, feature or product to exclude. The excluded IU will not be considered in the aggregation and verification process. Each exclusion rule can only reference one IU.
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Description
+
| <string>
+
| -
+
| Description for documentation purposes.
+
 
+
|- valign="top"
+
|Installable Unit
+
| <IU>
+
| -
+
| Reference to any IU (product, feature, bundle) in the enclosing [[#Mapped Repository|Mapped Repository]] that should be excluded from the aggregation.
+
 
+
|}
+
 
+
 
+
=====Valid Configuration Rule=====
+
By default all contributed contents of a [[#Mapped Repository|Mapped Repository]] will have to be verified for all [[#Configuration|Configuration]]s defined for the aggregation. A Valid Configuration Rule allows constrains this and defines and exception. For an IU (product, feature, bundle) referenced by this rule only chosen subset of configuration will be verified and aggregated.
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Description
+
| <string>
+
| -
+
| Description for documentation purposes.
+
 
+
|- valign="top"
+
|Installable Unit
+
| <IU>
+
| -
+
| Reference to any IU (product, feature, bundle) in the enclosing [[#Mapped Repository|Mapped Repository]] for which '''only''' the referenced configurations should be verified.
+
 
+
|- valign="top"
+
|Valid Configurations
+
| <[[#Configuration|Configuration]]>*
+
| -
+
| References to one or more configurations for which the referenced IU has to be verified. This implicitly excludes verification and aggregation for all other [[#Configuration|Configuration]]s defined as part of the aggregation model.
+
 
+
|}
+
 
+
 
+
====Maven Mapping (Contribution)====
+
See [[#Maven Mapping|Maven Mapping]] for a detailed description and list of properties.
+
 
+
===Contact===
+
Defines a resuseable contact which can be referenced in other parts of the model and may be used to send notifications about the aggregation process.
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Email
+
| <email>
+
| -
+
| The email to be used when notifying the contact.
+
 
+
|- valign="top"
+
|Name
+
| <string>
+
| -
+
| Full name of the contact. May be displayed as label when referenced in other parts of the model.
+
 
+
|}
+
 
+
===Custom Category===
+
A Custom Category provides a grouping mechanism for features in the aggregated repository. A custom category can be referenced by [[#Feature|Feature]]s defined for inclusion from a [[#Mapped Repository|Mapped Repository]].
+
The relationship to the between custom category and a [[#Feature|Feature]] is bi-directional. Thus,  adding the feature to a custom category will update this property automatically in the [[#Feature|Feature]] definition, and vice versa.
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Description
+
| <string>
+
| -
+
| Description of the category as displayed when accessing the aggregated repository.
+
 
+
|- valign="top"
+
|Features
+
| <[[#Feature|Feature]]>*
+
| -
+
| [[#Feature|Feature]]s included in this category by reference.
+
 
+
|- valign="top"
+
|Identifier
+
| <string>
+
| -
+
| Category id. Required Eclipse category property.
+
 
+
|- valign="top"
+
|Label
+
| <string>
+
| -
+
| Label displayed for the category when accessing the aggregated repository via the p2 update manager.
+
 
+
|}
+
 
+
===Validation Repository===
+
A Validation Repository defines a repository that may be required to satisfy dependencies for the aggregation but whose contents should not be included in the aggregated repository.
+
It supports the cases where the objective is to create a repository that is not self sufficient, but rather a complement to something else.
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Enabled
+
| '''true'''
+
'''false'''
+
| true
+
| Controls whether a Validation Repository is considered during the verification and aggregation process. Setting this property to <code>false</code> excludes the repository from the verification and aggregation process.
+
 
+
|- valign="top"
+
|Location
+
| <URL>
+
|
+
| Specifies the location of the repository.
+
 
+
|}
+
 
+
===Maven Mapping===
+
The Aggregator supports the creation of Maven-conformant repositories. Those require a structure and naming conventions that may have to be achieved by a transformation of the Bundle-SymbolicName (BSN) when working with Eclipse bundles found at contributed repositories. Custom transformations are supported by the definition of one or more Maven Mappings which can be defined at the [[#Aggregator|Aggregator]] and the [[#Contribution|Contribution]] level.
+
 
+
This only applies when the ''Maven Result'' property of the [[#Aggregator|Aggregator]] model is set to true. In that case all defined Maven Mappings are applied in the order in which they appear in the model starting from the most specific to the most generic. That means for each artifact that a [[#Contribution|Contribution]] adds to the aggregated repository:
+
#first Maven Mappings defined as children of a [[#Contribution|Contribution]] are applied in the order in which they appear as children of the parent [[#Contribution|Contribution]] node
+
#second Maven Mappings defined as children of the [[#Aggregator|Aggregator]] model are applied in the order in which they appear as children of the parent [[#Aggregator|Aggregator]] node
+
#finally the default Maven Mapping is applied
+
 
+
The most generic mapping is a default pattern that is applied whenever a Maven result should be created. It does not need to be added explicitly to the model.
+
A mapping is specified by a regular expression (applied to each BSN) and two replacements (one for groupId, another one for artifactId) which refer to the resulting Maven repo structure. The default pattern is:
+
 
+
<pre>
+
^([^.]+(?:\.[^.]+(?:\.[^.]+)?)?)(?:\.[^.]+)*$
+
</pre>
+
 
+
The default maven mapping defines as replacements <code>'''$1'''</code> for groupId and <code>'''$0'''</code> for artifactId. Hence, when applying the mapping to a BSN up to 3 segments (with dots as segment delimiters) are considered as the group, and the whole BSN is considered as the artifact name. If this is a applied to something like <code>org.eclipse.buckminster.aggregator</code> the groupId would be <code>org.eclipse.buckminster</code> and the artifactId <code>org.eclipse.buckminster.aggregator</code>. The resulting Maven repo would have the folder structure:
+
 
+
<pre>
+
org
+
  |
+
  eclipse
+
      |
+
      buckminster
+
        |
+
        org.eclipse.buckminster.aggregator
+
            |
+
            <folder name after version>
+
              |
+
              org.eclipse.buckminster.aggregator-<version>.jar
+
              ...
+
</pre>
+
 
+
 
+
 
+
{| {{Greytable}}
+
|-
+
!Property
+
!Value(s)
+
!Default Value
+
!Comment
+
 
+
|- valign="top"
+
|Name Pattern
+
| regex
+
| -
+
| A regular expression which is applied to the Bundle-SymbolicName (BSN). Pattern groups may be referenced in the replacement properties.
+
 
+
|- valign="top"
+
|Group Id
+
| <string> (may contain pattern group references (i.e. $1, ...))
+
| -
+
| Group Id applied in a maven mapping structure (groupId/artifactId). The Group Id replacement may contain pattern group references (i.e. $1, ...).
+
 
+
|- valign="top"
+
|Artifact Id
+
| <string> (may contain pattern group references (i.e. $1, ...))
+
| -
+
| Artifact Id applied in a maven mapping structure (groupId/artifactId). The Artifact Id replacement may contain pattern group references (i.e. $1, ...).
+
 
+
|}
+
 
+
 
+
 
+
[[Category:Buckminster]]
+
[[Category:Buckminster Tutorials]]
+

Latest revision as of 02:50, 3 November 2011

The Buckmintster aggregator has move to b3. Please visit the B3 Aggregator Manual page instead.