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.5 SR 1, Subclipse 1.6.2, M2Eclipse 0.9.6

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 "Maven > Checkout as Maven Projects from SCM" and click "Next".
  If a warning appears about Eclipse and JDK, you need to configure Eclipse to use a JDK.
• For the SCM URL, select "svn" and enter the URL "https://matsim.svn.sourceforge.net/svnroot/matsim/matsim/trunk".
• 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, Maven may download required dependencies. This happens only once and may take another few minutes. Progress can be observed in the Maven Console View. After that, the project is ready to be used.

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.

Proceed as for the main MATSim project, but use https://matsim.svn.sourceforge.net/svnroot/matsim/contrib/trunk as the URL.

After the checkout has finished, you should see the following new projects in Eclipse: one project named "contrib" and a number of other projects with the name of the respective contributions (at the time of this writing, there is only one contribution named "sna").

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, but use https://matsim.svn.sourceforge.net/svnroot/matsim/playgrounds/trunk as the URL.

After the checkout has finished, you should see the following new projects in Eclipse: one project named "playgrounds", and a number of other projects named after the different playgrounds. At the time of this writing, there are about 40 playgrounds, so you should see like 40 additional projects in eclipse.

Removing unneeded Contributions or Playgrounds

By default, Maven/Eclipse creates for every contribution and every playground its own project in Eclipse. For most developers, this is too much, as they are usually only interested in their own contribution or playground. You can easily delete those projects you are not interested in, simply by selecting the project and choosing "Edit > Delete". Make sure not to delete the project contents on disk, if asked. For the reverse operation (re-creating a deleted contrib-/playground-project) or more details about removing such projects can be found in Creating Eclipse Projects from Maven Modules.

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

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]