When you face the task of building a Server-Side Equinox or a RAP application (which is just a Server-Side Equinox application) you need to choose a build system from a fairly diverse palette. This choice is never easy because every build system has its pros and cons. In the end it comes down to which one you and others, love or hate.

To make this task a little easier we created a small github project called “RAP build examples”. It provides examples of how to build a RAP application with different build systems. Currently the following systems are covered:

PDE Build:

The goal of PDE Build is to facilitate the automation of plug-in build processes. Essentially, PDE Build produces Ant scripts based on development-time information provided by, for example, the plugin.xml and build.properties files. The generated Ant scripts, can fetch the relevant projects from a CVS repository, build jars, Javadoc, source zips, put everything together in a format ready to ship and send it out to a remote location (e.g., a local network or a downloads server). read more…

Tycho:

Tycho is focused on a Maven-centric, manifest-first approach to building Eclipse plug-ins, features, update sites, RCP applications and OSGi bundles. Tycho is a set of Maven plugins and extensions for building Eclipse plugins and OSGi bundles with Maven. Eclipse plugins and OSGi bundles have their own metadata for expressing dependencies, source folder locations, etc. that are normally found in a Maven POM. Tycho uses native metadata for Eclipse plugins and OSGi bundles and uses the POM to configure and drive the build. read more…

WAR Products Tooling:

The WAR Products are similar to Eclipse Products but much more lightweight. All you have to do to export a RAP application is to create a .warproduct based on a working launch configuration and press ‘export’. The exported .war file is ready to deploy. There is a function included that validates your .war file content before you’ve exported it. read more…

All the examples in the git repository follow the same pattern. They provide a simple RAP Application (the famous mail demo) and the files you need for the build. You can read the instructions on how to run each build in the README file which is provided for every example. For those of you who are not using git we’ve also created a zip file which contains the whole repository. You can download it here.

We plan to extend the examples in the future. A Buckminster example is on its way shortly. If you have experience with other systems please feel free to leave a comment and we can create an example together.

Tags: equinox, libra, pde build, rap, server, tycho, WAR Products

Recently I had the pleasure of updating the way Yoxos is built.  Like a lot of Eclipse based applications, the Yoxos build was feature based and we naturally use the normal headless PDE/Build scripts to do this.  To make things a little easier to extend, I decide to use the new product based builds (new is relative, as product builds have been around since about Eclipse 3.2).

There are a number of subtle points that I think are worth mentioning.

1. PDE/Build does not checkout the .product file

As you may know, when you specify a product build, you use the following build.property setting:

product=/some_bundle_or_featre/your.product

However, PDE/Build does not fetch that bundle or feature from your SCM system (See Bug: bug 159128)

To get around this problem, you can use a post setup custom target like this:

 <ant antfile="${genericTargets}" target="fetchElement">
    <property name="type" value="feature">
    <property name="id" value="org.feature.containing.product.file">
 </ant>

2. Platform specific products require platform filters

When I converted to product builds, I decided to build platform specific products (with platform launchers, etc…).  If any of your features contain platform specific fragments, make sure you set the conditions under which the fragment can be installed.

If you don’t set these, and the bundle or fragment has set platform filters, then at build time the fragment won’t be included, however, the feature will still require it.

3. Make sure your delta pack matches your platform

If you are building a product that targets a number of different architectures, then you are likely familiar with the delta pack.  It’s very important that you use the delta pack that matches your platform version (i.e. don’t use the Eclipse 3.5.1 delta pack with Eclipse 3.5.0). At build time, the executable features (found in the delta pack) has a requirement on the org.eclipse.equinox.launcher bundle.  This bundle comes with the platform and the versions must match.

4. Make sure all your bundles are contained in a feature

If your product is feature based, make sure all the bundles that constitute your product are listed in a feature.  This is one of those errors that manifest itself as it worked when I ran it from Eclipse, why doesn’t it work on the build machine. The reason for this is you likely had all your bundles in your workspace when you launched from Eclipse, so PDE was able to track down these dependencies for you.  When you build on the server, only things that are explicitly included are fetched for building.

