SolarNode Development Guide

This guide explains how to setup a development environment for contributing or modifying the SolarNode application code.

The SolarNode project consists of a set of OSGi bundle projects that, when combined and run in an OSGi container, form a complete SolarNode application. Each OSGi bundle comes configured as an Eclipse IDE plug-in project (Eclipse refers to OSGi bundles as "plug-ins" and its OSGi development tools are collectively known as PDE). Although Eclipse is not actually required, the remainder of this guide will describe setting up Eclipse for viewing and running the code for development purposes.

Eclipse Setup

Download a recent version of the Eclipse IDE from http://www.eclipse.org/downloads/. At a minimum you'll want the Eclipse for RCP/Plug-in Developers package, but if you plan to also work on the SolarNet code you should get the Eclipse IDE for Java EE Developers.

Most likely you will want to start with a new workspace for SolarNode development. When you launch Eclipse it might ask you for a workspace location, at which time you can point it at a new directory, or once Eclipse is running you can choose File > Switch Workspace > Other... to create a new one.

Eclipse Subversion support

Once you have Eclipse installed and running, you'll need to install support for Subversion. There are two popular Subversion plug-ins for Eclipse, Subversive and Subclipse. This guide will describe using Subversive. To install Subversive, follow this guide.

If you'd rather use Subclipse, there is a guide to installing that here.

Eclipse Spring support

Another useful plug-in for Eclipse is the Spring IDE. The Eclipse Update Site for this is http://dist.springframework.org/release/IDE.

Checkout SolarNode code from Subversion

In Eclipse, add a new Subversion repository by going to Window > Open Perspective > SVN Repository Exploring (you may need to choose "Other..." under Open Perspective if SVN does not appear there).

In the SVN Repositories view, right-click and choose New > Repository Location... For the URL enter

https://solarnetwork.svn.sourceforge.net/svnroot/solarnetwork/modules

If you are an approved developer on the project, enter your SourceForge username and password. Otherwise leave these empty.

On the Advanced tab, make sure the Enable Structure Detection checkbox is enabled, and that trunk, branches, and tags are used for the Trunk, Branches, and Tags fields. These are the defaults so you probably don't need to change anything here.

Click the Finish button and after a moment the SVN repository will appear in the SVN Repositories view. Open up the repository by clicking on the arrow to the left of its name.

The top level of the SVN tree contains several high-level modules. Under each module will be individual projects for each component within that module. For SolarNode development, you need to check out the projects within these modules:

1. common
2. external
3. node

For each module, expand the directory to reveal the trunk branch, then right-click on trunk and Find/Check Out As....

This will open a dialog where Eclipse can search for sub-projects for you to check out from SVN. Choose the Find projects in the children of the selected resource and then select Recursively for the Depth option.

It will take several minutes for the project scan to complete. Once this has finished, a dialog will appear to check out the projects it found. Although you may not need to check out every project listed to work on SolarNode development, at this point it will be easiest to just check out everything listed.

Click the Finish button to check out the projects. It will take several more minutes for the projects to check out. After the check out completes, you can return to the Java, JEE, or Plug-In perspective in Eclipse and you will see the bundle projects, which should look similar to the following (Note that Eclipse will report errors in most projects, which we will fix in the next step):

Set up Eclipse Target Platform

Eclipse PDE provides you with an OSGi development environment based on the Equinox OSGi container that allows you to write, compile, and run OSGi bundles in easily. SolarNode depends on a number of 3rd-party OSGi bundles, and those bundles, combined with the SolarNode bundles, are combined into what Eclipse calls a Target Platform. You must configure the Target Platform so that Eclipse can compile and run the SolarNode bundles.

In Eclipse, open the solarnetwork-osgi-target project and then the defs/solarnetwork-gemini.target file.

Click on the Set as Target Platform link in the upper-right.

This will create and activate the Eclipse target platform, and all Eclipse errors for all projects should go away. If any errors remain, select those projects and choose Project > Clean... to have Eclipse re-compile those projects again. Sometimes Eclipse incorrectly reports problems, and cleaning those projects will resolve the errors (you will find references to this situation on the web called "the Eclipse dance").

Eclipse code templates

If you will be developing code to contribute to the SolarNetwork project, you should also import the SolarNetwork Eclipse code templates. The templates are located in the /solarnetwork-osgi-target/defs/solarnetwork-codetemplates.xml file. To import them, open the Eclipse preferences, go to Java > Code Style > Code Templates and click the Import... button, and select the solarnetwork-codetemplates.xml file.

Configuring your SolarNode development environment

To get started working in the SolarNode development environment, go to the SolarNode Development Configuration Guide page.