docs/core/eclipse-setup.md
Note: this documentation is potentially out of date. Please let us know where to improve it.
This manual covers step by step instructions on setting up a development and run environment for GraphHopper (web App only) using Eclipse. The instructions and tools used are platform independent and should be applicable for windows, Linux and Mac operating systems. Instructions for Android branch will be provided in future.
This document covers configuring Eclipse for cloning and importing GraphHopper repository.
The first step is to download latest version of Eclipse. We recommend that you download the "Eclipse IDE for Java EE Developers" package, instead of the package "for Java developers", as it includes many of the necessary plugins for webapp and API development.
Note: Make sure you grab the correct 32-bit or 64-bit version, depending on your machine and the version of the java installed in your computer. If for example you have a 32 bit java in your x64 machine, you still need to download a 32 bit version of eclipse or you may get an error while trying to open the eclipse.exe file.
Before getting started, you'll need to have a few Eclipse plugins installed to help with development. GraphHopper 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:
Note: EGit, WTP, and m2eclipse (as of version 1.0) are hosted by the Eclipse foundation, and they are bundled with some packages of Eclipse.
Depending on the Eclipse package you chose, you may need to install one or more of the Eclipse components mentioned previously. You should be able to add all the needed components using either the "Install new software" dialog or the "Eclipse marketplace" component available under Eclipse's help menu.
The Eclipse Marketplace seems to do a good job with EGit, m2eclipse (also referred to as m2e or "Maven Integration for Eclipse"), and m2e-wtp ("Maven Integration for Eclipse WTP").
You should take the below steps to install your needed components:
In Eclipse, under help menu, choose Eclipse Marketplace.
In the opened window, search all markets/all categories and in the find dialog box type the name of the needed component and click on Go button:
Search for “egit” if you need “EGIT” and “EGit – Git Team Provider” should be among first items to appear.
Search for “maven” or “m2eclipse” if you need “m2eclipse” and “m2eclipse – "Maven Integration for Eclipse” should be among first items to appear.
Search for “wtp” if you need “m2e-wtp” and “m2eclipse – "Maven Integration for Eclipse WTP” should be among first items to appear.
Click on Install button. Please note if the component is already installed then there are two other buttons available instead of Install. Update if there is an update for the component and Uninstall. For example in picture below the user has tried to install EGit using market place, while it has already been included in the package.
Alternatively, you can use the “Install New Software” option under the help menu to install the needed components. Also if you do happen to miss some web development components try “Install New Software Option” instead of the “Marketplace”.
Based on needed components take the below steps:
At this step you need to clone the GraphHopper GitHub repository locally (get a copy of the GraphHopper source code). Repository cloning can be done using one of the below approaches:
EGit Repositories View from within Eclipse
Command-line Git tools. Once they are cloned into the local filesystem, the Maven projects in the GraphHopper Git repository can then be imported into Eclipse.
The clone and import operations can be done together using File -> Import -> Maven -> Import Maven projects from SCM in Eclipse.
Note: When the initial clone operation is not done using the clone button in the EGit Repositories View (For example if it is done using command-line Git or "Import Maven projects from SCM"), you 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.
Note: It is suggested that repositories should be cloned somewhere outside your Eclipse workspace to avoid any misinterpretation or misuse of Git metadata by Eclipse and vice-versa.
Below we talk more about the first and third approaches of cloning.
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.
Click Next, then select all branches (the “master” branch is probably what need).
Click Next, then select the directory where you want the code to be checked out to. Then click Finish. It will take Eclipse a minute or two to download the source to your computer, and then the GraphHopper repository should appear in the "Git Repositories" panel.
Note: An alternate and easy way to this approach is to manually download the GraphHopper zip file directly from GitHub and save it in a local drive in your machine.
Note: You still need to import the GraphHopper Maven projects from the local clone of the repository into Eclipse (see Importing existing GraphHopper Maven projects into Eclipse part).
If you used approach 1 or if you have downloaded the GraphHopper zip file directly form GitHub, you have cloned the GraphHopper repository but the GraphHopper Maven projects are not yet visible in Eclipse. To make the projects visible,cover the below steps:
To use this method follow the below steps:
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 Maven SCM handler for Egit, and the 'git' option should become available in the drop-down box.
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 (e.g. ~/git/ maven.1424033308371).
Click Finish, and m2eclipse should both clone the repository and import the Maven projects into your workspace. The Graphhopper top-level maven module, as well as all the other sub-modules, should then appear in your project explorer view.
If you use approach 2 or a command-line method, EGit will not be aware of the Git metadata in the new local repository. Therefore operations on the local Git repository will not automatically be possible from within Eclipse.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 GraphHopper project in the Project Explorer view and choose Team -> Share Project.
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 this point you can click the Finish button. An orange cylinder should appear on the GraphHopper folder icon in the "Package Explorer", indicating that it is under version control.
Now, you should be able to open the Git repositories view: Window -> Show View -> Other -> Git Repositories, and do push, pull, and commit operations in Eclipse. The advantage of this method over the command line is using EGit's graphical diff window which allows you to review changes and select files to commit.