GettingStartedMaven - mattwigway/OpenTripPlanner GitHub Wiki

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/

Quick Start

If you'd like to build, deploy, and try out the trip planner locally without using Eclipse or reading lots of documentation, run the following:

git clone git://github.com/openplans/OpenTripPlanner.git

cd opentripplanner

mvn integration-test -DskipTests -P interactive

If this succeeds, you should see the following output

...

INFO {execution: tomcat-execution}

INFO Press Ctrl-C to stop the container...

You should now be able to browse to http://localhost:8080/opentripplanner-webapp and plan trips in Portland. Note that since there is no geocoder provided with the project, the easiest way to specify starting and ending locations is to right (or control) click on the map and choose either "Start a trip here" or "End a trip here." Note also that the first trip you plan may take 10 to 15 seconds to complete because some additional information is loaded on the initial request. Subsequent requests should be considerably faster.

What does running mvn integration-test -DskipTests do, exactly?

First, it compiles the opentripplanner-routing, opentripplanner-api-webapp, opentripplanner-graph-builder, and opentripplanner-webapp modules.
Next, the -DskipTests flag tells Maven not to run the standard suite of unit tests (using this flag is by no means necessary -- it just saves some time).
The -P interactive tell the interaction test to run in interactive mode, which means that Maven will pause after everything starts up so you can interact with it.
It then compiles a Graph.obj file using the opentripplanner-graph-builder module. opentripplanner-graph-builder is a command-line application that is run with a single argument, the path to a graph configuration XML file. By default, the integration test looks for the file opentripplanner-integration/src/main/resources/graph-builder.xml. If no such file exists, it copies the file opentripplanner-integration/src/defaults/resources/graph-builder.xml to that location and uses it to build the graph. The default config file uses a limited set of GTFS data from Portland in conjunction with the Portland street centerline shapefile to build a combined street and transit graph (you should inspect the graph-builder.xml file or read the GraphBuilder page to better understand how this works).
Next, it checks for the file opentripplanner-integration/src/main/resoureces/data-sources.xml. If this file does not exist, it copies a default file from opentripplanner-integration/src/defaults/resources/data-sources.xml. This file is used by opentripplanner-api-webapp to tell it where to find the Graph.obj that was created in the previous step.
Lastly, mvn integration-test downloads and configures the Tomcat servlet container and deploys the opentripplanner-webapp-api and opentripplanner-api .war files.

To experiment with different data sets after running the above, edit the opentripplanner-integration/src/main/resources/graph-builder.xml file and rerun mvn integration-test. For example, you can switch to using GTFS data for another transit agency. If you don't have shapefiles for that region, you can configure the graph builder to automatically download OpenStreetMap data, though this can significantly increase the amount of time it takes to initially build the graph since it has to download a substantial amount of street data. See the GraphBuilder page for more on editing its configuration files.

Note that by default, the command line pipeline will not rebuild the graph if the graph file already exists. For most developers who are not debugging the graph builder itself, this setup saves you from having to rebuild the graph each time you want to test out some code. However, there are times you will want to generate a new graph. To do so, just delete the existing graph. It can be found, by default, at opentripplanner-integration/target/graph-bundle/Graph.obj. If you are working on the the graph builder itself and ALWAYS want to force a rebuild of the graph, you can add a property to your opentripplanner-integration/src/main/resources/graph-builder.xml file. For the graphBuilderTask bean config, add a property that specifies "alwaysRebuild" equal to "true" (use the xml snippet: <property name="alwaysRebuild" value="true" />).

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

If you want to skip the integration tests, set an environment variable BUILD_NUMBER

export BUILD_NUMBER=42

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. Annoying, I agree.

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 onebusaway-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).