5. Check your javacSource setting

If you are using newer java constructs like generics (again, new is relative as these constructs have been around for over 4 years), make sure your java settings reflect this. However, changing your compiler settings in your workbench will have little effect on a server 1/2 a world away.  To influence the compiler settings during build, you can set the following properties in your build.properties file:

# Default value for the version of the source code.
# This value is used when compiling plug-ins that do not set the
# Bundle-RequiredExecutionEnvironment or set javacSource in build.properties
javacSource=1.5

# Default value for the version of the byte code targeted.
# This value is used when compiling plug-ins that do not set the
# Bundle-RequiredExecutionEnvironment or set javacTarget in build.properties.
javacTarget=1.5

Happy building!

Tags: pde build

I wanted to share something I learned today about JUnit. Some of you may know this, but it was news to me.

My triggering problem was that I was writing some unit-tests which required OSGi to be started up. All my other tests were plain (i.e. non-OSGi) tests. Since I didn’t want to suffer from the startup delay every time I ran the unit tests, I thought about “ignoring” these OSGi dependent tests based on whether I was running plain tests or PDE tests. A bit of googling turned up an interesting feature of JUnit (since 4.4): Assumptions. Assumptions are defined in the Assume class and are basically the exact opposite of JUnit assertions: If an assumption fails, the test automatically passes. This keeps tests from failing when certain preconditions have not been met. Ideally these would be marked as “ignored” or “skipped” but still better than nothing (maybe someone with commit rights to the TestRunner could make this happen).

This neat feature allows us to do the following:

  @Before
  public void setUp() {
    Assume.assumeTrue( Activator.isOsgiRunning() );
  }

Now the tests will only be executed if they are running in an OSGi environment.

If you put this in an abstract base class that all PDE Tests inherit, these will be ignored when running in “plain” mode, for even quicker test runs. In that case be sure to name your @Before method in a unique way so it does not get overridden (and thus nullified) by subclasses.

These assumptions might also be useful for tests known to fail on particular platforms, JREs, runtime environments etc. Another neat addition to my toolbox. The bit of hair in this soup is that JUnit 4 support in Eclipse is a bit lacking, especially when it comes to the PDE build. Some of this is detailed in Bug #153429 which hopefully will be fixed in 3.6. (Hint: Vote!)

Tags: assume, assumptions, junit, pde build, pde test, preconditions, syndicate

Eclipse has earned a reputation of being one of the best IDEs in existence. While it has become a lot more than that in many ways, its roots and its focus have always been the user facing aspects. That is probably the reasons why certain other aspects like the PDE build have been a bit neglected for quite a while. Between the ugly map files, the dependence on a target platform and its disability to run JUnit 4 tests it feels like there is quite some room for improvement.
I appreciate all the effort that went into the current state of the PDE Build, and there is quite a lot that it offers: Checking of OSGI access rules, validation of extension and extensions points, multi-platform builds, generation of p2 metadata for update sites among other things. I want to take a look at some of the recent and ongoing developments that build upon that legacy.

b3

The b3 project is currently in incubation at eclipse.org. Its goal is basically to be to the PDE build what p2 was to the update manager: A revised, more powerful version of one of the main components of the Eclipse Platform. But while p2 was more or less a complete rewrite, the key with b3 idea is to build upon the exisiting technologies like the PDE build core, Buckminster, EMF and P2. Important key aspects are extensibility and customizability. as well as interoperability with other build tools such as ant and maven.

It is refreshing to see the build process getting more attention as of late, and that the Eclipse community itself is stepping up to the task of making sure that Eclipse based applications are built in a simple, repeatable and reproducible manner.

Tycho

