Building Cytoscape

This page will describe how to build the latest Cytoscape 2.x trunk build from source. For information in Cytoscape 3.0, please look here.

Tools required

To build Cytoscape trunk from source, you will need the following tools:

Java 1.6.x JDK
Apache Maven version 2.2.x (3.0 currently exhibits some problems with Cytoscape trunk)
A subversion (svn) client

You will need to ensure that these tools are added to your PATH if you intend to run them from the command line.

Basic development

To get started, you will need to check out the latest trunk build of Cytoscape from the SVN repository. In a directory that you would like to store the Cytoscape code, check out the latest Cytoscape trunk code from following repository:

http://chianti.ucsd.edu/svn/cytoscape/trunk

For example, if you are using the svn command-line client and want to check out to a directory called "cytoscape", you would use the following command:

svn co http://chianti.ucsd.edu/svn/cytoscape/trunk cytoscape

After checking out the code, you will want to increase the amount of PermGen space allocated to the JVM when running Maven builds. To do this, set the MAVEN_OPTS environment variable to the following value:

-XX:PermSize=64m -XX:MaxPermSize=128m

After doing this, you can use Maven to build Cytoscape from the directory in which your newly-checked-out code resides as follows:

mvn -Dmaven.test.skip=true install

Note that the "-Dmaven.test.skip=true" will skip building and running tests, which aren't strictly necessary to build Cytoscape (and may cause problems in the build process on some systems). If you want to run tests, simply exclude this command.

If you make changes to the code locally, you can avoid rebuilding all of Cytoscape by simply rebuilding the affected module. From the directory which contains the affected module (under the directory you checked out the Cytoscape source tree to), simply run Maven in the same way as mentioned above. After doing this, run mvn install from the parent directory again to rebuild Cytoscape using the new version of the modified module(s).

The binaries built using mvn install can be found in the distribution/target/cytoscape-<version>-null.dir/cytoscape-<version>/ directory under the directory which you checked out the Cytoscape source code.

Using Eclipse

If you want to develop using Eclipse, you will also need to install the following:

A recent version of Eclipse
Maven Integration for Eclipse plugin (m2eclipse)
If you want to use SVN from Eclipse: Subclipse (subversion plugin for Eclipse) (Subversive also will probably work, but has not been tested extensively)

To import an existing Cytoscape source tree into Eclipse, simply go to File->Import and choose Existing Maven Project to import the Cytoscape Maven project into Eclipse using m2eclipse. Locate the source tree on disk when prompted. Alternatively, do a File-> Import and choose Check Out Maven Projects from SCM. Use the URL from the Cytoscape repository listed above (http://chianti.ucsd.edu/svn/cytoscape/trunk), and use svn as the protocol. Note that this will create an Eclipse project for each Cytoscape project, so you may want to create a workspace or working set to separate the Cytoscape projects from other projects.

After importing the projects into Eclipse, however, you aren't done - you need to build Cytoscape using a custom run configuration. Right-click the "cytoscape" project in the Package Explorer and select Run As->Run Configurations. In the Run Configurations panel, click on Maven Build and click the New button in the upper-left-hand corner. Name the run configuration "cytoscape", enter "install" in the Goals field, and click the "Skip Tests" checkbox if you want to skip tests (this makes the build run faster and may be necessary when the tests don't work properly). Then, in the Maven Runtime section, click on "Configure..." , add your local Maven 2.2 install, and select it as the default. Also, in the "JRE" section, you will want to add the following under "VM arguments":

-XX:PermSize=64m -XX:MaxPermSize=128m

Finally, click "Run" to start the build process.

After building, find all the projects with a red X next to them and add all the folders directly under target/generated-sources (if it exists - refresh if you don't see it) to the build path by right-clicking on these folders and choosing Build Path-Use as Source Folder from the menu. Finally, you will have to tell Eclipse to exclude all of the "target" folders and other system files from version control. To do this, go to Window->Preferences and add the patterns "target" and ".*" (no quotes) to the list of ignored resources under Team-Ignored Resources. Now you should be able to work on Cytoscape code in Eclipse - to rebuild the Cytoscape source tree, just use the run configuration you created (and/or use the Run As right-click menu on projects to do standard Maven operations).

Running Cytoscape from Eclipse

If you want to quickly test changes to the Cytoscape source code from Eclipse, you will want to run Cytoscape from within Eclipse itself. To do this, go back to the Run Configurations screen. From here, create a new Java Application configuration. Choose "application" for the project and Cytoscape.CyMain for the main class. Under the Arguments tab, specify the following for Program Arguments:

-p ../cytoscape/distribution/target/cytoscape-<version>-null.dir/cytoscape-<version>/plugins

Substitute the current version in trunk for <version> (look at your cytoscape/distribution/target directory after building Cytoscape to find out the proper version to use here).

In Classpath, add all the projects comprising Cytoscape as well as the cytoscape.jar file from the parent directory of the above-mentioned path using "Add JARs". Press Run - if things are configured correctly, the trunk version of Cytoscape you build should run! If you make changes locally in Eclipse, these will be reflected in Cytoscape when run from Eclipse *without* the need to do a mvn install on the project!

Caveats