Cytoscape Consortium ORG

@cytoscape ·United States of America ·www.cytoscape.org

165 repos
251 followers
0 following

JavaScript 40%
Java 35%
HTML 6%
Python 4%
TypeScript 3%

This is the primary Maven project for building the Cytoscape Desktop application. To report bugs in this or other Cytoscape Desktop sub-projects, please use the bug report form here. Cytoscape…

This is the primary Maven project for building the Cytoscape Desktop application.

To report bugs in this or other Cytoscape Desktop sub-projects, please use the bug report form here.

Cytoscape Core: Building Guide

![](https://avatars1.githubusercontent.com/u/956141?v=3&s=200)

Status:

4/2023 - Updated for 3.10.0 release
3/2025 - Updated for 3.10.3 release

Introduction

Cytoscape is a fairly complex application and its core distribution has multiple repositories for managing its code. This repository contains top-level pom file and utility script for building Cytoscape core distribution. Most App developers won't need to clone this repository. Keep reading below to learn about how to work with Cytoscape's source code.

Target Audience

This document is a guide for developers who want to build the entire Cytoscape core distribution from scratch. If you are interested in building Cytoscape apps, you don't need to build Cytoscape from source. You can follow the guide here to learn more about Cytoscape app development:

Cytoscape Developer Documents

Requirements

You need the following tools to build latest development version of Cytoscape 3.10:

Computer with Windows, Mac, or Linux
JDK 17
Maven 3
Git
_cy.sh_ - Utility script for building Cytoscape core distribution (available in this repository).

While you can use any IDE to maintain Cytoscape 3, a popular IDE for this is Eclipse, which has its own Maven and Git support, too. However, for the initial repository clones and builds, we recommend that you follow the command line-based procedure below, and then switch to whichever IDE you prefer.

Related repositories

All build scripts are moved to the following repository:

Cytoscape Admin Scripts

Services

Note that some Cytoscape functions rely on code deployed as services available on web servers. Generally, such services are callable by Cytoscape or directly by non-Cytoscape clients (e.g., Python) in the larger bioinformatics community. Some services are provided by other organizations (e.g., PSICQUIC for importing public networks), while others are provided by Cytoscape developers (e.g., Diffusion) and are located in or rely on other GitHub repositories. Here is a list of known external repositories containing services called by Cytoscape and maintained by Cytoscape core developers:

CXMate - adapters that simplify service writing
Diffusion - called by Diffusion core app

Each repo contains information on how to build and deploy the service.

Cytoscape 3 Core Directory Structure

Cytoscape source code is maintained in several GitHub repositories, and is organized into a main project and several sub-projects.

The Core

── cytoscape
   ├── README.md
   ├── api
   ├── app-developer
   ├── cy.sh
   ├── gui-distribution
   ├── impl
   ├── parent
   ├── pom.xml
   └── support

parent - Contains several shared variables for building Cytoscape sub projects
api - Public API bundles
impl - Implementation bundles
support - Misc. bundles for building core
gui-distribution - Actual distribution created from core projects and core apps
app-developer - API JAR file for app developers

Instead of cloning each sub-project's repository one-by-one, you can use the utility script in the Cytoscape repository to initialize your workspace all at once (see below).

Building Development Version of Cytoscape 3

Here is the step-by-step guide to build a development version of Cytoscape.

tl;dr

git clone https://github.com/cytoscape/cytoscape.git
cd cytoscape
./cy.sh init
cd cytoscape
mvn -fae install -U -Dmaven.test.skip=true
./gui-distribution/assembly/target/cytoscape/cytoscape.sh


Eclipse Users - Eclipse Import Instructions
*NOTE: For first-time and new release builds, the build order matters and you may see an error involving event-api. The solution is to first build api/event-api, then build api, then build the entire package. Oh, and you can't skip tests for your first build; some poms depend on test outputs.*
*ANOTHER NOTE: If you see errors about "Could not transfer artifact" and "Blocked mirror for repositories," then you may be running a newer version of Maven that doesn't work for our repo at this time. Try Maven v3.6.0*
Branch Management
Cytoscape Core
For the core projects, development version always uses the branch named develop.  Master branch is only for the final release.  If you want to build the latest development version of Cytoscape, you should use develop branch for all sub-projects.
Core Apps branch management
Since core apps have their own release cycles, they have different branching scheme.  Usually, features are developed in feature branches, and there is only one common branch called master.  Head of the master branch is always the latest development version of the core app.
Step 1: Clone the Main Project
1. Install required tools: JDK, Maven, and Git. On some systems, these may be preinstalled - you can use those versions if they are relatively recent. Released versions of Cytoscape use
JDKs from Eclipse Adoptium.
2. Add JDK, Maven, and Git to your system PATH if necessary. On some platforms, this is done automatically on installation - try running mvn, git, or java at a command line to check this.
If you need to add tools to the PATH, the steps you should follow vary by operating system. On Windows, this can be done in the Environment Variables dialog - open the file browser, right click on "Computer" or "This PC", select "Advanced system settings", then click "Environment Variables" - you should be able to edit the the PATH by selecting the PATH environment variable and clicking Edit. On Mac or Linux, you would need to edit the .profile, .bashrc or .zshrc file in your home directory to set environment variables, depending on the type of shell you are using. It may be helpful to add the following to .profile and set the PATH in .bashrc so that all shells will read the same values:
if [ -f ~/.bashrc ]; then
   source ~/.bashrc
 fi
Then, in .bashrc, add something like the following:
export PATH=/path/to/java/bin:/path/to/maven/bin:/path/to/git/bin:$PATH
Use the directories where binaries are located, as this will ensure that the command line knows where to find them.
3. Set the JAVA_HOME environment variable to the JDK 17 installation directory. This is only necessary if you have multiple versions of Java installed - if JDK 17 is the only one, Cytoscape will be able to automatically find it without the need for an environment variable. To do this, follow the same instructions as above, but for JAVA_HOME instead of PATH. On Windows, you may have to click the "Add..." button under System Variables if JAVA_HOME does not already exist. On Mac/Linux, you would add an additional line to .bashrc (or .profile if you set environment variables there) like the following.
export JAVA_HOME=/path/to/java
On Mac, you can use /usr/libexec/java_home -V to show the paths of all installed JVMs.

4. MAVEN_HOME, and M2_HOME to your environment variables. On some platforms, this is done automatically on installation. These are environment variables that can be set using the same methods as JAVA_HOME and PATH, and should point to the Maven installation directory (example: /path/to/Maven/apache-maven-3.6.3. Use the relevant echo command to test these (example: echo $MAVEN_HOME for Ubuntu/Mac or echo %MAVEN_HOME% on Windows).


5. If you are using Git for the first time, you need to set your name and e-mail address. To do this, use the following commands:
 git config user.name &quot;Your Name&quot;
 git config user.email [email protected]
 Substitute your actual name and e-mail address in the commands.
6. Generate an ssh key and set it up on GitHub. To do this, you will first need to be added to the Cytoscape GitHub project by one of the core developers. Then, click the arrow in the top-right hand corner of any GitHub page and choose "Settings". Click "SSH and GPG keys", then follow the instructions on the linked guide to generate an SSH key on your particular operating system. Once you have generated an SSH key, return to the original "SSH and GPG keys" page and add the generated key using "New SSH key".
7. Clone this repository: git clone https://github.com/cytoscape/cytoscape.git
    - Now you can see a new directory named cytoscape:
cytoscape     &lt;-- parent level directory
├── README.md
├── cy.sh
└── pom.xml
Shortcut
If you want to skip the following steps, you can use this command to clone and build all core projects and core apps:
./cy.sh init-all
Once finished, you can skip to Step 4.
Step 2: Clone the Sub Projects
1. _cd_ to the cloned main project directory: cd ./cytoscape
1. Execute the following command:
    - Create new folder under current working directory: ./cy.sh init
1. Now you can see a new subdirectory (also) named cytoscape, which contains the sub projects:
cytoscape     &lt;-- parent level directory
├── README.md
├── cy.sh
├── cytoscape     &lt;-- subproject directory
│   ├── README.md
│   ├── api
│   ├── app-developer
│   ├── cy.sh
│   ├── gui-distribution
│   ├── impl
│   ├── parent
│   ├── pom.xml
│   └── support
└── pom.xml
Step 3: Building Cytoscape
1. Go into the cytoscape subproject directory cd ./cytoscape
1. Run Maven: mvn clean install -U
    - Option: use mvn -fae clean install -U (... see below)
1. Have a coffee break...  It depends on your machine specification and internet connection speed, but will take 3-60 minutes.  When you build Cytoscape for the first time, it will take a long time because maven downloads all dependencies from the remote server.
Step 4: Run the new build
Now you are ready to run the new
1. cd gui-distribution/assembly/target/cytoscape
1. Run development version of Cytoscape:
   - Mac/Linux: ./cytoscape.sh
   - Windows: ./cytoscape.bat

The option -faeis short for "fail at end", which allows the build to continue even if unit tests fail. (Current unit tests do fail during the first few compiles, but eventually pass.) When Maven is done, you can find the application ingui-distribution/assembly/target/cytoscape`.

Note that if you want to test the new build with a clean slate, we recommend to remove the entire

~/CytoscapeConfiguration

directory.

Step 5: Continue with Eclipse project steps

If you are developing in Eclipse, continue to set up with these steps. You can also configure Eclipse to debug Cytoscape.

----

New from 3.10.0: Core Apps

___Core Apps___ are Cytoscape Apps that are included with the Cytoscape distribution. They are located in their own separate GitHub repositories. Cytoscape depends on the latest version of each core app deployed to the Nexus repository, so you don't need to build core apps to build Cytoscape core.

As of Cytoscape 3.10.0 (March 2023), Cytoscape core distribution comes with the following core apps:

https://github.com/cytoscape/cytoscape-gui-distribution/blob/develop/assembly/pom.xml#L447

Optional Projects

This repository contains sample code for app developers and it will not be included in the core distribution. You don't have to build this repository if you just want to build the Cytoscape Core distribution.

samples

----

Building Core Apps

All of the core apps are maintained in their own repository and if you want to try the latest version of the core app, you need to build them separately.

Step 1: Checking out core apps

Assuming you are in the subproject directory of Cytoscape project (not the parent level), then

./cy.sh apps

will check out every core app into the

apps

subdirectory. Each is hosted in its own GitHub repository, and changes can be committed directly to each directory. All of the core apps are hosted under this org account:

Cytoscape Consortium GitHub Repository

Step 2: Building Core Apps

All of core apps are independent to each other and there is no dependency among those. To build the apps, you can just _cd_ to the app's directory and run:

mvn clean install -U

to build the latest version. You can also use the following command from top-level directory to build all core apps:

./cy.sh build-apps

This command simply runs

mvn clean install

for each core app directory.

Step 3: Install the new build

To test changes, install the JAR from the Cytoscape menu at Apps > App Store > Install Apps from File, or copy to the

~/CytoscapeConfiguration/3/apps/installed

directory.

----

Adding a new Core App

If you need to add an new core apps, you need to follow these steps:

Step 1: Update directory structure

All of the Cytoscape core apps should respect the following conventions for consistency. 1. Organize the directory - The top level directory should contain only the minimal set of files.

.
├── .gitignore
├── README.md
├── pom.xml
└── src
          ├── main
          └── test

- Create proper _.gitignore_ file - Add _README.md_ to briefly describe the app - Make sure _src_ contains only main and test sub directories 1. Use standard group and package name - _org.cytoscape_ should be used as the group ID - Package name also needs to be updated to follow the standard, like:

org.cytoscape.YOUR_APP_NAME

Step 2: Update pom.xml

1. Use standard name and ID

org.cytoscape
	  my-app
	  3.5.0
	  bundle
	  My APP

1. Add all required plugin instructions - The core app should work as an independent repository. This means you should not depends on any parent pom file. - All instructions, including compiler arguments and parameters for BND plugin should be provided - Make sure you have proper information for the following sections: - repositories ( You can just copy these from an existing pom, like CyREST: https://github.com/cytoscape/cyREST/blob/3e1ef7fcf867dbcd80749618c4134173e02688e9/pom.xml#L35) - distributionManagement ( You can just copy these from an existing pom, like CyREST: https://github.com/cytoscape/cyREST/blob/3e1ef7fcf867dbcd80749618c4134173e02688e9/pom.xml#L35) - scm - build 1. Update version number - Use standard versioning convention. For example, if your app is introduced for Cytoscape 3.5.0, set your app's version to 3.5.0. DO NOT USE _-SNAPSHOT_ SUFFIX.

Step 3: Add proper set of unit tests

If you don't have test suite, you should add it. This is important to detect errors caused by future changes.

Step 4: Test the new build locally

Once you finish all of the changes above, build it locally. If everything looks OK, install it to Cytoscape and test the app.

Step 5: Move your repository to the Cytoscape org account

Mov

…

All public repos (165)

Show forks Show archived