A Maven Eclipse RCP Product build at last!

My sincere thanks to René Gröschke and Patrick Paulin for putting me on the right track. These notes were developed using Eclipse RCP Developer (version 3.3.1.1 "Europa").

Below, I have documented the required steps in some detail, based largely on René's tutorial. Some gotchas to watch out for include:

• Contrary to popular belief, it is not necessary to install the Maven 2 Integration feature in Eclipse - in fact we found it confusing and removed it again, preferring to invoke various Maven goals through External Tool configurations under the Run menu
• The build.properties file is very literal in its interpretation of properties you specify. In particular, when specifying a pathname, you must use forward slashes even under Windows, you must not have spaces in the pathname and you cannot enclose it in quotation marks. And most particularly, you cannot use symbolic references to any other property or environment variable (although the template supplied with the Eclipse PDE build plug-in misleads you here by suggesting that you can use ${user.home} as part of the buildDirectory property) - otherwise you will see the dreaded error message: Content Provider not set for Site: "{0}".
• You must specify a target platform in the base location that has had the Eclipse RCP Delta Pack installed, otherwise you may be able to build using PDE but you won't generate an executable.

It is recommended to download both the RCP Runtime for your expected target platform architecture(s) and the RCP Delta Pack. Install each target platform RCP runtime into its own location - e.g. if you have installed Eclipse in C:\tools\eclipse, I would suggest unzipping the RCP Runtime for 32-bit Windows on Intel x86 processors to C:\tools\eclipse\win32.win32.x86\eclipse. Unzip the delta pack into each of the targets. Let it overwrite all clashing filenames. Afterwards, if you are short of space, you can go through each Eclipse target platform and safely delete any plugins or features that don't correspond to the selected target architecture.

Having installed the target platform(s), it is probably a good idea to set the default Eclipse workspace target platform to the one for the type of workstation you are running on - e.g. if you're using a 32-bit Windows / Intel x86 computer, select Window -> Preferences -> Plugin Development -> Target Platform and browse to C:\tools\eclipse\win32.win32.x86\eclipse (vary this path depending on the location of your Eclipse target platform). This ensures that native Eclipse builds and product exports will correspond as closely as possible to those built by the PDE in "headless" mode.

Another thing you need to do is to doctor the POM of the pde-maven-plugin (snapshot) so that it doesn't depend on outdated versions of org.eclipse.pde.core and org.apache.maven.shared.maven-osgi. Here is one way to do it:

    <dependency>
      <groupId>org.eclipse.pde</groupId>
      <artifactId>core</artifactId>
      <version>[3.3.0,4.0.0)</version>
    </dependency>
    <dependency>
      <groupId>org.apache.maven.shared</groupId>
      <artifactId>maven-osgi</artifactId>
      <version>[0.1.9,)</version>
    </dependency>

Make sure you catch all copies of the POM. You can do this in your local Maven repository after a first attempt to build, or more permanently on your project repository. You can use the eclipse:to-maven goal to get Eclipse plugins from the target platform folder into your local and/or project repository.

Let's work through a complete though simple example of creating an Eclipse RCP application that can be built from the command line using Maven. Broadly, this has the following stages:

1. Create the RCP application
2. Create a product configuration file
3. Create a build.properties file
4. Make a Maven POM
5. Run it and test the result

Steps A-C are identical to what you would do if you wanted to create a project capable of supporting headless PDE builds. The only concessions to Maven are the layout of the source and output directories and the fact that we do not specify an eclipseLocation property in the build.properties file - this is instead configured in the Maven POM as the eclipseInstall parameter.

Now, are you sitting comfortably in front of your Eclipse IDE? Then follow the bouncing ball...

A. Create the RCP application

1. Start a new project: File -> New -> Project -> Plug-In Project
2. Set project name = "com.breskeby.tutorial.rcp.withMaven"
3. Uncheck "Default location"
4. Specify a location outside the Eclipse workspace, e.g. C:\data\eclipseProjects\plugins\com.breskeby. tutorial.rcp.withMaven
5. Set Source folder = src/main/java (following the Maven convention)
6. Set Output folder = target/classes
7. Next
8. Check "Generate an Activator" and "This plugin will contribute to the UI"
9. Check "Create an RCP Application"
10. Next
11. Select the template "Hello RCP"
12. Next
13. Change the application window title to "Hello RCP with Maven"
14. Finish
15. If asked, decide whether to open the Plugin Developer perspective (it probably is not worth it at this stage)
16. Test the new plugin by clicking "Launch an Eclipse Application"

