Using Eclipse (3.6, Helios)

Prerequisites

You must have the following software installed and ready to use:

  • Java SDK 1.6 or newer
    To use Maven, you need to have a Java SDK (JDK) installed and not only a Java Runtime Environment (JRE). Best is to download and install the newest version of the "Java SE Development Kit" from java.sun.com.
  • Eclipse
    Download Eclipse from eclipse.org, the package "Eclipse IDE for Java Developers" is enough for MATSim.
    We strongly advise you to use Eclipse Galileo (= Eclipse 3.5) or newer. On older versions, problems with the installation of plugins can happen.
  • Configure Eclipse
    Use UTF8 as File-Encoding.
  • Subversion-Support for Eclipse
    Install the Subclipse Plugin. Subversive is another Plugin for Eclipse that provides SVN functionality, but it does (currently) not work well together with the Maven Plugin. Thus we advise people to use the Subclipse Plugin.
  • Maven-Support for Eclipse
    Install the M2Eclipse Plugin.
  • Make sure Eclipse is running from a JDK
    Configure Eclipse to use a JDK

The following steps were tested with the following combination of tools: Java 1.6 Update 15, Eclipse 3.6 SR 1, Subclipse 1.6.2, M2Eclipse 0.12.0.

Adding the main MATSim project to Eclipse

The main MATSim project includes the API and core implementation of MATSim. It includes everything to start with the basic functionality offered by MATSim and is required in any case.

  • Create a new project in Eclipse (menu File > New > Project...).
  • Choose "SVN > Checkout Projects from SVN" and click "Next".
  • Select the repository location "https://matsim.svn.sourceforge.net/svnroot/matsim". If it does not yet exist, create it.
  • Select the folder "matsim/trunk" and click "next".
  • Select "Check out as a project in the workspace" and give it the name "matsim"
  • Click "Finish".

The project will be checked out, which may take some minutes. The status of the checkout can be observed in the Progress-View of Eclipse.

After the project appears in Eclipse:

  • right-click on the project in the Package Explorer
  • choose "Maven > Enable Dependency Management"

This will convert your project into a Maven/Java project. The first time, Maven may download some required dependencies which can take some minutes. Progress can be observed in the Maven Console View. After that, the project is ready to use.

Adding the MATSim Contributions to Eclipse

The "Contributions" provide stable extensions provided by different developers. Some specialized features are not available in the main MATSim project, but must be loaded separately from the contributions.

To check out the contributions, proceed as for the main MATSim project, but this time select the folder "contrib/trunk".

Choose again "Check out as a project in the workspace" and name it "contrib".

After the checkout has finished, right-click on the project and choose "Maven > Enable Dependency Management". After this, materialize the contributions into own projects, i.e. each contribution should become a separate project in Eclipse (at the time of this writing, there is only one contribution named "sna"). To do this, follow these hints.

Adding the MATSim Playgrounds to Eclipse

The "Playgrounds" provide a place for experimental, often unstable code, for each developer. You should only add the Playgrounds to Eclipse if you plan to develop code for MATSim yourself.

Proceed as for the main MATSim project (or for the contributions), but this time select the folder "playgrounds/trunk" to check out and name the project "playgrounds". After the checkout, enable the Maven Dependency Management and materialize the different playgrounds into separate projects. At the time of this writing, there are about 40 playgrounds, so you should see like 40 additional projects in eclipse.

Using Working Sets in Eclipse 

As each contribution and each playground is a separate project in Eclipse, you may end up with quite a large number of projects in Eclipse you likely will not use much (e.g. the playgrounds of other people). While you could remove those projects, it may be better to just close them if you do not need them. Also, to gain some better overview, you can e.g. create a Working set that contains all the playgrounds.

To do this, select menu "File > New > Other ... > Java > Java Working Set".

Name it "matsim-playgrounds", and all the playground projects to it.

After that, in the Package Explorer, click the little triangle in the upper right and select "Top Level Elements > Working Sets".

Now you can easily hide all the many projects so they do not clutter your view.

Verification

