Skip to main content
Jump to: navigation, search

Difference between revisions of "Installing Buckminster"

(My First Materialization)
(Buckminster on Your Projects)
Line 110: Line 110:
''RMAP for Eclipse Monkey''
''RMAP for Eclipse Monkey''
[[Category:Buckminster Documentation]]
=Installing the Headless Buckminster=
=Installing the Headless Buckminster=

Revision as of 03:50, 21 May 2007

< To: Buckminster Project


Installing Buckminster in the Eclipse IDE

These steps describe a typical Buckminster installation for use in Eclipse IDE:

  1. Make sure you have Eclipse 3.2 or later installed:
    1. You can do that in Help > About Eclipse SDK
    2. Currently, the Buckminster plugins do not check for minimum Eclipse version. If you install the plugins on an earlier Eclipse version than 3.2, the installation may succeed, but you will seeing many errors as you start using Buckminster.
  2. Make sure you are using Java 5.0 or later. You can do that in Eclipse by:
    1. Select Help > About Eclipse SDK
    2. Select "Configuration Details", and scroll down to the parameter java.runtime.version - it should start with 1.5 (as an example the line may look like this "java.runtime.version=1.5.0_09-b01")
    3. If you are not on Java 5, you need to update your java environment first, but this is beyond the scope of this guide.
  3. In the two installation steps below you will be using the Eclipse Update Manager. To make these two steps easier, you can do the following:
    1. download this Buckminster Update Manager Bookmarks file and store in on your computer somewhere
    2. Select Help > Software Updates > Find and Install
    3. Select "Search for new features to install"
    4. Press "Import Sites..." and select the file you saved. The update sites for Buckminster and Subclipse will then be added to the list of available sites.
    5. Leave the "search for new features..." dialog open and continue on to the next step...
  4. If you want Buckminster to access Subversion repositories you must have the Subversion Subclipse plugin of version 1.0.1 or later. Follow the steps below or read more in the Subclipse installation guide. Subversion is optional, but unless you know that you are not going to be using source in a Subversion repository, we suggest that you also install Subclipse. (If you decide not to install Subclipse, you need to deselect the Subversion support when installing Buckminster, as per the instructions for 'Install Buckminster' below). So, to install Subclipse:
    1. If you closed the dialog, Select Help > Software Updates > Find and Install
      1. Select "Search for new features to install"
    2. If you did not use the bookmarks; In the "Update sites to visit" add the site for Subclipse with URL
    3. Make sure only the Subclipse update site is selected and press Finish.
    4. Select the subclipse feature, accept the license, and continue with the installation as directed by the wizard.
    5. You are asked if you want to restart, or apply changes. It is ok to select Apply Changes (at least for Subclipse 1.0.1).
  5. Install the Buckminster plugin
    1. If you closed the dialog, Select Help > Software Updates > Find and Install
      1. Select "Search for new features to install"
    2. If you did not use the bookmarks; In the "Update sites to visit", add the Buckminster update site with URL
    3. Make sure only the Buckminster update site is selected and press Finish.
    4. The Buckminster features are displayed. For a default installation select all - but see optional steps:
      1. You can omit the P4 features which are only needed if your organization is using Perforce P4. If you are unsure, it is OK to install the P4 support even if you do not have P4 installed. If you are using P4 you must have a P4 client with version 2004.2 or later installed.
      2. If you decided not to install Subclipse you must deselect the Subversion (SVN) features before proceeding.
    5. Accept license, continue with the installation as directed.
    6. You are prompted to restart Eclipse, Select restart to complete the installation.

After the Installation

Currently Buckminster has a very low visual profile, and you may wonder - well, where is it? How to I start using Buckminster? In a way it is like just having received a programmable industrial robot - how you use it depend on what it is you want to manufacture with the robot. Over time we want to add wizards that help you set up common and typical scenarios, but right now, you have to set these up manually.

To get started with Buckminster, here are some entry points:

  1. If you have not already, we suggest you read through Introduction to Buckminster - which explains the basic concepts.
  2. Buckminster Usage Scenarios where we will show how Buckminster is used in various situations. (Right now there is one demo available (Sharing a Project); how to efficiently share a project using Buckminster - but even if this is not what you want to do, this examples walks through most of the basic steps).
  3. Check out Buckminster Examples where we collect demos, code examples, longer answers to questions etc. Look in particular at the Hello XML World Example which details the Sharing a Project usage scenario.

