Buckminster/UserSeries/Getting Started

Getting Started

Welcome to Buckminster. So you've heard a little about it and would like to investigate further. This is the page to start. Here we'll talk about the what exactly Buckminster does, what the basic concepts are and why you might like to use it.

Introduction to Buckminster

Buckminster is an interesting concept to explain, but if you have ever found yourself building software and spending forever trawling for dependencies to get it to compile, then read on. If you are in an organisation with a complicated set of dependencies and build orders then this is also for you. Buckminster wont solve all your problems, but with the help of this series of wiki pages you should be very clear what it can do for you and where you'll need to invest extra effort.

Buckminster at a glance

It's a Java based tool that can resolve dependencies. So if you have a project you want to build, as a build engineer setting up Buckminster you'll need to spend some time configuring it so it can resolve those dependencies correctly. You will do that by defining a cquery and an rmap file which we will cover later. Then you run a Buckminster application that points at your cquery then materializes all those dependencies into an eclipse workspace. What will happen is your cquery specifies what exactly it is you need to build or materialise. The rmap file tells Buckminster where it can find this stuff and how it's accessible. Buckminster can read source repositories (svn, cvs), library repositories (such as maven and update sites) and even basic URL based sites natively.

It's embedded very tightly into eclipse and works really well if you are building simple OSGi based stuff. You can use it headless, that is from a command line for automated builds, or you can invoke it directly from within the eclipse IDE. Either way you end up with an eclipse workspace populated with the results of the materialisation. This your source code with all its dependants ready for compilation.

It can build stuff for you using eclipse's PDE. But it can also invoke ant and maven scripts as well using actors. We'll focus more on using the eclipse PDE but later on we will turn our attention to why you might need to call out to ant or other build system.

Once you have it this far, you can configure Buckminster to create and publish update sites if that is a requirement for your project. We will also be covering this in a later stage in the tutorial series.

Rationale for using it

Buckminster gives you a means of creating extensible and scalable build systems that wont require you to have to spend lots of ongoing time maintaining it. When you use Buckminster to do the materialisation and build of your code you will get:

• Consistency between how developers materialise the code and your automated build systems
• Reduced Maintenance going forward since you're delegating to Buckmsinter instead of rolling your own build scripts
• If you have a good rmap, new components in the project may not require the build system to be updated at all
• Tight integration with the eclipse development environment
• Great support from an active community within eclipse.

Let's address some of these points:

Consistency between developers and your build process

This is important if you have complex dependencies and branch structures. In the past, I've often experienced problems where developers were different versions of plugins or jars in the their development environment, and the automated build system was using different flavours. Trying to diagnose these problems can be very time consuming, not to mention stressful if you're near a release. When you use Buckminster, you're saying to the development team, for release X.X, use the following cquery file to materialise your workspace. When they do that, you are taking away any chance for them to have the wrong version of the source or dependants. And since your build system will be based on the exact same cquery, you can have confidence that what you are building for production will be identical to what the developers were using.

Reduced Maintenance Going Forward

Implemented correctly, Buckminster will save you a lot of effort in build system maintenance. You can pretty much eliminate a huge amount of DIY scripts that were kicking off other builds, bringing in jars from external repositories etc. This is particularly useful if you have eclipse plugins that use maven libraries. Buckminster will manage bringing in the correct version of the dependency, but also the more mundane side of things ensuring the library name matches what your plugin manifest and build.properties file expect.

And we also mentioned that if defined correctly, new components may not require any update to the build system at all. This is true if the rmap will be able to work out where the component is available from and the location of its dependants. So when you're creating your rmap, don't be afraid of using some regular expressions in there to make sure you wont have to be re-visiting the file on a frequent basis.

Basic Terminology and Concepts

Rather than re-inventing the wheel, there is already some good coverage here: Key Concepts

First steps to using Buckminster

So you're interested in taking Buckminster for a test drive? OK, let's look at what you need to install then.

If you are using eclipse 3.4, pop into the Software Updates dialogue. Make sure you have the Buckminster update site installed, if not just add the following URL: http://download.eclipse.org/tools/buckminster/updates and install the latest version of Buckminster.

Now you should see two new menu items in your File menu, "Open a Component Query" and "View a Selected Cspec". The first one will be what you will be what we'll use to materialise an already created Buckminster project. For now though, we're going to be creating a new Cquery File.

So, let's create a simple project and show you how to get Buckminster up and running with it.