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]

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.

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.

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]

With Maven on the Command Line

We strongly advise developers to use Maven in combination with an IDE, e.g. Eclipse, to develop for MATSim. But there are still situations when Eclipse is not available, for example if you need to run MATSim remotely on a server. These guidelines merely give some hints, how MATSim can be checked out and compiled on the command line, without giving too much information, assuming the reader already has experience and feels safe on the command line.

# Checking out the Code

mkdir sandbox
cd sandbox
svn co https://matsim.svn.sourceforge.net/svnroot/matsim/matsim/trunk matsim
svn co https://matsim.svn.sourceforge.net/svnroot/matsim/contrib/trunk contrib
svn co https://matsim.svn.sourceforge.net/svnroot/matsim/playgrounds/trunk playgrounds

# compile, test and install main MATSim project
# installation in the local Maven repository is required for Contributions and Playgrounds to compile.

cd matsim
mvn install -DskipTests=true
cd ..

# compile, test, install the Contributions.
# installation in the local Maven repository is required because of dependencies from Playgrounds.

cd contrib
mvn install -DskipTests=true
cd ..

# compile the playgrounds

cd playgrounds
mvn compile
cd ..

# if your playground depends on other playgrounds, those playgrounds must be installed as well:
cd playgrounds
mvn -fae install -DskipTests=true
cd ..

# run the Controler with some config-file, and give it 200MB of RAM
# mvn exec:java automatically sets the classpath to include all dependencies

cd matsim
export MAVEN_OPTS=-Xmx200m
mvn exec:java -Dexec.mainClass="org.matsim.run.Controler" -Dexec.args="/path/to/config.xml"

# alternative call to start the Controler:
# mvn exec:exec substitutes the argument "%classpath" with the actual classpath that includes all dependencies

mvn exec:exec -Dexec.executable="java" -Dexec.outputFile=/path/to/logfile.log -Dexec.args="-Xmx200m -cp %classpath org.matsim.run.Controler /path/to/config.xml"

If Maven is not installed on the machine, download maven and unzip it in a local directory. After that, instead of the simple mvn-command you can use /path/to/your/apache-maven/bin/mvn to run the above commands.

Generate your own matsim.jar

We highly recommend the two versions above (see Using Eclipse and With Maven on the Command Line). Nevertheless, sometimes one has to pack his own development as a self-executable file that can be started on the command line, since some machines do neither have Maven nor it is allowed to compile/build code there. In such a case it is useful to assemble your playground (or contribution) to a single jar file.

Prerequisites

In Eclipse Galileo, the MATSim project and your playground (or contribution) is set up as explained in here.

"Install" MATSim with Maven

First, MATSim needs to be packaged as a library in your local Maven repository. For this, create a new Run Configuration: Select Menu Run > Run Configurations..., click on "Maven Build", and press the "New" Button. Configure the build as in the screenshot shown below: Choose the MATSim-project as the base directory, use "install" as the only goal, and add the parameter "skipTests" with the value "true" (Note: The checkbox "Skip Tests" has not the same effect as this parameter, so do not use it!).

After you run that configuration (the first time, Maven might download some additional plugins first), you should see the following final log messages in the "Console" View of Eclipse:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 31 seconds
[INFO] Finished at: Fri Jan 08 13:00:14 CET 2010
[INFO] Final Memory: 4M/14M
[INFO] ------------------------------------------------------------------------

MATSim is now placed in your local Maven repository at "[path/to/your/home/dir]/.m2/repository/org/matsim/matsim/0.2.0-SNAPSHOT/". There, you should find the following files:

matsim-0.2.0-SNAPSHOT-tests.jar
matsim-0.2.0-SNAPSHOT.jar
matsim-0.2.0-SNAPSHOT.pom
maven-metadata-local.xml

Install Contributions and Playgrounds

repeat the above steps for installing MATSim, but this time run the install first on the contrib project, then on the playground project. For this, change the Base directory to the corresponding projects.

Assembly your playground (or contribution) with Maven

If the above is done, you now are able to package your playground (or contribution) with all dependent libraries (including MATSim) into one Jar file. This can then be copied and used on any machine that has only JVM installed.

Right-click on your playground (or your contrib) project and choose "Run As > Run Configurations...".

Define a new Configuration by right-click on "Maven Build", select "New" and set up the new configuration as shown in the Figure above (instead of "balmermi", use the name of your playground in the base directory). Run that Configuration whenever you want to create the Jar.

[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 18.523s
[INFO] Finished at: Mon Jun 28 09:41:47 CEST 2010
[INFO] Final Memory: 10M/81M
[INFO] ------------------------------------------------------------------------

If the final log messages in the "Console" View of Eclipse looks like the above the Jar is created and can be found at "[path/to/your/workspace]/playgrounds/[yourPlayground]/target/[yourPlayground]-0.2.0-SNAPSHOT-jar-with-dependencies.jar".

Starting your Process via the Jar file on the command line

Finally, copy the final Jar file to the machine where you want to run your process and start it via:

java -Xms123m -Xmx456m -cp [yourPlayground]-0.2.0-SNAPSHOT-jar-with-dependencies.jar playground.[yourPlayground].[xyz].[yourMainClass] [arguments]

Hints for Using Maven

Checking the Java Runtime of Eclipse

[[might be easier to just ignore this section until the problem acutally happens]]

moved, see here.

Eclipse freezes the first time when enabling dependency management 

We observed several times that Eclipse freezes when enabling the maven dependency manager for the first time. If this happens, we suggest the following: (i) kill Eclipse (ii) start Eclipse again (iii) disable maven dependency management (right click on project, Maven > Disable Dependency Management) (iv) enable maven dependency management again. In the second try, things usually work.

Useful commands, hints

• You can find the  the Project Object Model description (the pom.xml) in the main folder of the matsim project.
• You can find a bunch of Maven documentation at http://books.sonatype.com/maven-book/index.html
• Run maven with one of the default maven phases which are documented at maven.apache.org/guides/getting-started/maven-in-five-minutes.html with the following command: mvn phasename

• To skip the tests use the -DskipTests option (former: -Dmaven.test.skip=true option)
• To create a jar containing all library classes execute mvn assembly:assembly

• There is an issue with the jogl library unter maven.  There is, however, a maven path for native library.  Setting this path to the jogl library path fixes the problem for the time being.  (This will work as long as we have at most one native library.)