Table of Contents

  1. Getting started with PathVisio Development
    1. Getting Involved
      1. Obtaining the source code
      2. Where do I add new features? How do I submit it?
    2. Tips on getting started
      1. Q: How do I get a grip on the PathVisio code base?
      2. Q: Where can I ask questions about PathVisio development?
      3. Q: How do I submit a patch?
      4. Q: How to compile PathVisio from the command line on Windows?
      5. Q: How do I compile PathVisio in the eclipse development environment?
    3. Modular structure of PathVisio
      1. Q: Can someone tell me the rationale behind the package structure for …
      2. Troubleshooting Compilation
    4. Coding Style
    5. Additional resources
  2. Gpml Pathway Format
    1. Overview
    2. Naming
    3. Structure of a GPML file
      1. Overview
      2. Root level: Pathway
      3. First level: Pathway Elements
        1. DataNode
        2. Line
        3. Label
        4. Link
        5. Shape
        6. Group
        7. Infobox
        8. Legend
        9. Biopax
      4. Shared attributes and minor elements
        1. Graphics
        2. Comment
        3. GroupIds
        4. GraphRefs/GraphIds
        5. Biopaxref
    4. Schema and Validation
    5. Versioning
    6. History
    7. Future
  3. Code Examples

Getting started with PathVisio Development

Getting Involved

We're always interested in outside help. We're doing our best to have an open development process, to make it as easy as possible for outsiders to contribute.

It can be daunting to learn a the ins and outs of a large codebase all at once. To help you, we tag bugs that are easy to fix for newcomers with the lowhangingfruit tag, see  http://www.bigcat.unimaas.nl/tracprojects/pathvisio/report/10. These are small tasks for which it should be easy to dive right in and get started with the code base.

  • For developers we organize a biweekly phone conference meeting.
  • Take a look at the  roadmap.
  • The daily builds of PathVisio is available here:  PathVisio 2

Obtaining the source code

The source code is available free of hassle through anonymous subversion access. You can now browse or download the source code from our subversion repository:  http://svn.bigcat.unimaas.nl/pathvisio.

Where do I add new features? How do I submit it?

Your change may fall into one of these categories:

  • bug fixes or small tweaks to the core of PathVisio. Submit them as a patch, and we'll apply them to the trunk within a few days, and it will end up in the release version within a month.
  • the same goes for changes that affect GPML.xsd, but we'll save these up and release on a longer cycle, once or twice per year.
  • big features should go in a plugin. We'd like to keep the core of PathVisio as small as possible, but plugins have infinite space for new features. See also PluginDevelopment. If you need an event, hook or callback that doesn't currently exist to make your plugin work, we'll add it.

Tips on getting started

Here I'm collecting tips to help you get started with PathVisio Development.

Q: How do I get a grip on the PathVisio code base?

It can be hard for a newcomer to get an overview of the PathViso internals. I think the best way is to get started by trying to making some small changes. Try e.g. some of the following (consider it homework)

  • can you add your name to the about dialog?
  • can you make it so that datanodes are drawn as e.g. a rounded rectangle instead of a rectangle?
  • can you draw a fine 2D grid in the background of the Pathway being edited?
  • can you create a pathway exporter that is the same as gpml, but uses a different file extension (e.g. ".abc")
  • can you add a tab to the pathway element dialog (the one that appears after double-clicking) to set the line / arrow style (in addition to comments and literature), so that you don't have to use the side-pane for that

No doubt just trying to do this will lead to numerous questions. But those will not be overly broad questions, but focused questions that are much easier to answer.

Q: Where can I ask questions about PathVisio development?

You can ask development related questions on the wikipathways-discuss mailinglist here:  http://groups.google.com/group/wikipathways-discuss

Q: How do I submit a patch?

You can email your patches to our discussion mailinglist. Make sure your patch is as small as necessary, doesn't contain spurious changes (such as changes to whitespace formatting etc, that will just make it difficult to review the code), and contains only one functional change at a time. If you wish to make multiple changes, split your patch up and submit them separately.

