Creating an Eclipse RCP target platform

September 1st, 2009  |  Published in Rich Client Platform, Tips, eclipse  |  14 Comments

The PDE team has given RCP developers some great new features in Eclipse 3.5. It’s now much easier to create and manage target platforms for Eclipse RCP applications. In this post, I’ll outline one simple workflow that should work in most cases.

But first, if you’re interested in what a target platform is or why you might want to create one, check out these previous posts.

So now that you understand why we should create a target platform, what’s the best way to do it?

Create a target definition file

Eclipse target platforms can be created and selected directly in the Target Platform preferences page, but a better approach is to define your target platform using a target definition file. A target definition file outlines what should be included in your target platform and where the features and bundles can be located. More importantly, target definition files can be checked in to your version control repository and shared among the members of your team.

So how do we create one? You see here a sample RCP application that was generated with the Hello World template. Let’s add a target definition to this project.
sample-project

Right-click on the project name and select New > Other. Then choose Plug-in Development > Target Definition in the wizard selection dialog.
new-target-definition
The wizard page prompts you to select a file name, and I’m going to choose samplercp.target to match my project name. Remember, it’s a good idea to have a separate target platform for each project you work on.

Define your target platform

Now that we have a target definition file in our project, we can select what to include in our target platform. We do that by identifying one or more locations that may contain features or bundles. Eclipse 3.5 supports four types of locations (directories, installations, features, and software sites).

In this workflow, I’ll be using a software site which means that the features and bundles will be downloaded from a repository and stored locally under my workspace .metadata folder.

For an RCP application, we typically want to set our target platform to the Eclipse RCP SDK which is made up of two features:

  • org.eclipse.rcp
  • org.eclipse.rcp.source

Let’s add these features to our target platform. Start by clicking Add in the Target Definition Editor (this editor should have opened automatically after you created the target definition file). Then select Software Site on the Add Content dialog and click Next.
target-platform-add-content
The next page of the wizard is where the real work is done. We’re going to specify a repository location where the Eclipse RCP SDK can be retrieved.

  • First, select the Galileo repository from the Work with drop-down.
  • Next, deselect the Group by Category checkbox. For some reason, the Eclipse RCP SDK does not appear anywhere in the category listing. You would think it would be included under the EclipseRT Target Platform Components category, but no such luck.
  • Finally, place a check next to the Eclipse RCP SDK entry in the list and click Finish

target-platform-add-content2
As soon as you click finish, Eclipse PDE will start the process of downloading the RCP SDK to your machine. Your target definition file should look like this:
target-defintion-complete

Activate your new target platform

The final step is to activate your target platform by clicking the Set as Target Platform link in the upper-right corner of the Target Definition Editor. Then you’re all set! And make sure to check in your target definition so everyone on your team can share the fruits of your hard work ;-)

Responses

