Build Scala projects with Eclipse Buckminster

In one of my pre­vi­ous posts I talked about how to build Scala pro­jects with PDE Build. However, PDE Build is rather old and has long been su­per­seded by Buck­min­ster. The great ad­vant­age of Buck­min­ster is that it is ac­tu­ally a light­weight Ec­lipse SDK with all that you need to build an RCP ap­plic­a­tion: a work­space of pro­jects, a tar­get plat­form, and so on. To build Scala pro­jects in Ec­lipse you will most likely in­stall the Scala IDE. Un­for­tu­nately, this plug-in can­not be in­stalled in Buck­min­ster right away. But there is a work­around…

Short dis­claimer: in this art­icle I’m not go­ing to de­scribe how to ac­tu­ally build pro­jects with Buck­min­ster. This art­icle is rather about how to in­stall Buck­min­ster, so it is able to handle Scala pro­jects like any other pro­ject. If you need a more gen­eral de­scrip­tion, please refer to the Buck­min­ster web­site.

Why Buckminster?

Let’s first talk about why I prefer Buck­min­ster over other solu­tions. Com­pared to other build tools, Buck­min­ster has one great ad­vant­age: it provides an en­vir­on­ment very sim­ilar to the one you’re de­vel­op­ing in—the Ec­lipse SDK. You can see Buck­min­ster as a light­weight Ec­lipse SDK without all this dis­tract­ing UI stuff, but with a com­mand line in­ter­face in­stead. However, Buck­min­ster still has a work­space where you can im­port your pro­jects into, and of course a tar­get plat­form which defines the en­vir­on­ment for your RCP ap­plic­a­tion. Run­ning a Buck­min­ster-driven build with con­tinu­ous in­teg­ra­tion sys­tems like Hud­son/Jen­kins is also very easy, since all you have to do is to cre­ate some con­fig­ur­a­tion files—a re­source map and a CQuery—and then run a simple com­mand on the shell like buckminster build. However, there there is also a plug-in avail­able for Hud­son/​Jen­kins, which auto­mat­ic­ally down­loads and in­stalls Buck­min­ster if ne­ces­sary. For more in­form­a­tion on the us­age please refer to the great book Buck­min­ster, The defin­it­ive guide by Hen­rik Lind­berg and Thomas Hallgren.

Buck­min­ster is also one of the few tools that are able to build a full-fea­tured Ec­lipse RCP ap­plic­a­tion. There are ex­ten­sions for other build tools like Ant or—since we’re talk­ing about build­ing Scala pro­jects here—sbt. For ex­ample, Bnd is one of them. It al­lows build­ing OSGi bundles without the need for cre­at­ing a MANIFEST.MF file manu­ally. Be­sides, you can al­ways pack­age your OSGi bundles your­self us­ing the jar tool, but that is really not enough for ser­i­ous RCP de­vel­op­ment.

If you want to build your RCP ap­plic­a­tion head­lessly, you have to use a tool that is really aware of what it is build­ing. It has to un­der­stand the com­plex de­pend­en­cies between your pro­jects and the OSGi bundles from the tar­get plat­form you use. Apart from that, it has to be able to parse files like MANIFEST.MF, build.properties, plugin.xml as well as con­fig­ur­a­tions stored in .product or feature.xml files.

As far as I know, there are only three products avail­able which sup­port all these fea­tures—or at least most of them: PDE Build, Maven Ty­cho and of course Buck­min­ster. I men­tion PDE Build here since it was formerly the re­com­men­ded way to build RCP ap­plic­a­tions, but has now been su­per­seded by Buck­min­ster. PDE Build is also only a set of Ant scripts and does not sup­port all of the afore­men­tioned fea­tures. Ty­cho, on the other hand, has re­cently be­come a ma­ture solu­tion. It in­teg­rates very tightly into the well-known Maven build tool. This makes it very easy for people who are us­ing Ty­cho for the first time, but already know Maven. Apart from that, Ty­cho con­tains some cool fea­tures like ar­che­types which auto­mat­ic­ally cre­ate pom.xml files for the bundles to build.

Nev­er­the­less, I found Ty­cho al­ways be­ing slower than Buck­min­ster—at least for very large pro­jects with a lot of bundles. I don’t know if this has something to do with the sup­port for in­cre­mental builds in multi-mod­ule pro­jects (Is this still a prob­lem with Maven 3 any­how?) or with the way Ty­cho is resolv­ing the tar­get plat­form and how it cal­cu­lates bundle de­pend­en­cies. Apart from that, Ty­cho builds pro­jects in a slightly dif­fer­ent en­vir­on­ment than they are de­veloped in. This elim­in­ates all of the afore­men­tioned ad­vant­ages of hav­ing a build en­vir­on­ment that is very sim­ilar to the Ec­lipse SDK—as I said, this is in fact what you have when you use Buck­min­ster. These dis­ad­vant­ages make it of course not im­possible to build RCP ap­plic­a­tions, but they are the reason why I would prefer Buck­min­ster over Ty­cho. Of course, this may change even­tu­ally, since Ty­cho is con­tinu­ously de­veloped.

How to install Buckminster and the Scala IDE normally

There is a Buck­min­ster plug-in for the Ec­lipse SDK which adds a con­text menu with build tasks to all work­space pro­jects. You simply in­stall it us­ing the p2 up­date man­ager. The cur­rent up­date site can be found at http://www.eclipse.org/buckminster/downloads.html.