B. Create a product configuration file

1. File -> New -> Other -> Product Configuration
2. Parent folder = com.breskeby.tutorial.rcp.withMaven
3. Filename = withmaven.product
4. Check "Create a configuration file"
5. Finish - the product overview is displayed
6. Set Product Name = "RCP with Maven Example"
7. Product ID: click New...
8. Accept default values except Product Application
9. Set Application = "com.breskeby.tutorial.rcp.withMaven"
10. Finish
11. Check "Product Configuration based on plug-ins"
12. Click on the Configuration tab and click "Add..."
13. Select com.breskeby.tutorial.rcp.withMaven and click OK
14. Click "Add required plug-ins"
15. Save the product configuration
16. Test by right-clicking on the withmaven.product file in the package explorer and selecting "run as..." -> "Eclipse Application"

C. Create a build-properties file

1. Right-click the project folder com.breskeby.tutorial.rcp.withMaven and select New -> Folder: name the folder "buildConfiguration"
2. In Windows Explorer or equivalent, find your Eclipse installation and navigate down to eclipse/plugins/org.eclipse.pde.build_*/template/headless-build. Copy build.properties from this file to the clipboard. Paste it into your new buildConfiguration folder in Eclipse. The asterisk in the above path stands for the version number of the Eclipse PDE builder. Make a note of it, as you'll need it in step D
3. Open the build.properties copy in an Eclipse text editor and click on the build.properties tab. Change the following properties:
   1. product=withmaven.product
   2. archivePrefix=withMaven
   3. configs=win32, win32, x86 or change depending on your desired target(s) - but René has noted that only one target architecture can be built at a time
   4. buildDirectory=[project directory]/target/eclipse.build (substitute the pathname of your project directory - see step A4 above - but use forward slashes)
   5. buildId=withMaven
   6. base=C:/tools/eclipse/win32.win32.x86 (depends on where you installed the target platform and which configuration you specified in configs - item c above). The base directory must contain a folder called "eclipse", which contains folders named "features" and "plugins"
   7. pluginPath=.
   The plugin path is the list of places to be searched for features and plugins needed during the build. In this case, the current working directory (i.e. the project directory) is fine, since the product build first creates the plugin in a plugins subdirectory.

D. Make a Maven Project Object Model (POM)

1. Right-click the project folder com.breskeby.tutorial.rcp.withMaven and select New -> File: name the file "pom.xml"
2. Into the new file, copy the template XML below

   <project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
     http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.breskeby.tutorials.rcp</groupId>
     <artifactId>withMaven</artifactId>
     <packaging>zip</packaging>
     <name>RCP With Maven Example</name>
     <version>1.0-SNAPSHOT</version>
     <description>A Simple Product PDE Example</description>
     <build>
       <plugins>
         <plugin>
           <groupId>org.codehaus.mojo</groupId>
           <artifactId>pde-maven-plugin</artifactId>
           <version>1.0-alpha-2-SNAPSHOT</version>
           <extensions>true</extensions>
           <configuration>
             <eclipseInstall>${env.M2_HOME}/../eclipse</eclipseInstall>
             <pdeProductFilename>withmaven.product</pdeProductFilename>
             <pdeBuildVersion>3.3.2.R331_v20071019</pdeBuildVersion>
           </configuration>
         </plugin>
       </plugins>
     </build>
   </project>

3. Modify the configuration section as follows:
   1. eclipseInstall - this is the path to your Eclipse RCP Developer installation (e.g. C:\tools\eclipse in the above example). Because my current project follows a convention about installing all tools in one place, I was able to use a property for this as shown above - your mileage may vary
   2. pdeBuildVersion - insert the version number copied from the pathname of the folder whose name begins "org.eclipse.pde.build_" (see step C2 above)

E. Run the build and test the result

1. Make sure all edited files have been saved
2. Ensure that your settings.xml is configured such that the required Maven snapshot repository is searched for plugins
3. Select the pom.xml file in the package explorer
4. Set up and use an external tool configuration to invoke Maven or run it from a command-line in the project directory: mvn clean install
The result turns up in [project directory]/../../I.withMaven/withMaven-[architecture].zip - unzip it, open the resulting folder and double-click the executable you have just built!

I hope that you have found this useful. If you run into snags, please check that you have followed all the above steps to the letter before contacting me (if you leave a comment on this blog I should be notified by e-mail).