Running and Developing Cytoscape 3 on Eclipse

TableOfContents()

Introduction

This is a tutorial document to learn how to run and develop Cytoscape 3 with Eclipse PDE and other Eclipse plugins.

Procedure

Setting Up Your Environment

To develop Cytoscape 3 on Eclipse, you need to install several software packages.

Java Development Kit

You need to install JDK version 5 or 6.

Maven

Although you will use most of the functions from Eclipse IDE, it is better to install command line version of Maven in case you need to test your code from terminal. Also, internally this version of Maven will be used by Eclipse (will be described later).

• [http://maven.apache.org/download.html Download Maven]

• [:Cytoscape_3.0/Eclipse/M2EclipsePlugin:Maven Tutorial]

From terminal, type mvn --version and if you see something like the following, you are ready to use Maven:

[kono@beaujolais core]$ mvn --version
Maven version: 2.0.9
Java version: 1.5.0_15
OS name: "linux" version: "2.6.9-67.0.20.elsmp" arch: "i386" Family: "unix"

Eclipse

• attachment:eclipse_plugins0.png

This tutorial is based on the latest version of Eclipse 3.4, called Ganymede. Several distributions are available on [http://www.eclipse.org/downloads/packages/ Eclipse web site]. In this tutorial, we use Eclipse for RCP/Plug-in Developers version 3.4. This distribution includes PDE (Plugin development environment).

Eclipse Plugins

• attachment:eclipse_plugins1.png

Subversion Client (Subclipse)

Cytoscape 3 source code is managed by [http://subversion.tigris.org/ Subversion]. To access the repository, you need to install subversion client for Eclipse. In this tutorial, I'll use [http://subclipse.tigris.org/ Subclipse]. You can install the plugin from the eclipse's update manager. Do not forget to install SVNKit. Otherwise, you will get an error message when you try to check out repository ("Unable to load default SVN Client")

You can install the Subclipse plugin using Update Manager. URL is http://subclipse.tigris.org/update_1.4.x

After you finish the installation, you need to setup the repository location.

1. Select Window > Show View > Other > SVN > SVN Repository. SVN Repository viewer will be displayed.

2. Add new SVN repository by pressing following icon:
   • attachment:eclipse_plugins2.png
   Repository locations are the following:

   • Core Developers: svn+ssh://grenache.ucsd.edu/common/svn/cytoscape3

     • Note: you need to set up SSH client if you are a Windows user.

   • Others: http://chianti.ucsd.edu/svn/cytoscape3 - You can checkout the project from this URL, but cannot checkin.

   attachment:eclipse_plugins3.png

Do not checkout the project until you setup everything!

PAX Cursor

[http://wiki.ops4j.org/confluence/display/ops4j/Pax+Cursor PAX Cursor] is an Eclipse plugin developed by [http://wiki.ops4j.org/confluence/display/ops4j/Open+Participation+Software+for+Java OPS4J] developers. Basically, it is an Eclipse integration for [http://wiki.ops4j.org/confluence/display/ops4j/Pax+Runner PAX-Runner]. By this plugin, you can run set of bundles on multiple platforms including Felix, Equinox, and Knopflerfish.

To install this Eclipse plugin, just follow the standard procedure.

• PAX Cursor Eclipse Update Site - http://www.ops4j.org/pax/eclipse/update/

Maven Integration for Eclipse (m2eclipse)

Cytoscape build system has been moved to [http://maven.apache.org/ Maven]. To use maven from Eclipse, you need to follow [:MavenInfo:this] instruction. Even if you run all maven commands from Eclipse, you still need to install command-line version of Maven since Eclipse embedded version of maven have issues to execute some maven goals.

• m2eclipse plugin update site - http://m2eclipse.sonatype.org/update/

Replace Maven Executable Used in Eclipse

1. Open Preferences window from Window menu

2. Specify your local installation of Maven. Note: this is not the bin directory, the root of Maven installation

   • attachment:maven1.png

3. Set user settings.xml file location. This file can be copied from conf directory in the Maven root.

4. Apply settings

Now your machine is ready for Cytoscape 3 development!

My Testing Environment

I tested the following tutorial in the following environment:

• Common
  • Eclipse 3.4 Ganymede (32 bit version)
  • Apache Maven 2.0.9
  • Subclipse Plugin 1.4.1
  • m2eclipse Plugin 0.9.5.20080717-1821
  • Pax Cursor Plugin 0.6.0

• Test Platform 1 (Unix) Confirmed to work

  • RHEL 4 Workstation
  • Java SE 5 update 15

• Test Platform 2 (Windows) Still have some issues

  • Windows XP SP3

  • JDK SE 6 update 7 Important Note: You should use JDK, not JRE.

• Test Platform 3 (Mac) Confirmed to work

  • Mac OS X Tiger (10.4.11)
  • Apple's Java SE 5 (1.5.0_13)

Checkout and Create Cytoscape 3 Eclipse Project

In this section, you will learn how to create an Eclipse project from the fresh Cytoscape 3 checkout.

Checkout Cytoscape 3 Trunk

1. Start Eclipse. I recommend to use an empty, new workspace only for Cytoscape 3 project since it creates tons of new bundle projects in your workspace.

2. Select File → New → Other. Then select Checkout Maven Projects from SCM. Click Next

   • attachment:eclipse_core10.png

3. Select Source Code Management (SCM) system type to svn and set URL to svn+ssh://grenache.ucsd.edu/common/svn/cytoscape3/trunk. Click Finish

   • attachment:eclipse_core11.png
   This process takes a long time, depends on your network connection.
4. Your Eclipse workspace looks like the following image
   • attachment:eclipse_core2.png

Build Project and Run Cytoscape 3 on Felix

1. Select core project on the workspace. Right click and select Run As > Maven install. This command builds and install Cytoscape 3 bundles to your local maven repository.

2. Select Run → Run Configurations

3. Create new Maven Build and name it

4. Set the Base directory to core bundle

5. Set the goal to pax:provision

   • attachment:eclipse_core20.png
6. Apply and Run. You can use Felix Shell commands on the console.
   • attachment:eclipse_core21.png
7. Quit Cytoscape

Debug Cytoscape 3 on Eclipse with PAX Cursor

In this section, you will learn how to debug Cytoscape 3 on Eclipse.

1. First, let's set a sample break point in CytoscapeInit class, which is a clas to startup Cytoscape. You can set breakpoint anywhere in the public boolean init(CyInitParams params) method.

   • attachment:pax0.png

2. From Eclipse main window, select Run → Debug Configurations

3. Right click on OSGi Framework and select New

4. Name the configuration Cytoscape 3

5. Switch framework to Felix 1.0.4

6. None of the files should be selected in the bundle list

   • attachment:pax1.png

7. Click the Pax Cursor' tab

8. Click Add Pom. Then select pom file under runner directory.

   • attachment:pax2.png

9. Apply and Debug

   • attachment:pax3.png
10. Now you can see Cytoscape running on Felix and debugger shows current status of variables
    • attachment:pax4.png

The Following Section is obsolete and will be updated shortly...

• }}}

• Type help. You will see help messages for Equinox shell commands. You can play with them by typing commands in the console.

  osgi> help
  
  ---Application Admin Commands---
          activeApps - lists all running application IDs
          apps - lists all installed application IDs
          lockApp <application id> - locks the specified application ID
          schedApp <application id> <time filter> [true|false] - schedules the specified application id to launch at the specified time filter.  Can optionally make the schedule recurring.
          startApp <application id> - starts the specified application ID
          stopApp <application id> - stops the specified running application ID
          unlockApp <application id> - unlocks the specified application ID
          unschedApp <application id> - unschedules all scheduled applications with the specified application ID
  ---Extension Registry Commands---
          ns [-v] [name] - display extension points in the namespace; add -v to display extensions
          pt [-v] uniqueExtensionPointId - display the extension point and extensions; add -v to display config elements---Eclipse Runtime commands---
          diag - Displays unsatisfied constraints for the specified bundle(s).
          enableBundle - enable the specified bundle(s)
          disableBundle - disable the specified bundle(s)
          disabledBundles - list disabled bundles in the system
  ---Controlling the OSGi framework---
          launch - start the OSGi Framework
          shutdown - shutdown the OSGi Framework
          close - shutdown and exit
          exit - exit immediately (System.exit)
          init - uninstall all bundles

• To stop, type exit

Note: The behaviour of Cytoscpae 3 running on Equinox will be different from time to time. This is because budle loading timing is not properly controlled now. This will be solved by organizing bundle/service dependency. I'm working on this issue now and hopefully it will be solved soon.

Develop Cytoscape 3 Code on Eclipse PDE

Now you are ready to hack Cytoscape 3 on Eclipse. As you can see on your workspace, Cytoscape 3 is a collection of OSGi bundles. Each bundle is build as a Maven project and has a pom.xml file.

Currently, the desktop version of Cytoscape 3 is called application bundle. Under src/main/java you can see the source tree. You can edit these source files just like 2.x series, and create the bundle by running maven commands. To run them, you need to select (right click) the project name and then select maven command from Run As menu:

• attachment:eclipse_core6.png

• maven clean - clean all classes from target directory.
• maven install - build everything, create bundles, and run tests

To run your modified code, you just need to do maven install.

Debugging Cytoscape 3 Code with Eclipse Debugger

To debug Cytoscape 3, use the Cytoscape 3 Run Configuration created above. The only difference is you need to use debug perspective when you run debugger.

Troubleshooting

1. Somehow Cytoscape 3 Eclipse project is broken and no longer working with Eclipse

   • From terminal, run mvn eclipse:clean clean package again. This cleans up everything and gives you a fresh workspace.

This document is written by KeiichiroOno DateTime()

If you have any questions, please e-mail me (kono at ucsd dot edu)