## page was renamed from Cytoscape_3.0/Eclipse/CoreDevelopment = Checkout, Compile, and Test Cytoscape 3 Core on Eclipse 3.5 Galileo = == Status == * '''Now we are back to 3 development and this document needs to be updated. From now on, I'll use the following tools as standard development environment for Cytoscape 3:''' * Java 6 u21 * Eclipse 3.6 Helios PDE * m2Eclipse + Extras v0.10.x * Spring IDE v2.3.2 * Subclipse v1.6.12 Please read notes on [[Cytoscape_3.0/Eclipse/Helios|latest tools page]]. (7/29/2010 KeiichiroOno) * Document revesion 1.6: Updated for Galileo and Cytoscape IDE 0.2.2 (10/5/2009 by KeiichiroOno) * (!) As of Sep. 2009, target platform for Cytoscape 3 is [[http://java.sun.com/javase/6/docs/api/|Java 6]]. For Cytoscape 3 development, please use [[http://java.sun.com/javase/downloads/index.jsp|JDK 6]]. <> == Introduction == This tutorial is for Java developers who wants to learn how to checkout code, compile, and test Cytoscape 3 within Eclipse PDE. ----- = Tutorial = == Step 1. Setup Your Environment == To develop Cytoscape 3 on Eclipse, you need to install several software packages. === 1. Java Development Kit (JDK) === You need to install JDK version 6. If you use Mac, please use Intel Mac with Snow Leopard (or Mac with 64bit support + Leopard). Should work on both 32 bit and 64 bit versions. I tested this tutorial with the following JDK and Mac OS X 10.6.1: {{{ gamay:~ kono$ java -version java version "1.6.0_15" Java(TM) SE Runtime Environment (build 1.6.0_15-b03-219) Java HotSpot(TM) 64-Bit Server VM (build 14.1-b02-90, mixed mode) }}} === 2. Eclipse PDE === {{attachment:eclipse_plugins0.png}} This tutorial is based on the latest version of Eclipse 3.5, called ''Galileo''. 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.5'''''. This distribution includes PDE (Plugin development environment). '''''I recommend to install latest version of Eclipse PDE to a new directory on your machine. Otherwise, the screenshots may be different due to Eclipse plugins you have already installed on your machine'''''. You can install Eclipse by just extracting archive file (zip/gzip) to a directoly of your choice. By default, the ''eclipse'' directory should look like the following: {{attachment:eclipse_default1.png}} To keep your Eclipse up-to-date, you can update plugins by software updater (help-->software updates...) ==== For Windows Users: Set JDK's JVM for Eclipse ==== Usually, Eclipse for Windows use JRE virtual machine instead of JDK's VM. To use JDK's VM, create a shortcut and edit the shortcut's property: {{{ eclipse.exe -vm "c:¥path to jdk¥bin¥javaw.exe" }}} === 3. Cytoscape IDE === {{attachment:cytoscape_ide1.png}} You can install all required Elcipse plugins for Cytoscape 3 development at once by installing '''''Cytoscape IDE Plugin for Eclipse'''''. 1. Select '''''Help-->Install New Software...''''' {{attachment:cytoscape_ide_new_software.png}} 1. Click '''''Add''''' {{attachment:cytoscape_ide_add_site.png}} 1. Type '''''Cytoscape Update Site''''' for Name text box and type '''''http://chianti.ucsd.edu/~kono/data/cyide''''' in the ''Location'' text box. Press OK. {{attachment:cytoscape_ide_select.png}} 1. Eclipse automatically scans the location and displays available plugins. '''''You have to choose only one plugin, Cytoscape IDE for Eclipse 3.5''''' 1. Click '''''Next''''' button and follow the instructions. This process takes several minutes because it installes lots of plugins at once. When installation is complete, you will be asked to restart Eclipse. Press Yes and restart Eclipse. 1. Select '''''Window-->Open Perspective-->Other'''''. Then you can find '''''Cytoscape IDE''''' as a new perspective. Select it and press ''OK'' 1. If your workspace layout looks like the following, Eclipse is ready to develop Cytoscape 3. {{attachment:cytoscape_ide5.png}} ==== Note: My Testing Environment ==== I've tested the following tutorial on this environment: * Eclipse PDE 3.5 Galileo (Eclipse for RCP/Plug-in Developers Build id: 20090920-1017) * Mac OS X Snow Leopard 10.6.1 * Apple Java SE 64 bit version 1.6.0_15 ---- == Step 2. 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. Make sure Cytoscape IDE perspective is selected. 1. Turn off automatic build. (uncheck '''''Project > Build Automatically''''') 1. Select '''''SVN Repository''''' tab. Cytoscape subversion repository will appear automatically. 1. If you are a core developer, use '''''svn+ssh://grenache.ucsd.edu/cellar/common/svn'''''. You need id and pssword. Otherwise, use '''''http://chianti.ucsd.edu/svn'''''. You can checkout the project from this URL, but cannot checkin. 1. The Cytoscape 3 repository is '''''cytoscape3/trunk'''''. {{attachment:eclipse_repository1.png}} 1. From '''''SVN Repository''''' window, right-click '''''cytoscape3 > trunk''''' and select '''''Check out as Maven project...''''' 1. 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/cellar/common/svn/cytoscape3/trunk'''''). 1. Make sure '''''Check out All projects''''' checkbox is unchecked. Then click '''''Finish''''' {{attachment:eclipse_core11.png}} This process takes 5-10 minutes depends on your network connection. 1. You will be asked to select maven projects you want to import. Select '''top-level pom''' and '''application''' ONLY. {{attachment:select_pom.png}} 1. Select '''''Package Explorer''''' tab. Your Eclipse workspace looks like the following: {{attachment:eclipse_ws_default.png}} == Step 3. Build and Run Cytoscape 3 on OSGi Frameworks == {{attachment:cs3_nimbus1.png}} ~-(Cytoscape 3 running on Windows XP + Java 6 update 13 with Nimbus L&F)-~ First, let's build and run Cytoscape 3 from Eclipse workspace. 1. Select '''''core''''' project on the workspace. Right click and select '''''Run As > Maven install'''''. When you select this command, Eclipse builds and installs Cytoscape 3 bundles to your local maven repository ('''''$HOME/.m2'''''). It takes several minutes to complete (depends on your machine power). {{attachment:maven_install.png}} 1. You will see the message in the console if it is successful. {{attachment:maven_install_success.png}} 1. Select '''''Run → Run Configurations''''' 1. Create new '''''Maven Build''''' and name it 1. Set the ''Base directory'' to '''''core''''' bundle 1. Set the goal to '''''pax:run''''' {{attachment:eclipse_core20.png}} 1. Apply and Run. You can use Felix Shell commands on the console. {{attachment:eclipse_core21.png}} 1. Quit Cytoscape ==== For Windows Users ==== {{{ [FelixStartLevel] DEBUG org.springframework.osgi.extender.internal.activator.ContextLoaderListener - Setting globally defined wait-for-dependencies timeout value=300000 ms, for bundle [org.cytoscape.work-swing-impl (org.cytoscape.work-swing-impl)] [FelixDispatchQueue] DEBUG cytoscape.application - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.cytoscape.presentation-api - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.cytoscape.splash - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.swinglabs.swing-layout - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.cytoscape.cy-commons-cli - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.cytoscape.viewmodel - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.cytoscape.work-spring-hack - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.cytoscape.io-api - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.cytoscape.work-swing-impl - BundleEvent STARTED [FelixDispatchQueue] DEBUG org.cytoscape.view.vizmap - BundleEvent RESOLVED [FelixDispatchQueue] DEBUG org.cytoscape.session-api - BundleEvent RESOLVED }}} Somehow, you need to press enter several times after the message above if you use Windows. Otherwise, you cannot proceed. === Generate Manifest File for Eclipse PDE === At this point, '''''application''''' project is configured as Maven project. This means you can use m2eclipse plugin's features for the project, such as POM file editor, dependency graph visualization, etc. Since Cytoscape 3 is an OSGi application, actual distribution file (jar file) always include a manifest file '''''MANIFEST.MF,''''' which is a meta data for the OSGi bundle. As you know, all Eclipse plugins are also OSGi bundles, you can use PDE's Manifest editor features for Cytoscape projects. You can configure Cytoscape 3 application project as an PDE project by following the procedure below: 1. Select '''''Run > Run Configurations...''''' 1. Create new ''Maven Build'' 1. Name it '''''Generate Manifest for Eclipse''''' 1. Click '''''Browse Workspace''''' and select '''''application''''' project. 1. Set '''''install pax:eclipse''''' for ''goals'' 1. '''''Apply''''' and '''''Run'''''. {{attachment:osgi_nature1.png}} 1. Once it is done, refresh the workspace (press F5) and/or refresh maven project configuration by selecting '''''Maven ---> Update Maven Configuration'''''. You can see '''''META-INF''''' directory and under the folder, you can find '''''MANIFEST.MF''''' file. This is the metadata for OSGi bundle. 1. Right-Click '''application''' and select '''''PDE Tools ---> Open Manifest'''''. You can see the summary of the metadata. {{attachment:osgi_nature4.png}} {{attachment:osgi_nature2.png}} Editing this metadata file by writing BND statements is beyond the scope of this tutorial and will be discussed later in [[Cytoscape_3.0/Eclipse/PluginDevelopment|Plugin Development]] section. However by using this feature, you can see what packages are available for the selected project (bundle), and what packages will be exported as public API. {{attachment:osgi_nature3.png}} ==== Important Note: Maven and PDE ==== Eclipse PDE has a feature to build OSGi bundle manually. In this case, you need to edit MANIFEST.MF file by hand using PDE's Manifest editor. However, in Cytoscape project, we use [[http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html|BND from Maven]] to generate MANIFEST-MF automatically. '''This means, even if you edit MANIFEST.MF file in your Eclipse project, it will not be used when you create bundle!''' Therefore, you can use PDE's manifest editor as viewer of current manifest file generated by maven plugin, but cannot use it as an editor. You can control the manifest file generation process by editing '''''pom.xml''''' and '''''osgi.bnd'''''. This will be discussed in plugin development documents. == Step 4. Debug Cytoscape 3 on Eclipse with PAX Cursor == In this section, you learn how to debug Cytoscape 3 on Eclipse. 1. First, set a break point in '''''!CytoscapeDesktop''''' class, which is the class to startup Cytoscape Desktop GUI. It is in ''''' application/src/main/java/cytoscape/internam/view/CytoscapeDesktop.java'''''. You can set breakpoint anywhere in the code. {{attachment:debug0.png}} 1. From Eclipse main window, select '''''Run → Debug Configurations''''' 1. Right click on '''''OSGi Framework''''' and select '''''New''''' 1. Name the configuration '''''Debug Cytoscape 3''''' 1. Check ''log'' {{attachment:pax1.png}} 1. Select pom file under '''''runner''''' directory. To get the deploy-pom.xml file to be displayed, you have to change the '''''File of type''''' ComboBox to have '''''Any File'''''. 1. Change '''''Update''''' option to ''yes'' 1. Click the '''''Bundles''''' tab {{attachment:pax2.png}} 1. __None of the files should be selected in the bundle list__ 1. Switch '''''Framework''''' to Felix 1.8.1 (or newer) 1. '''''Apply''''' and '''''Debug''''' 1. 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). 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]. * If you want to use Equinox console, please read its documents. Commands are very similar. * '''''help''''' - display help message {{{ -> help bundlelevel ... | - set or get bundle start level. cd [] - change or display base URL. headers [ ...] - display bundle header properties. help - display impl commands. install [ ...] - install bundle(s). packages [ ...] - list exported packages. ps [-l | -s | -u] - list installed bundles. refresh [ ...] - refresh packages. resolve [ ...] - attempt to resolve the specified bundles. services [-u] [-a] [ ...] - list registered or used services. shutdown - shutdown framework. start [ ...] - start bundle(s). startlevel [] - get or set framework start level. stop [ ...] - stop bundle(s). uninstall [ ...] - uninstall bundle(s). update [] - update bundle. version - display version of framework. }}} * '''''ps''''' - List loaded bundles {{{ -> ps START LEVEL 4 ID State Level Name [ 0] [Starting ] [ 0] System Bundle (1.0.4) [ 1] [Active ] [ 4] cytoscape.util.intr [cytoscape] (1.0.0.SNAPSHOT) [ 2] [Active ] [ 4] cytoscape.graph.fixed [cytoscape] (1.0.0.SNAPSHOT) [ 3] [Active ] [ 4] cytoscape.graph.dynamic [cytoscape] (1.0.0.SNAPSHOT) [ 4] [Active ] [ 4] org.cytoscape.network [org.cytoscape] (1.0.0.SNAPSHOT) [ 5] [Active ] [ 4] cytoscape.render.immed [cytoscape] (1.0.0.SNAPSHOT) [ 6] [Active ] [ 4] cytoscape.geom.spacial [cytoscape] (1.0.0.SNAPSHOT) [ 7] [Active ] [ 4] cytoscape.render.stateful [cytoscape] (1.0.0.SNAPSHOT) [ 8] [Active ] [ 4] cytoscape.geom.rtree [cytoscape] (1.0.0.SNAPSHOT) [ 9] [Active ] [ 4] cytoscape.render.export [cytoscape] (1.0.0.SNAPSHOT) [ 10] [Active ] [ 4] org.cytoscape.attributes (1.0.0.SNAPSHOT) [ 11] [Active ] [ 4] org.cytoscape.tunable (1.0.0.SNAPSHOT) [ 12] [Active ] [ 4] cytoscape.task [cytoscape] (1.0.0.SNAPSHOT) [ 13] [Active ] [ 4] phoebe.dnd [phoebe] (1.0.0.SNAPSHOT) [ 14] [Active ] [ 4] undo (1.0.0.SNAPSHOT) [ 15] [Active ] [ 4] org.cytoscape.view (1.0.0.SNAPSHOT) [ 16] [Active ] [ 4] org.apache.commons.cli [org.apache] (1.0.0.SNAPSHOT) [ 17] [Active ] [ 4] Apache Commons Lang (2.4.0) [ 18] [Active ] [ 4] org.cytoscape.layout (1.0.0.SNAPSHOT) [ 19] [Active ] [ 4] org.cytoscape.vizmap (1.0.0.SNAPSHOT) [ 20] [Starting ] [ 4] cytoscape.application [cytoscape] (1.0.0.SNAPSHOT) [ 21] [Resolved ] [ 4] JDOM DOM Processor (1.0.0) [ 22] [Resolved ] [ 4] Java Activation API (1.1.0) [ 23] [Installed ] [ 4] Concurrent (1.3.4) [ 24] [Resolved ] [ 4] Lowagie iText (2.0.8) [ 25] [Installed ] [ 4] csplugins.automatic.layout [csplugins] (1.0.0.SNAPSHOT) . . . }}} * '''''services''''' - show list of available ''OSGi Services'' * '''''services BUNDLE_ID''''' - show detail of services abailable from the bundle {{{ -> services 25 csplugins.automatic.layout [csplugins] (25) provides: ----------------------------------------------------- name = force-directed objectClass = org.cytoscape.layout.CyLayoutAlgorithm preferredMenu = Cytoscape Layouts service.id = 21 ---- name = circular objectClass = org.cytoscape.layout.CyLayoutAlgorithm preferredMenu = Cytoscape Layouts service.id = 22 ---- name = hierarchical objectClass = org.cytoscape.layout.CyLayoutAlgorithm preferredMenu = Cytoscape Layouts service.id = 23 ---- . . . }}} * '''''services -u''''' - show usage of services. {{{ -> services -u System Bundle (0) uses: ----------------------- org.osgi.service.startlevel.StartLevel org.cytoscape.layout (18) uses: ------------------------------- org.cytoscape.layout.CyLayoutAlgorithm org.cytoscape.layout.CyLayoutAlgorithm org.cytoscape.layout.CyLayoutAlgorithm org.cytoscape.layout.CyLayoutAlgorithm org.cytoscape.layout.CyLayoutAlgorithm }}} * '''''services -u BUNDLE_ID''''' - show more detail about service usage of the bundle {{{ org.cytoscape.layout (18) uses: ------------------------------- name = force-directed objectClass = org.cytoscape.layout.CyLayoutAlgorithm preferredMenu = Cytoscape Layouts service.id = 21 ---- name = circular objectClass = org.cytoscape.layout.CyLayoutAlgorithm preferredMenu = Cytoscape Layouts service.id = 22 ---- name = hierarchical objectClass = org.cytoscape.layout.CyLayoutAlgorithm preferredMenu = Cytoscape Layouts service.id = 23 ---- . . . }}} 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. == 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: {{attachment:eclipse_core6.png}} * maven clean - clean all classes from target directory. * maven install - build everything under the selected project, create bundles, run tests, and install them to your local Maven repository 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. 1. '''''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. 1. '''''Cannot compile application bundle. Eclipse display some warning messages and cannot complete install goal''''' * Comment out following lines in pom.xml in '''''core''''' directory: {{{ true true }}} We are working on this problem. 1. '''''Eclipse and Cytoscape are frozen after splashscreen is displayed. What happened?''''' * On Windows, somehow Felix shell waits user's key entry after Cytoscape displays splashscreen. To proceed, you need to hit enter key in the console window (see below): {{attachment:ts1.png}} == Appendix == === Install Required Eclipse Plugins One by One === If you have troubles to install Cytoscape IDE, or you want to install newer versions of individual plugins, you can install them manually. {{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 from '''''Help > Software Updates...''''' Click '''''Available Software''''' tab and add this URL by pressing '''''Add Site''''' button: http://subclipse.tigris.org/update_1.6.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. * 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/ ===== Spring IDE ===== Cytoscape desktop application is wired by Spring. Eclipse has a plugin called '''Spring IDE''' which helps you to edit XML files to configure the application. You can install it from: http://dist.springframework.org/release/IDE ---- This document is written by KeiichiroOno If you have any questions, please e-mail me (kono at ucsd dot edu. English or Japanese)