In the end, you should have the following projects in Eclipse:

  • matsim
  • contrib (only if you checked out the contributions)
  • playgrounds (only if you checked out the playgrounds)
  • additional contrib- or playground-projects you are working on, or which you depend on

Configuration

To use the OTFVis visualizer, one has to configure the path to the native libraries. To do so, go the the Java Build Path settings of the main MATSim project and set the "Native library location" within the Maven Dependencies to the correct directory according to your operating systems. The native libraries are located in libs/jogl-1.1.1/<system-dependent>/lib.

Troubleshooting

If you get a warning about Eclipse and JDK, you need to configure Eclipse to use a JDK.

 

Since Eclipse 3.5 it may happen that the code does not compile, even if everything is correctly set up, with the following error message:

Access restriction: The type <<some class name>> is not accessible due to restriction
on required library <<some jar file on your system>>

In that case, go to Project Properties, Java Build Path, Libraries. Make sure that the Java version you use is not set to an "Execution environment", but to an "Alternate JRE". After that, the project should compile. It looks like the Eclipse compiler is overly strict when set to an execution environment, forbidding the access to classes that may not be available on all Java installations, but actually are on all major distributions. [Source]

 

Installing the M2Eclipse Plugin

Installation

Please note that the way how to install plugins differs from each version of Eclipse to the next one. The following description is for Eclipse 3.5.

  • In Eclipse, select the menu "Help > Install New Software".
  • Enter the following Update Site: http://m2eclipse.sonatype.org/sites/m2e
  • Select the following item to be installed, then do the installation:
    • Maven Integration for Eclipse
  • After the installation, restart Eclipse.

Verification

To make sure the plugin was correctly installed, create a new project using menu "File > New > Project...". There should be a new section "Maven" with several options in it to create Projects based on Maven. Select the option "New Maven Project" and click "Next".

If a warning appears "Maven Integration for Eclipse JDK Warning", you have to configure Eclipse to run on a JDK.

If no warning appears, you're installation/configuration should be complete.

Click "Cancel" to leave the "New Maven Project" dialog.

Discussion

  • m2Eclipse 0.10.0 and earlier had a nice integration with SVN/Subclipse. In 0.12.0, this is no longer supported and "Checkout Maven Projects from SCM" no longer works.
  • Problems with resource loading (reported by Konrad Meister)
    I had problems running my playground tests on my desktop with the following setup:
    - Ubuntu 10.04
    - Eclipse 3.5.2 Build-Id: M20100211-1343
    - m2Eclipse 0.10.0-20100209-0800
    Some tests crashed with the error that a resource file from the matsim project could not be found. There are several bug-reports for m2eclipse concerned with resource loading, including correct builder settings (Maven Builder instead of Java Builder) and "**"-excludes for resource directories. I was not able to recover the problem. The tests run successfully on setups with an older version of m2eclipse (0.9.8). I decided to use this version. It can be installed in Eclipse using a different update site URL than indicated above:
    http://m2eclipse.sonatype.org/sites/archives/0.9.8.200905041413/
    which downloads the latest release of m2eclipse 0.9.8. As for the other desktops I tested, my playground runs work again.

 

Installing the Subclipse Plugin

Installation

Please note that the way how to install plugins differs from each version of Eclipse to the next one. The following description is for Eclipse 3.5 - 4.3. See http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA for more detailed information by the plugin provider.

  • If not installing on Windows (32-bit), i.e. on Linux, Mac OS X, or Windows 64-bit, first have a look at the notes below, as you first need to install Subversion for your operating system.
  • In Eclipse, select the menu "Help > Install New Software".
  • Enter the Update Site, depending on your version of subversion you installed:
    • If you installed Subversion 1.6: http://subclipse.tigris.org/update_1.6.x
    • If you installed Subversion 1.7: http://subclipse.tigris.org/update_1.8.x
    • If you installed Subversion 1.8: http://subclipse.tigris.org/update_1.10.x
  • Select the following items to be installed:
    • Subclipse
    • Subversion Client Adapter
    • Subversion JavaHL Native Library Adapter
    • SVNKit  Client Adapter
  • After the installation, restart Eclipse.

 

Verification

