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 [[#Installing the Headless Buckminster| later below]].

+

=Installation for Buckminster users=

+

Buckminster is available as a plugin to the Eclipse IDE. There is also a stand alone “headless” version for command line usage, which is described in [[Installing Headless Buckminster]].

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

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

==Make sure you are using Eclipse 3.3 or later==

==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 when Buckminster is working with features and plug-ins, otherwise those will have to be obtained separately.

−

+

−

*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/ http://www.eclipse.org/downloads/].

*#Download either of the suggested packages from [http://www.eclipse.org/downloads/ http://www.eclipse.org/downloads/].

*'''Or''' if Eclipse is installed make sure it is the correct version:

*'''Or''' if Eclipse is installed make sure it is the correct version:

*#Select <tt>Help > About Eclipse SDK</tt> and check the Version number.

*#Select <tt>Help > About Eclipse SDK</tt> 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==

==Make sure you are using Java 5.0 or later==

You can do that in Eclipse by:

You can do that in Eclipse by:

−

#Select <tt>Help > About Eclipse SDK > Configuration Details</tt>. Scroll down to the parameter <tt>java.runtime.version</tt> - it should start with 1.5 or later (as an example the line may look like this <tt>java.runtime.version=1.6.0_01-b016</tt>)

+

#Select <tt>Help > About Eclipse SDK > Configuration Details</tt>. Scroll down to the parameter <tt>java.runtime.version</tt> - it should start with 1.5 or later (as an example the line may look like this <tt>java.runtime.version=1.6.0_03-b03</tt>)

#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 [http://www.java.com/en/download/manual.jsp here].

#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 [http://www.java.com/en/download/manual.jsp here].

Buckminster comes with a number of optional features. In order to obtain SVN support and allow Buckminster to communicate with SVN providers you have a choice to either use the Buckminster '''''Subclipse''''' OR '''''Subversive''''' integration. '''NOTE''' that those to features are '''mutually exclusive'''.

+

Buckminster comes with a number of optional features. In order to obtain SVN support and allow Buckminster to communicate with SVN providers you have a choice to either use the Buckminster '''''Subversive''''' OR '''''Subclipse''''' integration. '''NOTE''' that those to features are '''mutually exclusive'''.

The sections below describe the complete update steps for both choices.

The sections below describe the complete update steps for both choices.

#Select '''''Search for new features to install''''' and then the '''''Next''''' button.

+

#Provide the update manager with the required information for the Buckminster and Subversive/Subclipse update sites:

−

#Provide the update manager with the required information for the Buckminster and Subclipse update sites:

+

#*Click on the tab labeled '''''Available Software'''''

#*The easiest way to get the information for the required update sites is to use the bookmark file we prepared:

#*The easiest way to get the information for the required update sites is to use the bookmark file we prepared:

−

#*# Download this [[Buckminster and Subclipse Update Manager Bookmarks]] XML file, and store it somewhere convenient(e.g. in a file called ''bookmarks.xml''). This file tells the Eclipse Update Manager about both Buckminster and the Subclipse plugins required by Buckminster.

+

#*# Download this [[Buckminster and Subversive Update Manager Bookmarks]] XML file, and store it somewhere convenient(e.g. in a file called ''bookmarks.xml''). This file tells the Eclipse Update Manager about both Buckminster and the Subversive and SVN plugins required by Buckminster.

−

#*# Select '''''Import Sites...''''' and browse the bookmarks file. The update sites for Buckminster and Subclipse will then be added to the list of available sites.

+

#*# Select '''''Manage Sites...'''''

−

#*Alternatively, you can enter the update sites individually by choosing '''''New Remote Site ...''''' and then add:

+

#*# Select '''''Import...''''' and browse the bookmarks file. The update sites for Buckminster and Subversive/Subclipse will then be added to the list of available sites.

#Eclipse may throw up a window entitled '''''Update Site Mirrors'''''. Pick the most appropriate. For '''''Buckminster Update Site''''' we advise that you pick the main Buckminster Update Site as occasionally a mirror site is not always in synchronization with the master site and Buckminster is frequently updated.

+

#*#Subversive integration requires two update sites:

−

#Eclipse will then display a window entitled '''''Search Results''''' which should include the specified Buckminster and Subclipse upate sites.

#*#Select the Subclipse integration and typically all other optional features

+

#*#Select the optional features that you might need, but DO NOT SELECT THEM ALL. More information on the optional Buckminster features can be found [[Buckminster Optional Features|here]].

−

#*#BUT DO NOT SELECT the Subversive integration feature.

+

#*#In particular, DO NOT SELECT both the Subversive and the Subclipse integration feature.

−

#*For Subclipse:

+

#*For Subversive:

−

#*#Select the core Subclipse features.

+

#*#Select the core Subversive Team provider features.

−

#*#Select the Subclipse Buckminster integration feature.

+

#*#There may be other optional features for Subversive (i.e. Mylyn integration). Consult the Subversive site for information on those. They are not required for Buckminster.

−

#*#There may be other optional features for Subclipse (i.e. Mylyn integration). Consult the Subclipse site for information on those. They are not required for Buckminster.

+

#*#Select the SVNKit or JavaHL connector (or both in case you want to alter between them). Please note that JavaHL is not pure Java and might require other software installed on your computer.

−

# Proceed with '''''Finish'''''. Eclipse will then display a '''''Feature License''''' window, and if you are happy with the terms of the license as displayed, accept them, and then do '''''Next'''''.

+

# Proceed with '''''Install...'''''. Eclipse will then ask you to '''''Review Licenses''''', and if you are happy with the terms of the license as displayed, accept them, and then do '''''Finish'''''.

−

# Eclipse will then display the '''''Installation''''' window for the selected features. Accept the default folder locations and select '''''Finish'''''.

+

#The '''''Update Manager''''' will indicate the download progress and then recommend that you restart your IDE.

−

#The '''''Update Manager''''' will indicate the download progress and display a '''''Feature Verification''''' window upon completion. If you are happy to proceed, select the '''''Install''''' or simply '''''Install All'''''.

#Provide the update manager with the required information for the Buckminster and Subversive/Subclipse update sites:

−

#Select '''''Search for new features to install''''' and then the '''''Next''''' button.

+

#*Click on the tab labeled '''''Available Software'''''

−

#Provide the update manager with the required information for the Buckminster and Subversive/SVN update sites:

+

#*The easiest way to get the information for the required update sites is to use the bookmark file we prepared:

#*The easiest way to get the information for the required update sites is to use the bookmark file we prepared:

−

#*# Download this [[Buckminster and Subversive Update Manager Bookmarks]] XML file, and store it somewhere convenient(e.g. in a file called ''bookmarks.xml''). This file tells the Eclipse Update Manager about both Buckminster and the Subversive and SVN plugins required by Buckminster.

+

#*# Download this [[Buckminster and Subclipse Update Manager Bookmarks]] XML file, and store it somewhere convenient(e.g. in a file called ''bookmarks.xml''). This file tells the Eclipse Update Manager about both Buckminster and the Subclipse plugins required by Buckminster.

−

#*# Select '''''Import Sites...''''' and browse the bookmarks file. The update sites for Buckminster and Subversive will then be added to the list of available sites.

+

#*# Select '''''Import Sites...''''' and browse the bookmarks file. The update sites for Buckminster and Subclipse will then be added to the list of available sites.

−

#*Alternatively, you can enter the update sites individually by choosing '''''New Remote Site ...''''' and then add:

+

#*Alternatively, you can enter the update sites individually by choosing '''''Add Site ...''''' and then enter a URL. This step has to be repeated for each site that you wish to add.

#Eclipse may throw up a window entitled '''''Update Site Mirrors'''''. Pick the most appropriate. For '''''Buckminster Update Site''''' we advise that you pick the main Buckminster Update Site as occasionally a mirror site is not always in synchronization with the master site and Buckminster is frequently updated.

+

#Install the needed features:

−

#Eclipse will then display a window entitled '''''Search Results''''' which should include the specified Buckminster and Subclipse upate sites.

+

#*For Buckminster:

#*For Buckminster:

#*#Select all core Buckminster features.

#*#Select all core Buckminster features.

−

#*#Select the Subclipse integration and typically all other optional features

+

#*#Select the optional features that you might need, but DO NOT SELECT THEM ALL. More information on the optional Buckminster features can be found [[Buckminster Optional Features|here]].

−

#*#BUT DO NOT SELECT the Subversive integration feature.

+

#*#In particular, DO NOT SELECT both the Subversive and the Subclipse integration feature.

#*For Subclipse:

#*For Subclipse:

#*#Select the core Subclipse features.

#*#Select the core Subclipse features.

#*#Select the Subclipse Buckminster integration feature.

#*#Select the Subclipse Buckminster integration feature.

#*#There may be other optional features for Subclipse (i.e. Mylyn integration). Consult the Subclipse site for information on those. They are not required for Buckminster.

#*#There may be other optional features for Subclipse (i.e. Mylyn integration). Consult the Subclipse site for information on those. They are not required for Buckminster.

−

# Proceed with '''''Finish'''''. Eclipse will then display a '''''Feature License''''' window, and if you are happy with the terms of the license as displayed, accept them, and then do '''''Next'''''.

+

#*#Select the SVNKit or JavaHL connector (or both in case you want to alter between them). Please note that JavaHL is not pure Java and might require other software installed on your computer.

−

# Eclipse will then display the '''''Installation''''' window for the selected features. Accept the default folder locations and select '''''Finish'''''.

+

# Proceed with '''''Install...'''''. Eclipse will then ask you to '''''Review Licenses''''', and if you are happy with the terms of the license as displayed, accept them, and then do '''''Finish'''''.

−

#The '''''Update Manager''''' will indicate the download progress and display a '''''Feature Verification''''' window upon completion. If you are happy to proceed, select the '''''Install''''' or simply '''''Install All'''''.

+

#The '''''Update Manager''''' will indicate the download progress and then recommend that you restart your IDE.

−

#The installation should be finished with a restart of Eclipse.

+

−

+

==Wrapping up==

==Wrapping up==

Line 84:

Line 77:

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

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. (Note that this is required because the Eclipse Update Manager does not always do the right thing. This type of problem will go away with the newer Eclipse p2 based manager - and when using p2, it is a very bad idea to just delete things in the installation).

−

* 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 <tt>buckminster</tt> in its name below the two folders <tt>plugins</tt> and <tt>features</tt>. Then restart your Eclipse IDE again and proceed to re-install Buckminster.

+

* In update site selection step described 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).

−

* 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==

+

=Installation for Buckminster contributors=

−

We suggest the next places you might want to take a look at are:

+

As a contributor you will first have to follow the instructions in [[#Installation for Buckminster users|Installation for Buckminster users]]. If you intend to contribute to Buckminster, or plan to extend Buckminster you will want to get hold of the latest Buckminster source. Naturally, you will use Buckminster to get itself and use the following Buckminster CQUERY to obtain it:

−

* 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.

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.

#Navigate to the '''''RCP SDK''''' section where you will find a download link for the ''"RCP delta pack"'' zip.

+

#Download and unpack into your Eclipse installation directory.

+

#Restart Eclipse and execute the '''[http://www.eclipse.org/buckminster/samples/queries/buckminster-dev.cquery buckminster-dev.cquery]''' which should now happily resolve and materialize the latest Buckminster source into your workspace.

−

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?=

=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.

+

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/p2.

+

+

=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.

−

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.

Installation for Buckminster users

Buckminster is available as a plugin to the Eclipse IDE. There is also a stand alone “headless” version for command line usage, which is described in Installing Headless Buckminster.

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

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 when Buckminster is working with features and plug-ins, otherwise those will have to be obtained separately.

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_03-b03)

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.

Buckminster comes with a number of optional features. In order to obtain SVN support and allow Buckminster to communicate with SVN providers you have a choice to either use the Buckminster Subversive OR Subclipse integration. NOTE that those to features are mutually exclusive.

The sections below describe the complete update steps for both choices.

Option 1: Buckminster with Subversive integration

Select Help > Software Updates in the Eclipse IDE.

Provide the update manager with the required information for the Buckminster and Subversive/Subclipse update sites:

Click on the tab labeled Available Software

The easiest way to get the information for the required update sites is to use the bookmark file we prepared:

Download this Buckminster and Subversive Update Manager Bookmarks XML file, and store it somewhere convenient(e.g. in a file called bookmarks.xml). This file tells the Eclipse Update Manager about both Buckminster and the Subversive and SVN plugins required by Buckminster.

Select Manage Sites...

Select Import... and browse the bookmarks file. The update sites for Buckminster and Subversive/Subclipse will then be added to the list of available sites.

Alternatively, you can enter the update sites individually by choosing Add Site ... and then enter a URL. This step has to be repeated for each site that you wish to add.

Select the optional features that you might need, but DO NOT SELECT THEM ALL. More information on the optional Buckminster features can be found here.

In particular, DO NOT SELECT both the Subversive and the Subclipse integration feature.

For Subversive:

Select the core Subversive Team provider features.

There may be other optional features for Subversive (i.e. Mylyn integration). Consult the Subversive site for information on those. They are not required for Buckminster.

Select the SVNKit or JavaHL connector (or both in case you want to alter between them). Please note that JavaHL is not pure Java and might require other software installed on your computer.

Proceed with Install.... Eclipse will then ask you to Review Licenses, and if you are happy with the terms of the license as displayed, accept them, and then do Finish.

The Update Manager will indicate the download progress and then recommend that you restart your IDE.

Option 2: Buckminster with Subclipse integration

Select Help > Software Updates in the Eclipse IDE.

Provide the update manager with the required information for the Buckminster and Subversive/Subclipse update sites:

Click on the tab labeled Available Software

The easiest way to get the information for the required update sites is to use the bookmark file we prepared:

Download this Buckminster and Subclipse Update Manager Bookmarks XML file, and store it somewhere convenient(e.g. in a file called bookmarks.xml). This file tells the Eclipse Update Manager about both Buckminster and the Subclipse plugins required by Buckminster.

Select Import Sites... and browse the bookmarks file. The update sites for Buckminster and Subclipse will then be added to the list of available sites.

Alternatively, you can enter the update sites individually by choosing Add Site ... and then enter a URL. This step has to be repeated for each site that you wish to add.

Select the optional features that you might need, but DO NOT SELECT THEM ALL. More information on the optional Buckminster features can be found here.

In particular, DO NOT SELECT both the Subversive and the Subclipse integration feature.

For Subclipse:

Select the core Subclipse features.

Select the Subclipse Buckminster integration feature.

There may be other optional features for Subclipse (i.e. Mylyn integration). Consult the Subclipse site for information on those. They are not required for Buckminster.

Select the SVNKit or JavaHL connector (or both in case you want to alter between them). Please note that JavaHL is not pure Java and might require other software installed on your computer.

Proceed with Install.... Eclipse will then ask you to Review Licenses, and if you are happy with the terms of the license as displayed, accept them, and then do Finish.

The Update Manager will indicate the download progress and then recommend that you restart your IDE.

Wrapping up

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:

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. (Note that this is required because the Eclipse Update Manager does not always do the right thing. This type of problem will go away with the newer Eclipse p2 based manager - and when using p2, it is a very bad idea to just delete things in the installation).

In update site selection step described 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).

Installation for Buckminster contributors

As a contributor you will first have to follow the instructions in Installation for Buckminster users. If you intend to contribute to Buckminster, or plan to extend Buckminster you will want to get hold of the latest Buckminster source. Naturally, you will use Buckminster to get itself and use the following Buckminster CQUERY to obtain it:

Navigate to the RCP SDK section where you will find a download link for the "RCP delta pack" zip.

Download and unpack into your Eclipse installation directory.

Restart Eclipse and execute the buckminster-dev.cquery which should now happily resolve and materialize the latest Buckminster source into your workspace.

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/p2.

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 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.