Building an RCP application from a product configuration file

[Pascal Rapicault <Pascal_Rapicault@xxxxxxxxxx>]

In 3.2, pde build introduced a completly
automated way to build products.
The attached document gives simple steps
on how to setup such a build.
Feedback is welcome in the bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=133280

PaScaL

Title: Building an RCP application from a product configuration file

Building an RCP application from a product configuration file

PDE Build comes with infrastructure to build a complete RCP application from a product configuration file. Most of the setup necessary for such a build can be done through a few modifications to the template build.properties provided in PDE build. The following section focuses on setting up a simple product build assuming that all plugins and features (to build and pre-built) referred to by the product file are already locally available on disk.

Basic setup

The first step in setting up a build is to create the directory in which the build will take place. This directory will be referred to as the build directory and will contain the plug-ins and features to build as well as all the generated artifacts. Next, copy your plug-ins and features respectively into "plugins" and "features" subdirectories. Your product configuration file is expected to be in one of these plugins/features.

The second step in setting up a build is to copy the template build.properties file from org.eclipse.pde.build/templates/headless-build to a new directory which will be the build configuration directory also referred to as the configuration directory). Edit the copied build.properties file and set the following properties:

• product: the location of your product configuration file in the form "/<plugin or feature id>/path/to/.product"
• baseLocation:  the location of an eclipse install containing all the pre-built features and plugins that your application is using and the RCP delta pack (it is available from the eclipse download page). Note that the delta pack is mandatory as it includes the org.eclipse.platform.launchers feature which contains the launchers and root files necessary for a product.
• buildDirectory:  the directory the build will take place in.  Set this to the full path of the build directory created previously.
• configs: list the configurations for which you want your product to be built. You can uncomment the configuration(s) provided (be careful to the line continuations).
• archivePrefix: the name of the directory of your product once installed on disk.

Recapitulation of the directory structure

<buildDirectory>/
	plugins/
		pluginToBuildA
		pluginToBuildB
			myProduct.product
		...
	features/
		featureToBuild
		...

<buildConfiguration>/
	build.properties

<baseLocation>
	plugins/
		org.eclipse.core.runtime
		org.eclipse.ui
		...
	features/
		org.eclipse.rcp
		org.eclipse.platform.launchers
		...
		

Running the build

To run the build you will use the org.elipse.ant.core.antRunner application. When invoking eclipse with this application to perform a build you need to set two arguments on the command line:

• -buildfile </path/to/productBuild.xml>:  This is the path to the productBuild.xml provided by pde build.  It is located in the org.eclipse.pde.build/scripts/productBuild directory.  This is the build file that drives the whole product build process.
• -Dbuilder=</path/to/configuration folder>:  This is the path to the build configuration folder.

Run the antRunner application using the following command:

java -jar startup.jar -application org.eclipse.ant.core.antRunner -buildfile <<eclipseInstall>/plugins/org.eclipse.pde.build_<version>/scripts/productBuild/productBuild.xml> -Dbuilder=<path to the build configuration folder>

Once the build is complete, you can get the result in the build directory in the folder named I.TestBuild (this name can be configured by setting the buildLabel property).

Advanced scenarios

Behind the scenes this setup will generate a feature containing the plugins or features specified in your product configuration file.  This generated feature is then used to drive a normal feature based headless build.  If you require more customization of the build, ie fetching from a repository, see the Building Features page for more information.