Introduction to the PDE Build CDBS helpers

Authors: Ivan S. Dubrov <wfragg@gmail.com>

Copyright © 2005-2006 Ivan S. Dubrov

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.

Introduction

PDE Build CDBS helpers (cdbs-eclipse package) are the extensions to the CDBS. The documentation for the CDBS is provided with the cdbs Debian package.

PDE Build CDBS helpers are designed to simplify building and packaging Eclipse plugins into the Debian packages.

Quick Start

Using the cdbs-eclipse is simple; Simple rules are written like this:

#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/eclipse-pdebuild.mk

And that's all! However, the proper directory structure must present. If it is not, it should be created first.

Directory structure

The helper scripts require that the project directory contains the following subdirectories:

• plugins/
• features/
• releng/

The plugins/ contains the Eclipse plugins projects, with directories named after the plugin identifier (i.e, plugin org.tigris.subversion.subclipse.core should reside in the plugins/org.tigris.subversion.subclipse.core directory). The feature/ subdirectory is the same for feature projects.

The releng directory should contain two files, customTargets.xml and build.properties.

customTargets.xml is the Ant build file that specifies the plugins and features. It is not invoked directly, but called by the Eclipse PDE Build scripts. It should delegate to the targets in the genericsTargets.xml from the org.eclipse.pde.build Eclipse plugin.

build.properties contains several properties that affect the build process. Here is the example of the build.properties:

skipFetch=true

See Build and Test Automation for plug-ins and features for more details.

The default directories can be overriden by the certain variables. The list of variables can be found in the following section.

Variables

The following tables provides the variables supported by the eclipse-pdebuild make script:

Variable	Default value	Description
PDEBUILD_HOST	/usr/lib/eclipse	Host Eclipse SDK for building
PDEBUILD_HOSTLOCAL	./debian/eclipse-local	Directory where local Eclipse SDK instance is created. Note: must be absolute
PDEBUILD_BASELOCATION	$(PDEBUILD_HOSTLOCAL)	Directory to the Eclipse installation that contains additional plugins to be used during the build
PDEBUILD_BUILDER	./releng	PDE Build release engineering directory, with build.properties and customTargets.xml
PDEBUILD_CONFIG	debian/tmp/configure	Eclipse configuration location
PDEBUILD_DATA	debian/tmp/workspace	Eclipse data location
PDEBUILD_BUILDDIR	$(CURDIR)	Directory where plugins are built. Should contain two subdirectories, plugins and features. Each of these contains plugins and features that are built.
PDEBUILD_LINKS		Link names to enable when creating local Eclipse SDK instance. Each name is name of the file in the $(PDEBUILD_HOST)/links/ directory without the .link extension
PDEBUILD_OPTS		Additional Eclipse parameters
PDEBUILD_VMARGS		Additional Java VM parameters

Sample case - Subclipse build script

Let's look into the Subclipse build script to see how pdebuild can be used. The script is located in the Subversion repository here: Subclipse build script.

First of all, we need a build directory that will be used by the PDE Build for built plugins and features as well as for searching the sources. Since PDE requires fixed sources structure we cannot use the package root for this. We will use the the debian/tmp:

PDEBUILD_BUILDDIR := $(CURDIR)/debian/tmp

Next thing is to create certain sources layout in this directory. The simplest way is to use symlinks to symlink plugins/features source folders to the certain places. The plugins sources should be in the plugins/<plugin.id> directiories and features - in the features/<plugin.id>. At the same time, we can symlink required libraries from the /usr/share/java.

Here is the snippet from the Subclipse build script:

# Configure layout for PDE Build
pre-build::
	mkdir -p $(PLUGINS)
	mkdir -p $(FEATURES)
	ln -s $(CURDIR)/core $(PLUGINS)/org.tigris.subversion.subclipse.core
	ln -s $(CURDIR)/ui $(PLUGINS)/org.tigris.subversion.subclipse.ui
	ln -s $(CURDIR)/feature-plugin $(PLUGINS)/org.tigris.subversion.subclipse
	ln -s $(CURDIR)/feature $(FEATURES)/org.tigris.subversion.subclipse
	ln -sf /usr/share/java/svn-clientadapter.jar core/lib/svnClientAdapter.jar
	ln -sf /usr/share/java/svn-javahl.jar core/lib/svnjavahl.jar
	ln -sf /usr/share/java/ganymed-ssh2.jar core/lib/ganymed.jar
	ln -sf /usr/share/java/javasvn.jar core/lib/javasvn.jar

Then we can remove intermediate files that are generated during the build process:

# Remove temporary files and generated build scripts
common-post-build-indep::
	-rm -rf ui/temp.folder
	-rm -rf core/temp.folder
	-rm core/build.xml # It is generated, no need to save
	-rm ui/build.xml # It is generated, no need to save
	-rm feature/build.xml # It is generated, no need to save

Finally, the clean target removes symlinks to the libraries and build .jar files:

#
clean::
	# Remove symlinks
	-rm core/lib/svnjavahl.jar
	-rm core/lib/ganymed.jar
	-rm core/lib/javasvn.jar
	-rm core/lib/svnClientAdapter.jar
	# Remove built files
	-rm core/SVNPluginCore.jar
	# UI plugin	
	-rm ui/SVNPluginUI.jar

As you can see, in this case the only used variable is PDEBUILD_BUILDDIR.