Eclipse Buckminster Component Assembly

Buckminster is a buildtool that is used by the iDempiere project to build its workspace and distribute files.

Buckminster is an Eclipse project. There is a Buckminster Project Homepage at the Eclipse website.

Buckminster is comparable a bit to Apache Ivy, a bit to Apache Ant and a bit to Maven. It can care about materialization (others call it "dependency solution"), build and - if you need - deployment of software projects. One of the specialties is that Buckminsters architecture allows for very different types of component and its connectors are written so they use the native information format of these components. That means if your component is an Eclipse project Buckminster uses the Eclipse Project information to get information about dependencies, build options, classpaths, etc.

Buckminster has been written with Eclipse in mind from the beginning on. Today it is an Eclipse hosted Project. You can expect it to work well together with your eclipse project setup.

This Page is written by Thomas Bayen after his insight that he did not know anything about the iDempiere build process and after some recherche to change this fact. (If you need deeper informations you better should ask someonew who knows. Haha!) The iDempiere build system using Buckminster was first created by Heng Sin Low. (If you feel you can rewrite this page for the better please do not begin a new page but feel free to change all this here!)

Documentation

Looking at the Buckminster Homepage you find a link "documentation" which is a download link of the so-called BuckyBook ("Eclipse Buckminster: The Definitive Guide"). This book holds 250 pages of documentation and is no easy introduction. There is also a Wiki. If you want an shorter overview you can read Introducing Buckminster or Introduction to Buckminster.

From the Buckminster Wiki: The key essential concepts used in Buckminster are:

A Component Query (CQUERY). A CQUERY is a (usually quite small) XML file which names some component that you want to download and materialise. Included within the CQUERY is a reference (usually a URL) to a resource map (RMAP).
A Resource Map (RMAP). An RMAP (again, an XML file) identifies possible locations - e.g. internet repositories - where a component - given in a CQUERY - can be found. The component in the CQUERY may depend on having further components (which in turn may need further ones, forming a transitive closure): the RMAP lists all the places where all of the components may be found.
A publisher of components normally provides his/her audience of consumers with a CQUERY and RMAP. Armed with these, consumers can give the CQUERY (which in turn points to the given RMAP) to the Buckminster plugin to the Eclipse IDE and the appropriate components will be materialised into Eclipse. Materialisation into non-Eclipse environments, including stand-alone on a local or remote machine, is also possible.
Bills of Materials (BOM). A BOM is (an XML file) generated automatically by Buckminster, given a CQUERY and accompanying RMAP: it gives a detailed list of all components, and their respective locations, in order to fulfill that particular CQUERY. A BOM file can also be published and used to materialise, in situations where the publisher wants to ensure that all of his/her audience of consumers get precisely the same set of specific component instances from the same set of repositories.
Component Specification (CSPEC). A CSPEC (is an XML file and) describes the metadata, including dependencies on other components, for a particular component. CSPECs are automatically generated by Buckminster for Eclipse plugins and features, and thus Eclipse-based publishers in most cases do not need to manually write CSPECs.
Component Specification Extension (CSPEX). A CSPEX (is an XML file and) is manually written to extend an automatically generated CSPEC in cases where Buckminster cannot find the entire metadata needed automatically.
Materialisation Specification (MSPEC). An MSPEC (is an XML file which) can be provided by a publisher to ensure that downloaded components materialise to particular folders/directories on target machines, and with appropriate replace/update/discard policies if some of the components are in fact already downloaded on a specific machine.

How can Buckminster be used

There are two possible user interfaces to Buckminster: At first you should install the Buckminster Eclipse Plugin via the Buckminster Update site. Then you can use Buckminster through the Context Menu in Eclipse's package view (Menu item "Buckminster"). As second you can use Buckminster on the shell ("headless" without the need for an Eclipse installation). This can e.g. be used to materialize, build or run applications on a foreign server.

How is Buckminster used in iDempiere

iDempiere is a bunch of plugins that grows all the time. After the conversion to OSGi architecture (from ADempiere to iDempiere) it was clear that there was a need for a build tool to create all this stuff in the right way. Because of the plugin-able nature of the project it was clear that we want to use OSGi plugins from outside the same way than we use iDempiere's own plugins. So we needed a way to resolve dependencies and download components. Because the whole project was created as Eclipse projects and all informations (like dependencies etc.) were there as Eclipse project files Buckminster was the best tool to do this job.

When you downloaded the source code of the project you have to materialize the project. That means that Buckminster will download all dependencies and prerequisities. Read Installation in Eclipse for more information.

You can use Buckminster for an headless build (without a running Eclipse instance) e.g. in a script or in a continous integration server like Jenkins. See Building iDempiere without Eclipse.

On the page Developing Plug-Ins - Continous Integration with Jenkins you see how a headless Buckminster can be used for continous integration in a Jenkins server.

If you want to integrate your own plugins into the Buckminster build you can read Developing Plug-Ins - Get your Plug-In running.