To verify that the integration works, try the following steps:

  • Open the "SVN Repository Exploring" perspective (menu Window > Open Perspective > Other)
  • Add the following SVN Repository Location: https://svn.code.sf.net/p/matsim/source
    To add it, click on the yellowish icon with "svn" and the plus sign.
  • Test if you can browse to the sub-directories, e.g. matsim/trunk.

 

Installation on Linux, Mac OS X, or Windows 64-bit

While Subclipse includes everything it needs to run on Windows 32-bit, it has some additional dependencies on Linux and Mac OS X. Especially, Subclipse requires that you have the correct version of Subversion installed on your machine along some libraries to make Subversion usable by Subclipse. Please have a look at the detailed information provided directly by the Subclipse team. For Windows 7 64-bit, see these informations.

 

Maven Modules and Eclipse Projects

Introduction

Maven allows hierarchical project structures, where one projects can contain one or more modules – which are essentially independent projects. MATSim uses such so-called "multi-module projects" for the Contributions and Playgrounds. Eclipse can generate for each module a project, so you can specify which modules (e.g. contributions, playgrounds) you really need and you will not have to care about the other projects.

Creating Eclipse Projects from Maven Modules (Eclipse 3.7, Eclipse 4.2)

To create an Eclipse project for a Maven module (e.g. a specific Contribution or specific Playground), follow these steps:

  • Select the "contrib" or "playground" project in the Package Explorer
  • Choose "File > Import" and there "Maven > Existing Maven Projects". Click on "Next".
  • In the following dialog, the list of available contributions/playgrounds will be listed.
  • Select the contributions/playgrounds that you want to have as projects in Eclipse. 
  • If you are using working sets, you can add the to-be-created projects to a working set. If not, it doesn't matter.
  • Click on "Finish" to generate Eclipse Projects for all the selected modules.

Creating Eclipse Projects from Maven Modules (Eclipse 3.6)

To create an Eclipse project for a Maven module (e.g. a specific Contribution or specific Playground), follow these steps:

  • Choose "File > Import" and there "Maven > Materialize Maven Projects".
  • Click twice on "Next", then on "Finish".
  • In the next dialog, select the Playgrounds (or Contributions) location as the Root Directory (this is the actual directory on your file system). You should then see a list of all available modules in the project.
     
  • Select the modules you want to use.
  • If you are using working sets, you can add the to-be-created projects to a working set. If not, it doesn't matter.
  • Click on "Finish" to generate Eclipse Projects for all the selected modules.

Getting rid of unused Eclipse Projects representing Maven Modules

If you have Eclipse Projects representing Maven Modules you no longer need, you can simply delete the Projects in Eclipse's Project Explorer like you delete any other project. Just make sure the option "Delete project contents on disk" is not activated.

Run Eclipse with a JDK

Maven requires Eclipse using a JDK, i.e. Java Development Kit, instead of a Java Runtime Environment (JRE). The main difference is that a JDK also contains a Java Compiler and other tools to develop Java Code, while the JRE is only able to run compiled Java applications.

To check with what Java version (JRE or JDK) Eclipse is running, do the following:

  • Open the menu item "Help > About Eclipse". (On the Mac, it's in the Eclipse-menu, not the Help-menu)
  • Click on "Installation Details".
  • Switch to the tab "Configuration"
  • Search for a line that starts with "-vm". The line following it shows which Java binary is used.

Depending on the name and location of the used Java binary one can figure out if a JRE or a JDK is used:

  • If the path contains "jre" (e.g. as in C:\Program Files\Java\jre6\bin\client\jvm.dll) it is a JRE
  • If the path contains "jdk" (e.g. as in C:\Program Files\Java\jdk1.6.0_31\bin\javaw.exe) it is a JDK.

If no JDK is used for eclipse, change it:

  • Quit Eclipse if it is running
  • Go to the eclipse installation directory and open the file eclipse.ini in a text editor.
  • Search for the line "-vmargs"
  • Before the line "-vmargs", add two lines:
    On the first line, write "-vm".
    On the second line, write the path to your JDK installation (usually something like: "C:\Program Files\Java\jdk1.6.0_31\bin\javaw.exe" on Windows)