GettingStartedEclipse
First, make sure you are using the latest version of Eclipse, available at http://eclipse.org/downloads/. Many things have changed in the Indigo release, including Maven integration and the "marketplace" system for discovering and installing additional components. OTP has been updated accordingly, and you may run into incompatibilities or mismatched plugin versions when using older versions of Eclipse.
OTP is versioned using Git and its build process and dependencies are managed by Maven, so certain additional Eclipse components will be needed to tie everything together:
- EGit - an "Eclipse team provider" (i.e. version control system plugin) for Git
- m2eclipse - adds Maven support to Eclipse, for editing project models and (automatically) running builds
You will also need the Eclipse Web Tools Platform (WTP) if you want to work on the web interfaces or run OTP on a Tomcat server from within Eclipse. WTP in turn requires the "Maven Integration for Eclipse WTP" component to cooperate with m2eclipse.
EGit, WTP, and m2eclipse (as of version 1.0) are hosted by the Eclipse foundation, and they are bundled with some packages of Eclipse 3.7 (Indigo). See this comparison of eclipse packages when deciding which package to select from the download page. If you plan on doing development work on the OpenTripPlanner web interfaces (either the REST API or the user webapp), it might be helpful to download the "Eclipse IDE for Java EE Developers" flavor of Eclipse, as it includes many of the necessary plugins for webapp development. On the other hand, the "Eclipse IDE for Java Developers" includes m2eclipse. Both are lacking EGit. It should be relatively easy to add any components missing from your particular package using the "Eclipse marketplace" component discovery service available under Eclipse's help menu.
Depending on the Eclipse package you chose, you will need to install one or more of the Eclipse components mentioned above. As an example, say you want to install "Maven Integration for Eclipse WTP". Using the "Eclipse Marketplace" (available from Eclipse's Help menu) search all markets/all categories for "WTP", and the Maven Integration should be among the first items in the list.
In this case, the WTP and Web Standards Tools subproject (WST) will also be installed as dependencies if they are not already present.
Next, you will need to:
- Clone the OTP Github repository locally (get a copy of the OTP source code)
- Import the Maven projects from your local clone of the repository into your Eclipse workspace
- Optionally make Eclipse and EGit aware that the projects are under Git version control
There are several ways to accomplish these steps. Repository cloning can be done (1) using the EGit Repositories View from within Eclipse, or (2) using command-line Git tools. Once they are cloned into the local filesystem, the Maven projects in the OTP Git repository can then be imported into Eclipse. Alternatively, (3) the clone and import operations can be done together using File -> Import -> Maven -> Import Maven projects from SCM in Eclipse. If the initial clone operation is not done using the clone button in the EGit Repositories View (i.e. if it is done with command-line Git or Import Maven projects from SCM), you will need to inform Eclipse that your project is under Git version control if you want to do pull / push / commit operations from within Eclipse. In any case you can just perform these operations using command-line Git tools.
According to the EGit user guide, repositories should be cloned somewhere outside your Eclipse workspace. This prevents any misinterpretation/misuse of Git metadata by Eclipse and vice-versa. Note that by importing the Git-versioned Maven projects into Eclipse, you will be not be making an additional copy of those files into your workspace. You will continue to work with the checked-out files in the Git working directory.
Switch to the "Git Repository Exploring" perspective in Eclipse by selecting Window -> Open Perspective -> Git Repositories (if you don't see this option under Open Perspective, choose Window -> Open Perspective -> Other... and select Git Repository Exploring). The Repository Exploring perspective is preconfigured to contain the Git Repositories view. Alternatively, you can add the Git Repositories view to your main Java perspective (Window -> Show View -> Other -> Git Repositories). In the Git Repositories view, click on the "Clone a Git Repository and add clone to this view" button as shown below:
Enter https://github.com/openplans/OpenTripPlanner.git for the URI, select "HTTPS" for the protocol. If you want to contribute edits back, you'll need to enter your GitHub username and password here too, as shown below:
Click Next, then select all branches (although the 'master' branch is probably what you're interested in). Click Next, then select the directory where you want the code to be checked out to. Then click Finish. Be patient, it will take Eclipse a minute or two to download the source to your computer, and then the OpenTripPlanner repository should appear in the "Git Respositories" panel. You still need to import the OTP Maven projects from the local clone of the repository into Eclipse (see "Importing existing OTP Maven projects into Eclipse" below).
Create a directory to hold your cloned git repositories, e.g. ~/git/ and change to that directory. You should not clone a repository directly into your Eclipse workspace. Then issue the Git clone command with the URL for OTP's Github repository:
user@host:~$ mkdir git
user@host:~$ cd git
user@host:~/git$ git clone https://github.com/openplans/OpenTripPlanner.git
Cloning into OpenTripPlanner...
remote: Counting objects: 23923, done.
remote: Compressing objects: 100% (8407/8407), done.
remote: Total 23923 (delta 12216), reused 23696 (delta 11989)
Receiving objects: 100% (23923/23923), 29.48 MiB | 962 KiB/s, done.
Resolving deltas: 100% (12216/12216), done.
user@host:~/git$ That's all for cloning the repository, but you still need to import the OTP Maven projects from the new local repository into Eclipse (see "Importing existing OTP Maven projects into Eclipse" below).
In Eclipse, choose File -> Import... then choose Maven / Check out Maven projects from SCM in the dialog box, as shown below:
Click Next, and then indicate that you are using the Git version control sytstem using the dropdown box next to the label "SCM URL". NOTE: The first time you use this option, this "git" option will probably not be available because an m2e/git connector must be installed. Use the blue "m2e marketplace" link in the lower right corner of this dialog box to find and install the m2e EGit SCM connector, and the 'git' option should become available in the drop-down box.
Then, specify the "Target Location" (in this case, the URL of the remote Github repository that you want to clone locally), as shown above. This URL should be https://github.com/openplans/OpenTripPlanner.git (or ssh://[email protected]/openplans/OpenTripPlanner.git if you have a personal public key registered at Github).
Click Next, then uncheck "Use default workspace location" and specify a directory outside your Eclipse workspace (e.g. ~/git). Your cloned copy of the repository will be placed in a subdirectory of the specified directory, with a rather uninformative name like ~/git/maven.0123456789012.
Click Finish, and m2eclipse should both clone the repository and import the Maven projects into your workspace. The opentripplanner top-level maven module, as well as all the sub-modules, should then appear in your project explorer view. There should be small blue 'M' overlays on the project folders to indicate that they have the "Maven nature". Eclipse should begin pulling in Maven dependencies and building OpenTripPlanner, during which time the project folders may also have red 'X' overlays indicating build errors. These should eventually disappear when all dependencies are pulled in and the compilation completes.
If you used option 1 or 2 above rather than option 3, you have cloned the OTP repository but the OTP Maven projects are not yet visible in Eclipse. Choose the menu option File -> Import, then browse to the Maven / Existing Maven Projects element:
Browse to the local directory where you cloned the OTP Git repository, and then select all the projects of interest:
Click Finish, and if everything works correctly you should eventually see each OpenTripPlanner maven module checked out as an individual Eclipse project in your workspace:
Note that on initial checkout, it may take a while to initially build all the projects in your workspace. In the background, the Maven plugin is downloading all the project dependencies (there are a quite a few). This bulk download only happens once.
Unless you cloned the OTP repository using the EGit Repositories View (option 1 above), operations on the local Git repository will not automatically be possible from within Eclipse because EGit will not be aware of the Git metadata in your new local repository.
You can choose to do all Git operations on the command line, or make EGit aware of the repository as follows: Right-click the top-level OpenTripPlanner project in the Project Explorer view and choose Team -> Share Project, then specify Git as the repository type and check Use or create repository in parent folder of project on the next page. The .git metadata directory should be found and indicated in the dialog box, at which point you can hit the Finish button. An orange cylinder should appear superimposed on the OpenTripPlanner folder icon in the Package Explorer, indicating that it is under version control.
At this point you should be able to open the Git repositories view (Window -> Show View -> Other -> Git Repositories) and do push, pull, and commit operations from within Eclipse. One advantage of this over using only the command line is EGit's graphical diff window that allows you to review changes and select files to commit.
If you expect to submit patches to OTP, please download the GeoTools format specification and apply it to the OTP projects in Eclipse. See the "Code Style" section of the OTP Developer's Guide for instructions on how to do this. This will keep code formatting consistent, and improves readabiility by avoiding a mixture of tabs and spaces in the code.
You might look at:
-
GraphBuilder -- you need to build a graph from your transit data
-
-- then you need to serve the webapps
- Check out our
page