Skip to main content
Jump to: navigation, search

Difference between revisions of "Buckminster Aggregator User Guide"

(Aggregator standalone)
Line 16: Line 16:
==Aggregator standalone==
==Aggregator standalone==
[[Image:Buckminster_Install_Aggregator.png|thumb|right|480x400px|'''''Buckminster Aggregator Editor''''' selection]]  
[[Image:Buckminster_Install_Aggregator.png|thumb|right|480x200px|'''''Buckminster Aggregator Editor''''' selection]]  
# Start your Eclipse installation and open the '''''Install New Software wizard'''''. You'll find in under the top menu ''Help''
# 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 in the ''Location'' field.
# Click the ''Add...'' button and enter the URL in the ''Location'' field.

Revision as of 06:03, 6 November 2009


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:

  1. 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.
  2. 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.
  3. 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


Start by installing a fresh Eclipse 3.5 SDK from (The latest version used at the time of writing was

Aggregator standalone

Buckminster Aggregator Editor selection
  1. Start your Eclipse installation and open the Install New Software wizard. You'll find in under the top menu Help
  2. Click the Add... button and enter the URL in the Location field.
  3. Select the Buckminster Aggregator Editor and click Next twice.
  4. Accept the Eclipse Public License and click Finish
  5. Restart the IDE once the installation is finished.

Aggregator with Buckminster

The Aggregator is not part of the official Galileo release. If you install the Aggregator from the repo mentioned above, into a workbench with Buckminster already installed, you may run into dependency conflicts. Instead update your Buckminster or install it from the following p2 repo:

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 and opened in an appropriately set up workbench:

Buckminster provides support for Subversive. Apart from the Subversive components at Eclipse (, a complete installation will also require Subversive SVN connectors provided by Polarion ( We want to create a repo that combines all these components and makes them accessible from one location and for several pre-defined configurations.

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:

  1. The top node Aggregator groups all model definitions regarding Configurations and Contributions. 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
  2. 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)
  3. 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
  4. 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 Rules 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
  5. 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
  6. 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.


Check the next section for a slightly different approach.

Providing a repo indirection

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 false in order to prevent copying all artifacts of the contributed repo to the aggregated repo.

The following is a variation of the first example with the Mirror Artifacts property set to false for all contributed repos. Running this aggregation will result in a composite repository that provides an indirection to the contributed repos.


Creating a Maven-conformant p2 repo

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 true. The aggregation deployed to the Build Root location will be a Maven repo.

The sample is a variation of the previous aggregations configured to produce a Maven repo.


Headless support

Running from the command line

Just type:
eclipse -nosplash -application org.eclipse.buckminster.aggregator <options>

For a detailed listing of the available options consult the next section.

Command line options

Option Value Default Description
-buildModel <path to build model> This value is required Appoints the aggregation definition that drives the execution
-action VERIFY




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
-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
-buildRoot <path to directory> buildRoot declared in the aggregation model Controls the output. Defaults to the build root defined in the aggregation definition.
-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.
-emailFrom <email> Address of build master Becomes the sender of the emails sent from the aggregator.
-mockEmailFrom <email>  ? Becomes the sender of the mock-emails sent from the aggregator.
-mockEmailTo <email>  ? Becomes the receiver of the mock-emails sent from the aggregator.
-mockEmailCC <email>  ? Becomes the CC receiver of the mock-emails sent from the aggregator.
-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.
-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>"
-smtpHost <host name> localhost The SMTP host to talk to when sending emails. Defaults to "localhost".
-smtpPort <port number> 25 The SMTP port number to use when talking to the SMTP host. Default is 25.

Hudson integration


Aggregator model - advanced features

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

Aggregator Model components and specific actions



Mapped Repository

Exclusion Rule
Validation Configuration Rule

Maven Mapping


Custom Category

Validation Repository

Maven Mapping

Back to the top