< To: Buckminster Project
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 later below.
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.
Make sure you are using Eclipse 3.3 or later
At the time of writing you will have to make sure you have Eclipse 3.3 or later with PDE bundles installed.
- If you are starting from scratch it is it is recommended that you choose either the '"Eclipse Classic" or the '"Eclipse for RCP/Plug-in Developers" package. They both contain the PDE bundles required by Buckminster, otherwise those will have to be obtained separately.
- Download either of the suggested packages from http://www.eclipse.org/downloads/.
- Or if Eclipse is installed make sure it is the correct version:
- Select Help > About Eclipse SDK and check the Version number.
- Currently, the Buckminster plugins do not check for a minimum Eclipse version. If you install the plugins on an earlier Eclipse version, the installation may succeed, but you will probably however encounter many errors as you start using Buckminster.
Make sure you are using Java 5.0 or later
You can do that in Eclipse by:
- 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)
- 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.
Download Buckminster with the Eclipse Update Manager
(and the subclipse) plugin:
- 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.
- Select Help > Software Updates > Find and Install in the Java SDK.
- Select Search for new features to install and then the Next button.
- 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.
- 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.
- 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.
- 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.
- 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.
- Eclipse will then display the Install window, for the Buckminster feature. If you are happy with the default folder location, select Finish.
- The Update Manager, with a progress bar, will display again.
- 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.
- The Update Manager will then briefly re-display, followed by invitation to restart Eclipse to complete the installation of the plugin. Select Yes.
- 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
We suggest the next places you might want to take a look at are:
- The Why Buckminster ? document gives a high level overview of the motivation for, and concepts in, Buckminster, without getting into details of any (XML) code fragments.
- The Hello XML World Example (Buckminster) which illustrates in detail how a materialization can be done, and uses different types of components - Eclipse plugins and stand alone files.
- The Introduction to Buckminster which gives some common usage scenarios, explaining how to materialize and consume software components; how to publish components to your colleagues and the wider community; and how to prepare virtual distributions ("distros") using Buckminster.
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.