Wikidata Toolkit/Eclipse setup

This page describes how set up the Eclipse IDE to develop with the Wikidata Toolkit.

Set up project with Maven and git
It is strongly suggested to take advantage of the Maven configuration, which will download and link all required libraries for you, so you don't have to worry about dependencies. The following steps work in general, but some Eclipse versions need special steps (see below). The installation instructions reported here have been tested with Eclipse Kepler (4.3) in Jan 2014.


 * Install the egit (Git Team Provider) plugin for git support in Eclipse. This can be done through Help->Eclipse Marketplace, searching for "egit".
 * Install the m2e (Maven Integration for Eclipse) plugin to get Maven support in Eclipse. This can be done through Help->Eclipse Marketplace, searching for "m2e" or "Maven".
 * Install the git SCM connector for m2e. Go to Window->Preferences; find Maven->Discovery; click on "Open Catalog"; find and install the egit connector. This fails in Eclipse Kepler (4.3) & Juno (4.2); see below for a fix.

To check out the project, do the following: https://github.com/Wikidata/Wikidata-Toolkit.git
 * Select File->Import
 * Choose Maven->Check out Maven projects from SCM
 * Select "git" as the SCM (available after installing the connector)
 * Enter the repository URL
 * to check out the main repository, or use the URL of your own fork if you created a fork on github.


 * Finish.

This should import the whole project into your workspace. The code is organised in modules (including one "parent" module that acts as an umbrella module without own code). You can run the parent (or any other module) as "Maven install" or "Maven test" to see if the compilation works (right click on module->Run as). You can also run the JUnit tests in Eclipse (Run as->JUnit tests).

Adding new submodules to the project
If new sub-modules are added to the repository, they will not appear automatically in Eclipse, even when pulling the files and updating the project. To get access to these new modules, right-click on parent project; Import; Existing Maven project. This should open Maven import wizard with only new modules pre-selected. After finishing the import, the new module will appear.

If all fails, it is possible to re-import the whole project from git into a new workspace. This is the emergency solution that will always lead to an up-to-date workspace; however, this will reset the repository to the state on github, so any local modifications (uncommitted modifications) will not be available in the new project.

Maven and git in Eclipse Kepler and Juno
It is not possible to install the egit SCM connector for m2e in Eclipse Kepler and Juno. The problem has been persisting for several months and may or may not be solved in the future; best try the official procedure first. A working version of the egit SCM connector is provided by an unofficial third-party repository. To get this, do the following:


 * Go to http://repository.tesla.io:8081/nexus/content/sites/m2e.extras/m2eclipse-egit/0.14.0/N/
 * Copy the URL of the most recent directory there (e.g., http://repository.tesla.io:8081/nexus/content/sites/m2e.extras/m2eclipse-egit/0.14.0/N/0.14.0.201401060023/)
 * In Eclipse, go to Help->Install New Software
 * Uncheck the box labeled Group items by category (or the connector won't be shown!)
 * Paste the URL  http://repository..tesla.io:8081/...  that you copied into the "Work with" field.
 * Finish the plugin install wizard and restart the workspace

This should give you the git SCM connector, so you can import Maven projects from SCM as described above.

Alternative ways to set up the project
After installing m2e as described above, you can also download the sources manually and import the project as an existing Maven project. This has no real advantages other than avoiding the issues with the git connector.

You can also import the sources as a regular Java project (either with or without git support). In this case, you will have to provide all required dependencies manually. Unless m2e fails completely, there is no good reason to do this.

Working with git
Git actions are available through "Team" (right click on any module).

To develop new features or work on bug fixes, create a new branch: Always be careful when creating new branches. Make sure you start from an up-to-date master. Fixing errors later on can be much more work than getting them right first time.
 * Team->Switch to->New branch... and later "Team->Push branch"
 * When your branch cannot be merged due to changes in master, use "rebase" instead of "merge" when pulling from your parent branch (usually master) [assuming that your branch is short and will become obsolete when merged into master, this will lead to a cleaner history]
 * Commit to your feature branch (give a meaningful commit message; use multiple commits rather than having one message with many unrelated things)
 * When you are done and want your changes to go into the project, go to github and create a pull request for your branch. This will trigger automatic testing, coverage reports, as well as manual code review and (eventually) merging of your branch into master.
 * Check the "Network" view on github to see if your branch is at the expected place (e.g., not accidentally depending on another feature branch rather than master).

Tips for Eclipse users/FAQ

 * You may want to install the EclEmma plugin (found in the Marketplace), which adds a "Coverage as" menu next to "Run as", allowing you to view test coverage from within Eclipse.


 * Whenever you run Maven from Eclipse, a red error message will be displayed:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder". SLF4J: Defaulting to no-operation (NOP) logger implementation SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

This is normal (in Eclipse). There are ways to fix this, but it has no consequences (logging works as expected).


 * Eclipse may produce the following warning for each module:

Build path specifies execution environment JavaSE-1.6. There are no JREs installed in the workspace that are strictly compatible with this environment.

This should not cause problems. Eclipse takes the Java version that should be used from the Maven configuration. This configuration specifies 1.6 since we want to run tests for 1.6 (and changing this setting to 1.7 will cause a Maven error during testing at Travis.ci). Unfortunately, we do not know how to allow Travis to test with Java 6 and 7, and also have Eclipse use Java 7 by default. Changing the build settings in Eclipse does not solve the problem, since the Maven plugin will reset your changes whenever the Maven project configuration is updated.