Getting to Know the Concepts

A first step in starting to use Buckminster is to get to grips with Buckminster concepts and terminology. The Introduction to Buckminster is a good starting to point to get a basic understanding of Buckminster.

The next thing to get a better understanding of is the Resource Map as this gets you an understanding of from where and how Buckminster gets components. Then you need to look at Component Type since a component type is responsible for producing dependency information for a component, and this is done differently depending on the type of component.

Now you should understand how components can be made, depend on each other in different situations, and how Buckminster use this information to materialize the components into your workspace.

To make something happen, you need to understand the Component Query as that is the starting point of getting something resolved and materialized.

My First Materialization

You are probably anxious to try Buckminster in action, but on what? To help you out, there is a Sharing a Project demo with more detailed explanations in the Hello XML World Example. You can materialize this project, just like in the demo. There is also a Buckminster 'dog-fooding' example that the Buckminster team uses to develop Buckminster, so if your are interested, you can materialize the Buckminster project. You can also try to materialize the source of the Eclipse Monkey project as described on the Monkey Getting and Working with the Source Code page.

Buckminster on Your Projects

To run Buckminster on your own projects, there are a few things to think about. How are your components organized? Do you even have components? If everything is in one big project pile (a monolith) - how do you organize it into components?

Even if your own project is not broken up into individual components, you are perhaps including 3d party components, or indeed components from open source projects.

Basically these are the steps you need to take:

  1. Make sure that the components are available for download in the form your intended audience wants (source, binary, etc.), and being in a repository of a type supported by Buckminster (Eclipse update site, CVS, SVN, Maven, etc.).
    1. If your component does not contain dependency information, you also need to add a Component Specification describing the dependencies. This can be done by hand, or in Eclipse by 'adding the Buckminster nature' to the project and then editing the .cspec file.
    2. Note that if you do have components that already have dependency information (such as for Eclipse plug-ins, Buckminster uses this information directly, and instead of creating a full component specification, you can extend the specification created from the 'plug-in' (or whatever the source of dependency information was). See Component Specification Extension.
  2. Create a Resource Map that tells where to find your component(s) and all components they depend on. Make this resource map available to your audience via a URL (i.e. put in up on a website they can reach).
  3. Create a Component Query where you enter the URL to the resourcemap, and any other settings as apropriate for the query.
  4. Make the component query file (.cquery) available via a URL and hand this URL out to your audience.
    1. Give them instructions to use "File > Open" and to enter the .cquery URL, and to press "Resolve and Materialize" (here is an instruction example from the Eclipse-Monkey project).

As an example, this is the cquery file for the Eclipse Monkey.

<?xml version="1.0" encoding="UTF-8"?>
<cq:componentQuery xmlns:cq="" resourceMap="">
    <cq:rootRequest name="org.eclipse.eclipsemonkey-feature" versionType="OSGi"/>

CQuery for Eclipse Monkey

As you see, all it does is pointing at the RMAP URL, and stating that version strings are expressed in OSGi notation.

And here is the RMAP for the Eclipse Monkey.

<?xml version="1.0" encoding="UTF-8"?>

	<rm:site name="default">

	<rm:searchPath name="dash">
		<rm:provider readerType="cvs" componentType="eclipse-project" mutable="true" source="true">
			<rm:uri format=",org.eclipse.dash/{0}">
				<bc:property key="buckminster.component" />

	<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" />


RMAP for Eclipse Monkey

Installing the Headless Buckminster

Buckminster is also packaged in a so called 'Headless' command line oriented version suitable for running on remote servers, be invoked from scripts etc. The Headless version is based on Eclipse but only includes what is needed to run as a command line tool. The footprint of the headless version is thus much smaller than for the complete Eclipse IDE.

The Headless version as it is delivered today requires configuration before use. The downloadable version only contains the Buckminster core - i.e. it does not contain any of the optional plugins. They are easy to add, but it requires some work on your part.

You can read about the details and get step by step instruction on the Buckminster Packaging page.

How can I Stay Updated?

The IDE installation is updated via the Eclipse Update Manager. When installing Buckminster as described above, you have already added the required information to receive updates via the Eclipse Update Manager.

For the Headless version, you need to read more on the Buckminster Packaging (and subsequent) pages as there are different options how to do this.

Back to the top