Q: How to compile PathVisio from the command line on Windows?

  • You need the following tools: TortoiseSVN, Java SE Development Kit (JDK) version 5 or higher, Apache ant
  • Install TortoiseSVN: You can get it at  http://tortoisesvn.tigris.org/
  • Install Java JDK
  • Install Apache ant ( http://ant.apache.org/)
    • You can get it here:  http://ant.apache.org/
    • Download the binary distribution zip file (e.g. apache-ant-1.7.1-bin.zip).
    • Unzip it to a folder, e.g. C:\Program Files\ant
    • add the folder containing ant.bat to your PATH. You can modify the PATH by opening the System dialog (Windows key + Break), click on the "Advanced" tab and then on the "Environment variables" button. Create the "PATH" environment variable if it doesn't already exist. Set the PATH variable to the folder containing bat.
    • In the same environment variables dialog, you also have to set JAVA_HOME to point to the JDK you just installed (e.g. C:\Documents and Settings\Java\java_1.6_jdk). If you don't do this correctly, ant will later complain that it can't find tools.jar
  • Now check out the source code.
  • Compile the source code: Open the command terminal (Windows key + R, and type cmd<ENTER>). Use "cd <dirname>" to navigate to the directory where you downloaded the PathVisio source code. Type "ant" in the directory that contains build.xml. PathVisio will now be compiled.
  • Run PathVisio. If all went according to plan, you should now be able to start pathvisio by double-clicking or typing pathvisio.bat.

Q: How do I compile PathVisio in the eclipse development environment?

Step 1. Download and install the  eclipse IDE if you haven't done so yet.

Step 2. Install the subclipse plugin. To do this:

  • Go to Help->Software->Find and Install.
  • Search for new features to install.
  • Add  http://subclipse.tigris.org/update_1.0.x as a new remote site (click finish).
  • You should see the subclipse plugin in your window, check it and click next.

Step 3. Start a new project of type "Checkout Projects from SVN". (File->New->Project)

In the following wizard steps, you have to create a new repository at location " http://svn.bigcat.unimaas.nl/pathvisio". Select the trunk directory (unless you are interested in a particular branch, in that case, select the branch you want). Check out the project configured using the New Project Wizard (See next step).

Step 4. In the New Project wizard, select a project of type "Java Project".

Choose any project name. Make sure you set the JDK Compliance to 5.0 (or higher).

Finish the wizard right away, we'll set the remaining project options after the initial checkout.

Step 5. Go to the menu Window->Show View->Ant and drag the file "build.xml" to this view. select resources-jar and run it (the green play button).

Refresh the file list in the Package explorer by selecting the project name and pressing F5.

Step 6. Go to the menu Project->Properties. Select "java build path" on the right.

6a. On the Source tab, remove the default for source folders. Instead, add the src/core, src/gui and src/swing folders.

6b. In the libraries tab, click "Add JARs..", and select all jar files in the lib directory and all subdirectories of the lib directory (i.e. lib/apache/*.jar, lib/batik/*.jar, lib/paxtools/*.jar).

You should now be able to build the project without getting errors.

Step 7. Create a run configuration in the menu Run->Run... Set the project to the one you just created and set the main class to org.pathvisio.gui.swing.GuiMain.

Modular structure of PathVisio

Q: Can someone tell me the rationale behind the package structure for PathVisio? What goes in core vs. gui vs. swing?

Basically the code is split up in a few modules. Parts of the code base are shared by the WikiPathways? applet and the PathVisio application.

  • "core" is the non-gui backend, these classes can be used without a main frame
  • "gui" is the gui part that is shared by the PathVisio app and the WikiPathways? applet
  • "swing" are specific to the PathVisio app, it is not used by the WikiPathways? applet. It includes the code for expression data import, visualization, and the plugin interface
  • "wikipathways" are classes specific to the WikiPathways? applet, it is not needed for the PathVisio program. It includes code to check login status and download / upload a pathway.
  • "wikipathways-client" contains utility classes for bots and scripts that interact with the wikipathways webservice. It is not needed for the PathVisio app.

And the dependencies are like this:

  • gui depends on core
  • swing depends on gui and core
  • wikipathways depends on gui and core
  • wikipathways-client is independent

See also this dependency graph:

Troubleshooting Compilation

  • If you get errors like 
     "The declared package "org.pathvisio.data" does not match the expected package "core.org.pathvisio.data"
    You've selected the wrong source folders in step 6a.
  • You can safely ignore the following error: 
     [exec] Execute failed: java.io.IOException: Cannot run program "svnversion".
    PathVisio uses the program svnversion to obtain the current revision of the project and include it in the about dialog, but this is non-critical.
  • If you are missing the file Revision.java, make sure you run the the ant "resources-jar" target or "prepare" target (see step 5). The file Revision.java is automatically generated. Don't forget to refresh the project in eclipse (press F5) after you ran ant.
  • If you see errors like this: 
     Error: Couldn't load resource 'icons/undo.gif'"
    This means you're missing resources.jar from your classpath. Resources.jar is also automatically generated. Make sure you've run the ant "resources-jar" target, pressed F5 to refresh the project explorer and included resources.jar in the project.

Coding Style

See CodingStyle

Additional resources

Attachments