GettingStartedMaven

Prologue: Windows

If you're using Windows, you'll need some additional tools. We have heard recommendations for "Git for Windows", which includes both git (needed to download OTP) and bash (a better shell than the built-in Windows shell):

http://code.google.com/p/msysgit/downloads/list?q=label:Featured

(you want the one labeled Git-[version number]-preview-[numbers].exe)

Setting Up Maven

Maven is a command-line tool for building Java projects. Start by making sure you are using a recent version Maven, which you can find at http://maven.apache.org/ Use version 3.x if at all possible, since OTP is a multi-module project and pre-3.x versions of Maven seem to have problems with multi-module builds. Run mvn --version to see which version of Maven you have installed.

Quick Start

If you'd like to build the trip planner locally without using Eclipse, run the following:

git clone git://github.com/openplans/OpenTripPlanner.git
cd OpenTripPlanner
mvn clean package -DskipTests

This command will download all the dependencies for OTP, compile all the modules, and assemble the compiled software into JAR and WAR packages. If this succeeds, you should see the following output

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] OpenTripPlanner ................................... SUCCESS [0.154s]
[INFO] OpenTripPlanner Open Street Map Support ........... SUCCESS [1.822s]
[INFO] OpenTripPlanner Administration Webapp ............. SUCCESS [1.931s]
[INFO] OpenTripPlanner Utilities ......................... SUCCESS [2.000s]
[INFO] OpenTripPlanner Routing ........................... SUCCESS [5.769s]
[INFO] OpenTripPlanner Graph Builder ..................... SUCCESS [15.697s]
[INFO] OpenTripPlanner System Map ........................ SUCCESS [4.185s]
[INFO] OpenTripPlanner Updater ........................... SUCCESS [11.544s]
[INFO] OpenTripPlanner Thrift API Server ................. SUCCESS [16.785s]
[INFO] OpenTripPlanner Analyst ........................... SUCCESS [6.208s]
[INFO] OpenTripPlanner Web Utils ......................... SUCCESS [0.394s]
[INFO] OpenTripPlanner API Webapp ........................ SUCCESS [6.305s]
[INFO] OpenTripPlanner Geocoder .......................... SUCCESS [1.452s]
[INFO] OpenTripPlanner Graph Visualizer .................. SUCCESS [16.063s]
[INFO] OpenTripPlanner Main Client ....................... SUCCESS [2.926s]
[INFO] OpenTripPlanner Integration Testing ............... SUCCESS [0.549s]
[INFO] OpenTripPlanner Analyst Client .................... SUCCESS [0.553s]
[INFO] OpenTripPlanner Leaflet Client .................... SUCCESS [0.692s]
[INFO] OpenTripPlanner Municipal Boundary Reverse Geocoder  SUCCESS [1.733s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Note: The integration tests are being revised, so the mvn install integration-test -DskipTests -Pinteractive method for running a test server no longer applies. We will post new instructions once the new system is in place.

Project Structure

The OpenTripPlanner project uses a Maven aggregator/multi-module layout (http://maven.apache.org/pom.html#Aggregation) to organize the various components of the system. Taking a look at the project directory structure, you will see the following directories and files.

opentripplanner-routing/pom.xml
opentripplanner-routing/...
opentripplanner-api-webapp/pom.xml
opentripplanner-api-webapp/...
opentripplanner-webapp/pom.xml
opentripplanner-webapp/...
pom.xml
README

Maven looks for pom.xml files to define project settings. The root pom.xml defines the parent opentripplanner project and references individual project modules, including opentripplanner-routing, opentripplanner-api-webapp, opentripplanner-webapp, and potentially other modules as the project grows in size and complexity.

Compiling the Code

You can compile all the code with the following command from the project root:

mvn compile

Running the Unit Tests

To run all the unit tests, run the following command from the project root:

mvn test

Packaging the Code

To build jars, wars, and other packaged build artifacts, run the following command from the project root:

mvn package

Skipping Tests

If you want to temporarily disable unit tests, add the following to your Maven command line:

-DskipTests

Running Specific Tests

If you want to run only a specific unit test, add the following to your Maven command line:

-Dtest=TestIWantToRun

Tips and Tricks for Working with Multiple Modules

Most maven commands, such as compile, test, package, and install will run on the entire project tree, including all sub-modules. This can be tedious when you are working with just one specific module. However, if you change into the directory of one of the specific modules and execute a Maven command (for example, mvn package), you will **often get complaints from Maven that it can't find dependencies for other modules within the project. **

The _solution _is the Maven Reactor plugin, which is built in to Maven and is designed to allow working with just a subset of Maven modules.

For example, if we wanted to package the opentripplanner-api-webapp war, along with all its dependencies, we could execute:

mvn reactor:make -Dmake.folders=opentripplanner-api-webapp/ -Dmake.goals=clean,package,-DskipTests=true

To walk through what's going on, we are running a Reactor build ("reactor:make"), targeting the opentripplanner-api-webapp module (-Dmake.folders=opentripplanner-api-webapp/). We want to execute the following goals: clean and package, while skipping tests (-Dmake.goals=clean,package,-DskipTests=true).