Revision as of 11:57, 4 July 2007

< To: Buckminster Project

Installation

Installing Buckminster in the Eclipse IDE

Buckminster is available as a plugin to the Eclipse IDE. There is also a stand alone “headless” version for command line usage, which if you ever need it, is described here<URL to be given>.

These steps describe a typical Buckminster installation for use in Eclipse IDE. Note that the Subclipse plug-in is also typically used (see below): Subclipse is an Eclipse Team Provider plug-in which provides support for the Subversion version control system within the Eclipse IDE.

1. Make sure you have Eclipse 3.2 or later installed. Install it from here if you do not yet have it.
   1. Select Help > About Eclipse SDK and check the Version number.
   2. Currently, the Buckminster plugins do not check for a minimum Eclipse version. If you install the plugins on an earlier Eclipse version than 3.2, the installation may succeed, but you will probably however encounter 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 > Configuration Details. Scroll down to the parameter java.runtime.version - it should start with 1.5 or later (as an example the line may look like this java.runtime.version=1.6.0_01-b016)
   2. If it does not start with at least 1.5, you need to update your java environment first: you should find a version for your operating system here.
3. You will now use the Eclipse Update Manager to download Buckminster (and the subeclipse) plugin:
   1. Download this Buckminster Update Manager Bookmarks XML file, and store it somewhere convenient on your computer (e.g. in a file called Bookmark.xml). This file tells the Eclipse Update Manager about both Buckminster and the Subeclipse plugins.
   2. Select Help > Software Updates > Find and Install in the Java SDK.
   3. Select Search for new features to install and then the Next button.
   4. Select Import Sites... and browse your computer’s file system to select the Bookmarks file you saved at step 1. above. The update sites for Buckminster and Subclipse will then be added to the list of available sites.
   5. Select Finish. Eclipse will then display a window entitled Update Sites to Visit and will include the Buckminster Update Site, and the Subclipse upate for 1.0 amongst these: make sure that both are selected.
   6. Eclipse may throw up a window entitled Update Site Mirrors for the Buckminster Update Site. In this case, we advise that you scroll down the list of mirror sites and pick the last entry, ie Buckminster Update Site itself. This is because occasionally a mirror site is not always in synchronization with the master site.
   7. Eclipse will then briefly throw up a window entitled Update Manager, and when it has completed that step, will automatically throw up another window entitled Updates with Search Results. Select the Buckminster Update Site checkbox, and then the Next button.
   8. Eclipse will then display a Feature License window, and if you are happy with the terms of the license as displayed, select the I accept button, and then the Next button.
   9. Eclipse will then display the Install window, for the Buckminster feature. If you are happy with the default folder location, select Finish.
   10. The Update Manager, with a progress bar, will display again.
   11. A Verification window will then be displayed, indicating that the Buckminster feature is validly digitally signed. If you are happy to proceed, select the Install All button.
   12. The Update Manager will then briefly re-display, followed by invitation to restart Eclipse to complete the installation of the plugin. Select Yes.
4. Eclipse should close down, and automatically restart.

To confirm that Buckminster has now been installed, check that the File > New > Other > has an entry for the Buckminster wizards; expanding the Buckminster box should show a number of available Buckminster wizards.

Hopefully your installation has proceeded smoothly. However, here are some thoughts if things don't work out:

• At the time of writing, the Eclipse Update Manager (in general, not just for Buckminster) is IMHO far from perfect, and is currently being subject to revision. Hopefully before the end of 2007, there should be a better version.
• If you have previously installed Buckminster, you may need to un-install it before re-installing it as above - otherwise the re-install may fail. The safest way to do this is to find the Eclipse installation directory on your machine, and remove anything that has buckminster in its name below the two folders plugins and features. Then restart your Eclipse IDE again and proceed to re-install Buckminster.
• In step 3.5 above, it may be prudent of you to select all the sites which are displayed to you to include in your search: this will ensure that your version of the Eclipse IDE is completely up to date with all the functions and features of Eclipse which you are using (not just Buckminster alone).

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="http://www.eclipse.org/buckminster/CQuery-1.0" resourceMap="http://www.eclipse.org/dash/monkey/monkey.rmap">
    <cq:rootRequest name="org.eclipse.eclipsemonkey-feature" versionType="OSGi"/>
</cq:componentQuery>

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:rmap
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:rm="http://www.eclipse.org/buckminster/RMap-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">
			<rm:uri format=":pserver:anonymous@dev.eclipse.org:/cvsroot/technology,org.eclipse.dash/{0}">
				<bc:property key="buckminster.component" />
			</rm: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>

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.