Friday, September 9, 2011

Sharing Target Platforms and Launch Configurations in Version Control

Last week I had the pleasure to participate in the Masterclass on OSGi led by Neil Bartlett and Peter Kriens. The event was really fruitful and inspiring, and among other things I had to opportunity to work with Bndtools. For a long-year user of Eclipse PDE like me, it was quite interesting to look at the OSGi bundle development from such a different perspective.

One of the differentiators of Bndtools is that all resources of the OSGi development environment (like bundle repository, build and run configurations) are stored in projects in the Eclipse workspace and can be easily shared to a version control system using the Eclipse Team Provider. And indeed, this is a very useful feature - sharing such non-functional resources with your team members would enable them to quickly have the same working environment by just a quick checkout from the version control system.

But... Does Eclipse PDE really miss this same feature?

Not exactly! PDE has the "target platform" that is the equivalent of the bundle repository and the build-time configuration in Bndtools, and the "launch configuration" that is the equivalent for the run configuration in Bndtools. It's true that both target platforms and launch configurations are stored deep in the Eclipse workspace's metadata, which cannot be shared using the Eclipse Team Provider. But this is just the default behavior. Both artifacts can be exported to files in existing projects in the workspace so they can be shared.

Target Platforms

Let's first take a look at the target platforms. Users have two options: 1) create a new target platform from scratch as a file, or 2) export an existing target platform to a file.

New target platforms can be created using the New Target Definition wizard. It can be found by following New > Other... > Plug-in Development > Target Definition from the main menu. You need to choose "Nothing" for "Initialize the target definition with". The result is an "empty" .target file in an existing project in the workspace.

Exporting an existing target platform to a file can be done in a similar way. In the New Target Definition wizard choose the "Current Target" radio button instead of "Nothing". This way the wizard will export the active target platform. If you want to export a target platform that is not the active one at the moment, you need to first activate it (from Window > Preferences > Plug-in Development > Target Platform preference page).

Edit (Thank Curtis for this hint): Another (even easier) way to export an existing target platform is by going to the Target Platform preference page (Window > Preferences > Plug-in Development > Target Platform) and using the Share... button. This will launch a wizard that will export the selected target platform as a .target file in the specified project. The wizard itself will not share the target platform in a version control system, but after having it in the project you can use the Eclipse Team Provider for doing this.

The result .target file can be open and edited with the (default) Target Editor. It is important to mention that there may be many target definitions in the workspace, but only one can be activated as a target platform at the same time. This is a known issue (bug 159072) in PDE. It's not a problem for simple OSGi development scenarios, but could be really annoying for more complex ones. I have to admit that Bndtools has a better design here - every Bnd project can have its own target platform equivalent.

Launch Configurations

Here the only option is to export an existing launch configuration. This can be done by calling the File > Export... > Run/Debug > Launch Configurations wizard from the main menu. The selected launch configuration will be exported as a .launch file at the given location on the file system. You need to browse the location of the respective project in the workspace. Don't forget to Refresh the project to see the exported file.

The .launch files can be executed by using the Run As actions in the context menu. They can be edited by calling Run As > Run Configurations... action. Actually, every .launch file in the workspace is recognized as a launch configuration.

Like target platforms, you can have many launch configurations in the workspace. And, luckily, you can launch as many as you like at the same time. Launch configurations can be configured to launch only a subset of the target platform - the bundles that you really want to run, plus additional bundles from the workspace. So, it's worth having several launch configurations if complex projects must be run in different contexts.

Additional Hints

It's very important to remember that when sharing resources with a team provider you should avoid using absolute file paths. Otherwise, your team mates could see broken paths if they don't maintain the same directory structure like yours. Such file paths could be the working directory of a launch configuration or a directory of bundles included in a target platform.

The Eclipse Platform has an excellent solution called Path Variables. The one that I like the most is the ${workspace_loc} variable that always points to the root location of the current Eclipse workspace. I highly recommend using it when constructing file paths that will be shared with a team provider.

Many dialogs in Eclipse provide the special Workspace... button that makes construction of paths relative to the workspace root very easy.


We've seen that sharing project metadata like target platforms and launch configurations, although not so obvious at first sight, is easily possible in Eclipse PDE. Compared to Bndtools, PDE even provides some more flexibility, but at the same time has also some deficiencies.
Languagesen>bg GoogleCE