While Eclipse is certainly one of the defacto industry standards, another one is maven. Just as Eclipse is more than an IDE, maven is more than a build tool. The Tycho project is the maven implementation for building Eclipse plugins. While there are currently maven plugins out there capable of building “plain” OSGi bundles, Eclipse plugins are quite a lot more involved. Since both the maven pom.xml and the OSGi manifest include dependency information, there is a bit of redundancy here. The idea is here to have one of these be the “master” version, and then synthesize the other one from that. This means that projects can either be “pom-first” or “manifest-first” depending on the sepcific requirements and project setup.

There a certainly some roadblocks in the way. For example, both OSGi and maven have a concept of versions that is important for resolving dependencies. And while their format is superficially the same, their notion of version ordering is subtly but definitely incompatible. This can lead to all kinds of havoc.

Hopefully issues like these will be resolved sooner rather than later. Eclipse is not an island. Many applications based on Eclipse RCP are actual rich clients, which means they are connected to a server. These server components are usually more traditional “read: non-OSGI” Java applications, and thus tend to be built by a maven setup. In cases like these it would be desirable to have client and server share the same build infrastructure. This would be a huge boon to many real-life projects out there.

Better builds

Both these projects show an encouraging amount of progress, and I am convinced that these efforts will go a long way in making the Eclipse and the Java Platform an even better combination. While I think friendly competition is a good thing, competitive cooperation can be even better. Maybe these two projects have slightly different goals and will fill slightly different niches in the future. But I believe there is a lot of common ground, and I hope there is some healthy cross-pollination between these two projects, if not more. Both teams have a quite a background in their respective areas, and thus could bring a lot to the table.

I for one am looking forward to see these two project bear fruit, making the Eclipse build process a lot less painful and a lot more powerful.

Tags: b3, build, maven, pde build, tycho

Yesterday I spent the day working on examples of how PDE Build can be used to build OSGi bundles.  I was setting up builders, copying files from my workspace to my builder, and running builds.   Early in the morning I was faced with the follow:

The method disposeImageButtonImages(ImageButton) from the type
ScaledWidgetFactory refers to the missing type ImageButton

Ok, a compile error, no big deal… the better part of a day later I finally had this solved.  Just so nobody ever has to deal with this particular error again, I thought I would post a small debugging tip you can use.  But first, some background on my day (after I saw the error):

1. Ensure export from the UI works… yes!
2. PDE/Build defines a variable called pluginPath that you can use to point at additional plugin locations.  Since the missing type  –ImageButton in my case — was in a pre-compiled bundle that exists in my target, I assumed this variable was set wrong.  I tried different separators, bundle ordering and directory locations (with and without spaces in the name). I even tried putting the bundle in my baseLocation.  No dice.
3. You can debug Ant scripts using PDE/Build.  There are a few things that you must setup first, but after I did this I was able to debug the script and ensure that the “so called ‘missing’” bundle was indeed in my classpath.
4. At this point something hit me — the compile errors is on the method call, not the import statement. That means that the compiler found the type on import, but not when the method was called…. strange!
5. In this particular example we are using Import-Package as opposed to Require-Bundle. Maybe I found a bug… I changed all the code to use Require-Bundle… No Dice.
6. Because build can be finicky, and and a typo can cause all sorts of problems, I started again… Same problem.
7. Read a story to my daughter. (Best part of the day, by far)
8. Back to work… This time, I started making small changes in different bundles, copying them over, and trying again… At one point, IT WORKED!
9. Revert the changes… IT WORKS! — Note: That’s not good
10. Start over, .. IT FAILS… make the same changes I did above.. IT FAILS!
11. Curse
12. Notice something.. when I copy the directories over, I am copying a bin/ directory that may (or may not) have fully built .class files.
13. Delete the bin/ directory .. IT WORKS!

In fact, the problem will happen very infrequently.  It only happened because I was copying bundles from my workspace (not fetching them from CVS), and in some cases, the bundles were not fully built.

So, the lesson: If you get strange compile errors using PDE Build, try deleting the bundles bin/ directory.

Thanks goes out to Andrew Niefer who once again came through with a much better way off structuring my build.

Tags: pde, pde build, tips