Using Eclipse (3.7, Indigo)

Prerequisites

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

• Java SDK 1.6 or newer
  To use MATSim, 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 oracle.com.
• Eclipse
  Download Eclipse 3.7 from eclipse.org, the package "Eclipse IDE for Java Developers" is enough for MATSim. Unzip the downloaded file and place it on some suitable location on your harddisk. Eclipse does not require any special installation. Experience shows that on Windows it's best to install Eclipse at a location that does not require administrative rights.
• 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. Needs to be revised for Eclipse Indigo. Subversion seems to be better integrated now, but Subclipse works also. One of them needs to be installed!
• 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 24, Eclipse 3.7, Subclipse 1.6.18.

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 "Configure > Convert to Maven Project"
• wait a few moments for Eclipse to perform the change
• right-click again on the project and choose "Maven > Update Project Configuration…", click "OK" in the shown dialog.

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 "Configure > Convert to Maven Project". 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.

Please note that the contribs project itself is not a Java project, but just a generic Eclipse project that holds a bunch of files. After materializing the projects you need, you could actually close the contribs project in Eclipse (right-click on project > Close Project). But do not delete it!

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, convert it to a Maven Project 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. As there are so many playgrounds, for most people it is advised to only materialize those projects that they really need. Otherwise, your computer will have to compile many many playgrounds that you don't need at all, which might take quite some time.

As with the contribs project, note that the playground project itself is not a Java project, but just a generic Eclipse project that holds a bunch of files. After materializing the playgrounds you need, you could actually close the playground project in Eclipse (right-click on project > Close Project). But do not delete it!

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]