In­stalling this plug-in and then in­stalling the Scala IDE is very easy and lets you build Scala-fea­tured OSGi bundles in a few minutes. Nev­er­the­less, set­ting up Buck­min­ster with the Scala IDE for head­less op­er­a­tion is a little bit harder. If you fol­low the doc­u­ment­a­tion very strictly, you will do the fol­low­ing things:

First you have to down­load the latest ver­sion of the p2 dir­ector ap­plic­a­tion: dir­ector_latest.zip. You can then in­stall the Buck­min­ster RCP ap­plic­a­tion with the fol­low­ing com­mand:

$ director -r <url to headless repo> -d <buckminster install folder>
      -p Buckminster -i org.eclipse.buckminster.cmdline.product

This will down­load Buck­min­ster from the sup­plied up­date site—which can be found on this site—and in­stall it into the given folder. After that you will most likely want to in­stall some ad­di­tional fea­tures in or­der to en­able head­less builds. Change into the dir­ect­ory where you in­stalled Buck­min­ster and run the fol­low­ing com­mands, for ex­ample:

$ buckminster install <headless repo> org.eclipse.buckminster.core.headless.feature
$ buckminster install <headless repo> org.eclipse.buckminster.emma.headless.feature
$ buckminster install <headless repo> org.eclipse.buckminster.git.headless.feature
$ buckminster install <headless repo> org.eclipse.buckminster.pde.headless.feature

Ad­di­tion­ally, you have to in­stall the Scala IDE into Buck­min­ster. Go to http://download.scala-ide.org and se­lect the up­date site that fits your needs. Then run the fol­low­ing com­mand:

$ buckminster install <scala ide repo> org.scala-ide.sdt.feature

Cannot complete the install because one or more required items could not be found.
[0]Software being installed: Scala IDE for Eclipse 2.0.0
     (org.scala-ide.sdt.feature.feature.group 2.0.0)
[0]Missing requirement: Scala IDE for Eclipse 2.0.0
     (org.scala-ide.sdt.feature.feature.group 2.0.0)
   requires 'org.eclipse.ui.navigator 0.0.0' but it could not be found

Oops! What happened? It seems like the Scala IDE re­quires user in­ter­face bundles, but my Buck­min­ster runs on the com­mand line!

Workaround

In or­der to work around this prob­lem, you have to in­stall Buck­min­ster a little bit dif­fer­ently. First, you need the p2 dir­ector ap­plic­a­tion again, but this time you will in­stall the Ec­lipse SDK:

$ director -r <eclipse sdk repo url> -d <eclipse install folder>
      -profileProperties org.eclipse.update.install.features=true
      -p SDKProfile -i org.eclipse.sdk.ide

After that, change into the dir­ect­ory where you just in­stalled Ec­lipse and run the fol­low­ing com­mands to in­stall Buck­min­ster:

$ eclipse -nosplash -application org.eclipse.equinox.p2.director
      -r <url to buckminster headless repo>
      -i org.eclipse.buckminster.core.headless.feature.feature.group
      -i org.eclipse.buckminster.emma.headless.feature.feature.group
      -i org.eclipse.buckminster.git.headless.feature.feature.group
      -i org.eclipse.buckminster.pde.headless.feature.feature.group

Please note the ad­di­tional .feature.group at the end of each fea­ture to in­stall.

Fi­nally, you can in­stall the Scala IDE:

$ eclipse -nosplash -application org.eclipse.equinox.p2.director
      -r <scala ide repo>
      -i org.scala-ide.sdt.feature.feature.group
      -i org.scala-ide.sdt.weaving.feature.feature.group

This should suc­ceed without er­rors.

From now on you can launch Buck­min­ster with the fol­low­ing com­mand:

$ eclipse -nosplash -application org.eclipse.buckminster.cmdline.headless

You may get the fol­low­ing ex­cep­tion when the Scala IDE bundles are star­ted:

java.lang.IllegalStateException: Workbench has not been created yet

This is due to the fact that you don’t have a UI and thus no work­bench. For­tu­nately, there’s an (un­doc­u­mented?) sys­tem prop­erty you can set to avoid this ex­cep­tion. Simply add the fol­low­ing line at the end of your eclipse.ini:

-Dsdtcore.headless

This tells the Scala IDE that you’re run­ning it in head­less mode and that it should avoid ac­cess­ing the work­bench.

Summary

In this art­icle I de­scribed how to head­lessly build Scala pro­jects with Buck­min­ster. I talked about why I prefer Buck­min­ster over other build tools and presen­ted a work­around for in­stalling Buck­min­ster and the Scala IDE with the com­mand line.

After in­stalling Buck­min­ster this way, you will have a full fledged tool to build Ec­lipse RCP ap­plic­a­tions in­clud­ing Scala plug-ins. However, in­stalling a com­plete SDK would not be ne­ces­sary if the Scala IDE bundles did not de­pend on Ec­lipse’s UI. It’s prob­ably pos­sible to cre­ate a fea­ture con­tain­ing only the core plu­gins like it has been done for the Groovy plug-in, but that’s something the Scala IDE team has to fig­ure out in the fu­ture.

Nev­er­the­less, a com­plete Ec­lipse SDK has also an ad­vant­age worth to men­tion: everything that works on your local ma­chine will also work on your head­less build server. Ac­tu­ally, you may even in­stall your local Ec­lipse the same way as de­scribed above. Then you can ab­so­lutely be sure that your ap­plic­a­tion is built in the same en­vir­on­ment as it is de­veloped in. This can make de­bug­ging a lot easier.