Developer's Tutorial for Cytoscape 3 on Eclipse: Rev. 1.1

Status

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

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

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

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 from Help > Software Updates... Click Available Software tab and add this URL by pressing Add Site button: http://subclipse.tigris.org/update_1.4.x

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 plugin installation procedure discussed above.

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.

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've tested the following tutorial on these platforms:

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 Window > Show View > Other > SVN > SVN Repository. SVN Repository viewer will be displayed.

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

    Once you specify the repository location, you can see the entire repository tree. The Cytoscape 3 repository is cytoscape3/trunk. attachment:eclipse_plugins3.png

  4. From SVN Repository window, right-click cytoscape3 > trunk and select Check out as Maven project...

  5. Select Source Code Management (SCM) system type to svn and make sure the URL is set to http://chianti.ucsd.edu/svn/cytoscape3/trunk (for core developers, svn+ssh://grenache.ucsd.edu/common/svn/cytoscape3/trunk).

  6. Click Finish

    • attachment:eclipse_core11.png
    This process takes 5-10 minutes depends on your network connection.
  7. Now your Eclipse workspace looks like the following:
    • attachment:eclipse_core2.png

Build Project and Run Cytoscape 3 on Felix

First, let's build and run Cytoscape 3 from Eclipse.

  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 and it takes several minutes to complete (depends on your machine power).

    • attachment:maven_install.png
      • If you cannot complete this process due to failing tests, try the following:

        1. Select Run > Run Configurations

        2. Set core as the base directory

        3. Set install for goal and check Skip Tests

        4. Apply and Run

          • attachment:maven_install2.png

        This is a workaround for failing tests in Windows environment. We are working on this issue and once it is solved, you can call install goal from right-click menu.

  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 the class to startup Cytoscape. It is in application/src/main/java/cytoscape/CytoscapeInit.java. You can set breakpoint anywhere in the public boolean init(CyInitParams params) method.

    • attachment:debug0.png 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. To get the deploy-pom.xml file to show, you have to change the File of type ComboBox to have Any File.

    • 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

    Just like other applications, Eclipse debugger stops execution at the break-point you specified in the source code. To start again, you need to press green triangle (Resume button).

    • attachment:pax5.png

Basically, the debugging process is same as regular Java projects. Once you edit something in the source code, you can rebuild and deploy it to local repository by Maven install command. Then you can repeat the procedure above to check internal states of Cytoscape 3 by Eclipse debugger.

Working with Felix OSGi Console

Cytoscape 3 is an OSGi application and you can check the status of bundles from OSGi console. After you start Cytoscape 3 from Eclipse, you can see a prompt on the Console window (if not, hit enter in the console to show the prompt). The following is some useful command to check internal states of the OSGi system. For more information, please visit [Felix web site].

Note: The behaviour of Cytoscpae 3 running on Felix 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.

Additional Notes

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 built 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:

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

Troubleshooting

  1. Somehow Cytoscape 3 Eclipse project is broken and I cannot compile it anymore

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

  2. pax:provision fails. What should I do?

    • Cleaning up the working space (maven clean) and rebuilding it (maven install) solves this problem in most cases.

  3. Cannot compile application bundle. Eclipse display some warning messages and cannot complete install goal

    • Comment out following lines in pom.xml in core directory: 

      • <showWarnings>true</showWarnings>
<showDeprecation>true</showDeprecation>
      We are working on this problem.

This document is written by KeiichiroOno DateTime()

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

Funding for Cytoscape is provided by a federal grant from the U.S. National Institute of General Medical Sciences (NIGMS) of the Na tional Institutes of Health (NIH) under award number GM070743-01. Corporate funding is provided through a contract from Unilever PLC.

MoinMoin Appliance - Powered by TurnKey Linux