Setting up a development environment in IntelliJ IDEA

The IDEA IDE

At the suggestion of Joost at Go About I decided to give IntelliJ IDEA IDE a try recently, and I haven't looked back. It is a commercial product which has a "community edition" and supports open source by providing licenses for their flagship product gratis to FOSS projects. My impression is that it is more responsive and less crash-prone than Eclipse, which I found to be hindered by an overly complex "Marketplace" extension discovery mechanism and frequently mismatched or conflicting plugin versions. Superficially, the IDEA interface also tends toward compact, crisp text and layout which I prefer. On the other hand, Eclipse does an excellent job of executing Java projects that are full of compile errors and following through with the entire build even when errors exist. It took me a while to get used to fixing every last glitch in IDEA before I could try out some experimental code. Apparently IDEA does allow using the more tolerant Eclipse compiler but I never got this combination working properly.

Install Idea

If you don't already have it, grab the "ultimate edition" of IDEA from http://www.jetbrains.com/idea/download/. JetBrains has given the OpenTripPlanner project a license to use its flagship product as a way of supporting the open source community. Extract the IntelliJ distribution somewhere convenient (e.g. under your home directory), and run bin/idea.sh to start the IDE. You can choose to evaluate IDEA for 30 days or enter the license code immediately (contact Andrew from the mailing list to request a license code). You can always decide to evaluate first and enter the code later. You should then be presented with a series of step-by-step configuration dialog boxes where you can enable or disable plugins. The less plugins you have activated, the more resource-efficient IDEA will be. The following steps will give you a very minimal IDEA setup that is sufficient for working on OTP. You can always enable more plugins later if you need them.

1. Uncheck all the version control plugins except Git unless you expect to use one of the other version control systems such as Subversion, CVS, or Hg.
2. Disable all the Web/EE plugins unless you want to deploy OTP to a Java application server from within IDEA. This would only be useful for people who have a strong preference or requirement for deploying to Java application servers and know what they're doing. I've avoided doing this recently, and don't recommend it when beginning to work with OTP. In any case it isn't implemented yet in the master branch.
3. Disable all the HTML/JS plugins except maybe CSS, HTML Tools, JavaScript, and W3C Validators if you plan to work on the front end.
4. Disable all "Other plugins" except GitHub, JUnit, Maven (our build system), and Properties. Additionally you might get some use out of Gradle (being evaluated as our future build system), Structural Search, the REST client.

Clone the OTP repository from GitHub

IDEA allows you to check out Git repositories from GitHub via its GUI: "Check out from version control" in the "Welcome to IntelliJ IDEA" dialog. You can choose either the Git plugin (which will accept an arbitrary URL for a Git repository) or the GitHub plugin (which will log in to your GitHub account and fetch a list of projects you work on). You'll need to create a directory to serve as a root for your checked out source trees, e.g. IdeaProjects under your home directory, or simply git. If you choose the plain Git plugin, enter the HTTPS clone URL from the right sidebar on the OTP Github page, which should be https://github.com/opentripplanner/OpenTripPlanner.git. When the repo is successfully cloned, you should see the message "You have checked out an IntelliJ IDEA project file: .../OpenTripPlanner/pom.xml. Would you like to open it?" This file pom.xml is the Maven Project Object Model, and this means that IDEA has recognized OTP as a Maven project and will configure it as such. Click "yes", and approve an IDE restart if confronted with any messages about language level changes. After dismissing the "tip of the day" you will be presented with a nearly blank screen. Clicking the small box icon in the lower left of the Idea window will allow you to open the Project pane and browse through the OTP directory hierarchy.

Alternatively, if you prefer to use command-line Git tools you can manually clone the OTP repository into a directory of your choice using the command git clone https://github.com/opentripplanner/OpenTripPlanner.git, then import the project into IDEA using the "Import project" dialog available under the File menu or the "Welcome to IntelliJ IDEA" dialog. In my experience, when importing an existing project this way you must give IntelliJ more information about it. Tell it to "Import project from external model (Maven)", and check "Import maven projects automatically" as well as "Automatically download sources and documentation" in the following dialog box. A dialog will ask you to "select Maven projects to import". There should be only one, so you can move on to the next step where you'll need to specify an SDK for the project, i.e. which Java development kit is to be used for compiling the code. If no JDKs are shown, click the green plus icon and add one or more by specifying a directory on your machine (usually under /usr/lib/jvm). Once you have at least one JDK defined, select it in the list and hit next. Approve the project name and click "finish".

Running OTP

As in other IDEs, you need to set up "run configurations" to start up a Java program. By default these are available in the Run -> Edit configurations dialog, which is also available in the dropdown menu just to the right of the Make Project button (the downward green arrow with some ones and zeros in the top right of the IDEA window). Click the green plus sign to add a new Application configuration. You'll probably want at least two configurations to start: one to build a graph and one to start a server. In both cases your main class will be org.opentripplanner.standalone.OTPMain, and you may want to specify VM options to increase the JVM heap size (e.g. -Xmx4G to increase the limit to 4GB). Only the "Program arguments" will be different for building and serving a graph (see "Standalone Graph Build" [article to be completed]).

Once run configurations are defined, you can select them in the dropdown menu and launch them in either normal or debug mode using the right-facing triangular "play" button or the bug icon next to it, respectively.

Debugging

Running and debugging are done in separate dockable windows in IDEA. Watch out you can easily start an OTP server in debug mode while another is still active in the plain "Run" window, eating up a lot of memory. Once you have OTP running in debug mode, unlike in Eclipse you will need to tell IDEA to hot-swap any changed classes into the running JVM. This is done using Run -> Reload changed classes or via the Make Project button (a downward green arrow with some binary code next to it) or key binding (usually Ctrl-F9).

Working on older versions of OTP

Note that older versions of OTP (the 0.11.x and 0.10.x branches) require significantly more plugins and configuration than the master branch. We encourage you to carry out development on the current master branch since we don't always have time to rebase bugfixes and patches between versions, and master will become our next relase. If for some reason you need to work with an older version, you will need to install a Lombok IDE plugin, import a multi-module Maven project, and possibly build OTP into a WAR package that is deployed to a Java application server.