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.

Procedure

Setting Up Your Environment

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

Eclipse

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).

Subversion

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

Repository locations are the following:

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

• Others: http://chianti.ucsd.edu/svn/cytoscape3/

You need to checkout the trunk directory.

Maven and Maven Integration for Eclipse

Cytoscape build system has been moved to Maven. To use maven on 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 problems to run some of pax-construct commands.

Introduction to m2eclipse plugin features is available [:Cytoscape_3.0/Eclipse/M2EclipsePlugin:here].

Replace Maven Executable

Although M2eclipse plugin has embedded version of maven, it has some issues if you want to use it with maven-pax-plugin. To avoid this, you need to replace the executable with the command-line version of maven.

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 Maven root directory

4. Apply settings

Now your Eclipse 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

• 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 Rebuild Eclipse Project Files

1. Select core project on the workspace. Right click and select Run As > Maven install. This process takes a long time...

2. Select Run > Run Configurations..., then create new Maven Build

3. Press Browse Workspace and select core project as the base directory

4. Name the build Rebuild Eclipse Project Files

5. For Goals, select pax > eclipse. Then press Apply and Run. This process takes 10-20 minutes depends on your network connection

   • attachment:eclipse_core22.png
6. Refresh the entire workspace (F5)

Run Cytoscape 3 on Eclipse

Eclipse is running on an OSGi implementation called [http://www.eclipse.org/equinox/ Equinox]. Since Cytoscape 3 is following OSGi standard, (theoritically) you can run it on any OSGi environments. In this example, you will run Cytoscape 3 using Equinox.

1. From Eclipse main window, select Run → Run Configurations

2. Right click on OSGi Framework and select New

   • attachment:eclipse_core3.png

3. Name the configuration Cytoscape 3

4. By default, every bundle available in current Equinox environment is selected. Uncheck Target Platform bundles. At this point, only Cytoscape 3 bundles are selected.

5. Press Add Required Bundles button. This function automatically select required (infrastructure) bundles to run Cytoscape 3 bundles under Workspace

   • attachment:eclipse_core4.png

6. Press Run. After few moments, Cytoscape Desktop appears. In the console window, you can see the messages to standard output

   • attachment:eclipse_c3main.png attachment:eclipse_core5.png
   You may see several error messages or exceptions, but it is normal because current Cytoscape 3 trunk is not fully working version of Cytoscape.

7. On the Console, hit enter. Then you will see the Equinox's command prompt

   osgi>

8. Type ss. This command displays current status of bundles running on Equinox.

   osgi> ss
   
   Framework is launched.
   
   id      State       Bundle
   0       ACTIVE      org.eclipse.osgi_3.4.0.v20080605-1900
                       Fragments=48
   1       ACTIVE      com.sun.xml.bind.jaxb-xjc_2.0.0
   2       ACTIVE      csplugins.quickfind_1.0.0.SNAPSHOT
   3       ACTIVE      phoebe.dnd_1.0.0.SNAPSHOT
   4       ACTIVE      org.freehep.swing_2.0.2
   5       ACTIVE      org.eclipse.datatools.modelbase.sql.query_1.0.1.v200805152355
   6       ACTIVE      net.sourceforge.lpg.lpgjavaruntime_1.1.0.v200803061910
   7       ACTIVE      cytoscape.graph.dynamic_1.0.0.SNAPSHOT
   8       RESOLVED    org.eclipse.core.runtime.compatibility.registry_3.2.200.v20080610
                       Master=31
   9       ACTIVE      cytoscape.graph.fixed_1.0.0.SNAPSHOT
   10      ACTIVE      cytoscape-temp.sbml2_1.0.0
   11      ACTIVE      cytoscape.geom.rtree_1.0.0.SNAPSHOT
   12      RESOLVED    org.eclipse.core.resources.compatibility_3.4.0.v20080604-1400
                       Master=77
   13      ACTIVE      org.eclipse.ant.core_3.2.0.v20080529
    .
    .
    .

9. 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

10. 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

Essentially, there is no difference between regular Java program debugging and OSGi system debugging. Eclipse built-in OSGi environment is integrated to other part of Eclipse, and you can use most of the functions available in Eclipse.

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.

Run Cytoscape 3 on Felix

You can also run Cytoscape 3 from Eclipse using pax:provision command. To do this, you need to create a new Run Configuration.

1. Select Run → Run Configurations

2. Create new Maven Build and name it

3. Set the Base directory to core bundle

4. Set the goal to pax:provision

   • attachment:eclipse_core20.png
5. Apply and Run. You can use Felix Shell commands on the console.
   • attachment:eclipse_core21.png

Note: you cannot use debugger when you use pax-plugin from Eclipse. For debugging, use PDE's OSGi environment instead

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)