overview

If you read this, I guess you're a developper that is interested in participating in the boneclipse project, or you want to build boneclipse from source, and/or want to understand the internals.

This document presents the boneclipse structure and explains how to build and test it using the Eclipse runtime-workbench. It focuses on Eclipse integration. This is a draft subject to change. To begin with you should checkout a fresh version of the various boneclipse modules. The current modules in boneclipse are:

  • com.bonevich.eclipse.plugins
  • com.bonevich.eclipse.cvsgrapher
  • com.bonevich.eclipse.logging

The com.bonevich.eclipse.plugins project is the master project and build process controller. The build process is triggered by calling

maven build-all
in this project.

The com.bonevich.eclipse.cvsgrapher and com.bonevich.eclipse.logging projects are Eclipse plugin projects.

building the various artifacts

The build-all custom goal defined in com.bonevich.eclipse.plugins/maven.xml allows us to run the Maven reactor against the entire project. The Ant buildfile ( build.xml ) in that module wraps the call to maven defining a target buil d-all which uses an exec target.

Site generation has been reactored too. The site generation process can be triggered by running maven build-site . This goal too has been wrapped by an Ant target ( build-site ).

The file base-project.xml defines the basic POM from which all subproject POMs should inherit

configuring the build process

Building the boneclipse subprojects is a bit tricky to configure since most of the Eclipse libraries are not present at ibiblio (I plan to submit requests to upload them). So I can see two ways of solving this issue:

  1. copy all required missing dependencies to the repository
  2. use the maven jar overriding feature

I choose the first solution because (1) it uses then the common mechanism and (2) it does not pollute the project.properties file. However, in either case we need to set some properties:

  • eclipse.home because it is config dependent
  • swt.plugin.dir because it is system dependent

We take care of the jar copy by adding a preGoal for build in which I have defined which jars are needed as, for example, in the lines below:

			
<copy file="${eclipse.home}/plugins/org.eclipse.core.resources_2.1.0/resources.jar" 
      tofile="${maven.home}/repository/eclipse/jars/eclipse-resources-2.1.0.jar"/>
...
<copy file="${eclipse.home}/plugins/${swt.plugin.dir}/swt.jar" 
      tofile="${maven.home}/repository/eclipse/jars/eclipse-swt-2.1.0.jar"/>	
			
		 

Concerning the site generation, I chose to use a property to identify the siteDirectory boneclipse.local.siteDirectory and, in order for the links to be correct urls, I've added another property that identifies the protocol use d: boneclipse.site.prefix

So, in brief, you need to set the following properties in project.properties :

  • eclipse.home
  • swt.plugin.dir
  • boneclipse.local.siteDirectory (optional, for site generation only)
  • boneclipse.site.prefix (optional, for site generation only)

In addition, for the Ant script to work, you must set these two properties in build.properties :

  • maven.home
  • maven.script

and then invoke maven build . This process is not as simple as it could be. We need to think about making it easier and more straightforward, so that configuration could be abstracted more.

launching the Runtime-workbench

At this point you should have been able to build the projects thanks to Maven (and, as a corollary, to configure your Eclipse workspace).

Before launching the runtime-workbench, please make sure that the boneclipse directory layout is correct regarding the meta-information contained in the plugin.xml plugin descriptor. However it should have been prepared during the Maven build process thanks to the boneclipse:prepare-lib goal. If not, you can either manually execute the required steps or run that goal

maven boneclipse:prepare-lib

The plugins use a large number of libraries, so we group them under the /lib directory. We also declare the /etc directory to be a runtime-dependency containing only resources. Icons are stored in the /icons directory. Your project layout should look like this:

${eclipse.plugins.dir}/${boneclipse.project}_1_0_0/
    +- etc/
	|   +- META-INF/
	|   |
	|   +- commons-logging.properties
	|
	+- icons/
	|   |
	|   +- *.gif
	|
	+- lib
	|   |
	|   +- *.jar
	|   
	+- plugin.xml
	|
	+- ${plugin.resource.files}
	|
	+- ${boneclipse.project}_1.0.0.jar
	  

runtime testing

Just select Run->Run As->Run-time Workbench and you should be good to go for testing. You may need to make sure that you have the Runtime Workbench settings properly configured, but the default ought to work.

coding conventions

To be done ...