Feed Trackback Address
  1. Kai says:

    September 2nd, 2009 at 2:22 am (#)

    Hi Patrick,

    These target platforms are a very useful feature indeed. Thanks for the hint to the target file, now I also know how this setup can be easily shared among the team members :-)

    There is just one thing I ask myself: What is the best way to keep this target platform definition and my RCP product definition in sync? In the .product file you also list all features/plugins that make up your application (e.g. org.eclipse.rcp) and thus this information is very close to the content of the target file.

    What is your suggestion to deal with this?

    Cheers,
    Kai

  2. Patrick says:

    September 2nd, 2009 at 10:03 am (#)

    Hi Kai,

    I agree that it would be nice to specify dependency information in one place and reuse it for development and builds. Maybe some day we’ll get to a Maven-like dependency approach. Also, it should be noted that currently a product definition is a concatenation of target platform and workspace resources, so it’s not a one-to-one mapping.

    Currently, there’s no way that I’m aware of to avoid duplicating the information. I highly suggest basing product definitions on features instead of bundles, which makes a definition simpler and easier to maintain.

    Regards,

    — Patrick

  3. Martin Dilger says:

    September 2nd, 2009 at 2:57 pm (#)

    Hi Patrick,

    thanks for this useful hint!

    Martin

  4. Kai says:

    September 3rd, 2009 at 2:25 am (#)

    Hi Patrick,

    Thanks for your answer – at least I now know that I didn’t miss anything important ;-)
    I very much agree that products should be specified using features; the only drawback which I see with this is that your RCP app becomes more bloated than it is necessary (as many features also contain plugins that you normally would not want to add). Still, trying to maintain the complete list of plugins is a real nightmare, so I opted for the features :-)

    Kai

  5. Alexander Malic says:

    September 3rd, 2009 at 3:30 pm (#)

    hi patrick,

    Is there a guarantee that the Target Platform will be hosted by Eclipse.

    e.g.: i develop a rcp-application
    in 5 years i have to implement some new features. will i be able to build my application against the target definition pointing to the eclipse galileo update site?

    if not, what would you suggest instead?

    at our company we are allready using a target platform. we just used all the plugins from the ganymede release for 3.4 target platform. but it’s huge and there are lots of unneeded plugins in it. i’ve tried to minimize it, but from a certain point i was able to build our applications, but unable to launch them. and the error message didn’t tell me what.

    alex

  6. Patrick says:

    September 3rd, 2009 at 4:05 pm (#)

    Hi Alex,

    That would be a good question to ask the Eclipse Foundation, but I doubt if they would provide a guarantee. I was talking to Jeff McAffer at EclipseCon about this issue and he suggested Yoxos as a solution. This is really the same problem as depending on a Maven repository for builds, but they have a longer track record of supporting this type of thing.

    In my work, I do not yet use update sites for build targets, only for development. I usually construct build targets locally and then archive them along with my source code.

    — Patrick

  7. Paul says:

    September 18th, 2009 at 12:16 am (#)

    Hi Patrick,

    one little remark I have realized when playing around with target platform …
    As long as I only have my RCP application in my Eclipse workspace everything is OK. But as soon as I want to add some junit test to my code the target platform in not sufficient any more. If I want to run pure java unit test as well as plugin junit tests I need to expand the target platform further. I ended up using the at least the EclipseSDK package as target platform, in order to work as usual!
    Nevertheless, I still think that the concept of target platform is very valuable.

    What are your experience in this area? Any possibilities I have missed?

    Regards
    Paul

  8. Patrick says:

    September 18th, 2009 at 11:47 am (#)

    Hi Paul,

    Yes, you will almost always need to add other bundles to your target platform. JUnit is a common one, third party libraries will need to be added as well.

    You can structure these additions in various ways. For some, you may want to create a directory and place the bundles there. For others (JUnit for example), you may want to point at an installation and select the bundles you need.

    One thing to be careful of is to add only the bundles you really need. Adding the EclipseSDK to your target platform is usually unnecessary. Remember that you don’t have to limit a target platform to features, it can contain individual bundles as well. You’ll want to create your own features to contain those bundles. For example, you may want to create a com.mycompany.myproduct.test feature to reference your JUnit bundle.

    Regards,

    — Patrick

  9. Martin Roberts says:

    December 9th, 2009 at 10:43 am (#)

    Hi,
    how do I get the target platform and a product definition linked together?

    Martin

  10. Patrick says:

    December 9th, 2009 at 4:42 pm (#)

    HI Martin,

    There’s no way I know of to link target platforms and product definitions. The target platform specifies all of the bundles which *may* become part of your product. The product definition specifies the bundles that *are* part of your product.

    I agree that there is some redundancy here and it would be nice if you could simply specify things once.

    — Patrick

  11. Ryan says:

    April 13th, 2010 at 8:29 am (#)

    Hi Patrick,
    I’ve been trying to get my project switched over to a target file and have a several questions.
    First, why do you pick the RCP SDK instead of just the RCP package? It seems like for a target, you’d only need the runtime, not the source.
    Second, is there a way to just download the RCP and use the add directory option, and not use the update site? This site http://download.eclipse.org/eclipse/downloads/drops/R-3.5.2-201002111343/index.php lists the RCP, but it seems to be platform dependent; I thought that it would be platform independent with the delta pack holding all the platform dependent bits. This goes for all the other packages listed by the Galileo update site; where do I download them so I don’t depend on the update site for my target file.
    And finally, I’ve deselected all plug-ins in my run configuration and clicked “Add Required”. How do I go from the package/plug-ins listed in my run configuration to the eclipse project I need to add to my target file?

    Thanks,
    Ryan

  12. Patrick says:

    April 14th, 2010 at 9:46 am (#)

    Hi Ryan,

    Here are my thoughts on your questions:

    1. The RCP SDK contains source bundles. When you’re creating a target platform for development use, you want source bundles so you can browse and debug into it. The source bundles also provide the extension point definitions and it’s difficult to developer RCP apps without them. For a build machine, I would generally use the regular RCP Runtime + Delta Pack.

    2. It’s no problem to just download the RCP SDK, extract it, and then add that file to your target platform definition. It’s true that the RCP SDK (and Runtime) are platform independent and that does seem strange. I suppose it makes it possible to export your app from the IDE, though PDE Build will still fail. Anyway, you only need the RCP SDK for development, RCP Runtime + Delta Pack for a build machine.

    3. The link in your post is the correct place to download any of the RCP-related zip files.

    4. Generally it’s easier to manage your target platform at the feature level. This means that even if certain bundles are not required by the run configuration, they are still part of your target platform. It’s possible that you could weed out the bundles that are not required, but in my opinion it’s better to think of features as the real building blocks for RCP apps and to leave them intact in the target platform.

    I hope this helps,

    — Patrick

  13. Ryan says:

    April 14th, 2010 at 10:59 am (#)

    Hi Patrick,
    I setup a test project with only the runtime bundles and quickly realized why you want the SDKs.

    I agree that managing the target is easier with features, but what I was trying to figure out was the mapping between a required plug-in in my run configuration and what feature it was in (so I could add that feature to my target). I’ve been developing against my (bloated?) eclipse install for quite some time, so I had some plug-ins I wasn’t sure what feature they were in. Eg. org.hamcrest.core… turns out that plug-in is in the eclipse platform. It’s how to determine what feature that plug-in is included in that I wasn’t sure about. In that case, I was just looking through the eclipse platform, rcp, pde, etc. zip packages from that site and saw it in there.

    Ryan

  14. Patrick says:

    April 14th, 2010 at 12:48 pm (#)

    Hi Ryan,

    Ah, I understand what you mean. Occasionally it makes sense to add bundles to your own features, especially if you only need a few from a particular eclipse feature. Bringing in org.eclipse.platform is usually overkill for most RCP apps.

    I often create a “support” feature for the third party (including Eclipse) bundles I need for a given feature. For example:

    com.modumind.myapp.feature
    com.modumind.myapp.support.feature

    I usually create a separate folder to hold the support bundles for each feature, and these can be versioned if you like. These folders can then be added to your target platform in the normal way.

    — Patrick

Leave a Response