Dev guide: How to setup your development environment for JGraphT

This tutorial explains how to setup your development environment such that you can start contributing to JGraphT. First, follow the General Instructions. Then follow the guidelines for the IDE of your choice.

General Instructions

1. Required software. The following software is required:

   • JDK 11 or later. You can either use Oracle JDK or OpenJDK.
   • Some kind of IDE, e.g. Intellij IDEA, Eclipse, or VS Code. We do not recommend using Netbeans due to its poor interoperability with Maven.
   • Apache Maven 3
   • Git-scm

2. Since JGraphT is hosted on Github, it is essential that you learn the basics of Git version control system. Here's a nice visual tutorial

3. Create a GitHub account, fork jgrapht to your own repository and make a local clone of the forked repository. Don't forget to star the JGraphT repository 😄.

4. Before you start developing, create a new working branch. Keep your master branch clean and in sync with the upstream master of jgrapht; do NOT make modifications to your master branch. You will thank me later for this advice!

5. Follow the instructions for your specific IDE:

   • Eclipse
   • Intellij IDEA
   • Netbeans

---

Developing using Eclipse

These instructions are based on the Neon release of Eclipse.

• From the Workbench File menu, choose Import
• From Maven, select "Existing Maven Projects"
• Browse to jgrapht directory
• The root pom.xml and all subprojects should be automatically selected
• Click the Finish button

For the Java Code Style project settings, be sure to apply our project-specific settings (either globally in your workspace, or to all JGraphT subprojects):

• For Java Code Style, Formatter, import jgrapht/etc/eclipse-formatter-settings.xml
• For Java Code Style, Organize Imports, set number of imports needed for .* to 0 so that imports are always collapsed (please forget those dire warnings your grandmother told you about this being dangerous; it's a myth!)

If you use a different IDE, please use equivalent settings.

When you use the Run As/JUnit Test menu option, by default Eclipse will run all tests. This includes performance tests and long-running integration tests, which usually you don't want during development. Instead, you can either run tests individually, or you can run the predefined suite of all fast-running tests. To do this, under the jgrapht-core project, browse to src/test/java and then expand the org.jgrapht package. Right-click FastTestSuite.java and then execute the Run As/JUnit Test menu option to run the suite. There are also suites defined for performance tests and integration tests.

Developing using IntelliJ IDEA

These instructions are based on the 2016.3 version of IntelliJ IDEA and beyond.

• Select Import Project, or alternatively, select File | New | Project from Existing Sources
• Browse to jgrapht directory
• Select the jgrapht root directory
• In the Import Project dialog,
  • Select Import project from external model and Maven as the external model. Hit Next.
  • In the import options screen keep all options as default. Hit Next.
  • In the profiles dialog screen keep all options unselected. Hit Next.
  • In the next screen select only the org.jgrapht:jgrapht project. Hit Next.
  • Select the project's SDK. You must select at least 1.8. If there is no 1.8 or higher version, you need to install one. See your operating system's documentation. Hit Next.
  • Keep the project name and file location as is. Hit Finish.
• Right click on the jgrapht-io project and run Maven->Generate Sources and Update Folders
• Build project from the Build menu.

See also the help page from JetBrains website.

Formatting Rules: Setup the Java formatting rules and imports style to be similar with the ones we are using in Eclipse. Some points worth considering while importing eclipse formatting rules in IntelliJ:

• For importing etc/eclipse-formatter-settings.xml, you need to go to File -> settings -> Editor -> code style -> Java -> import scheme -> Eclipse XML profile, and here select the etc/eclipse-formatter-settings.xml file.
• While formatting the annotations you will hit this bug and so you should manually set the line wrapping settings for annotations.
  • Go to File -> settings -> Editor -> code style -> Java, now go to the tab Wrapping and Braces and manually set Class annotations and method annotations to Wrap always. (click Apply and then Ok).

Developing using Netbeans

These instructions are based on the 8.1 version of Netbeans.

• From the File menu, choose Open Project
• Browse to jgrapht directory
• Select the jgrapht root directory
• Click the Open Project button

Setup the Java formatting rules and imports style to be similar with the ones we are using in Eclipse.