Setting up a development environment in IntelliJ IDEA

Setting up a development environment for OTP used to be a rather irritating process, but things have been greatly simplified recently. The master branch of OTP no longer requires a multi-module Maven build, deployment to a servlet container, Spring-based configuration, or Lombok IDE plugins. This makes it much easier to dive in to the OTP code base than in the past.

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?" Click "yes", and if confronted with any messages about language level changes ask to restart Idea. 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 a project this way you must give IntelliJ more information about how to import 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. You'll also need to specify an SDK for the project, i.e. which Java development environment is to be used for compiling the code. If no JDKs are shown, click the green plus icon and add one by specifying a directory on your machine. Once you have at least one JDK defined, select one in the list and hit next. Approve the project name to finish.

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.