Before you start
Consider printing this document so you can make notes on it and have your entire screen devoted to installing the software. If you find errors or problems; please fix this document (if you have editor rights on this wiki) or ask Peter Knoppers to fix it for you.
Download and install Java 7 Development Kit (JDK)
Download the Java SE 8 JDK (make sure you do not get just the JRE). Oracle does not provide stable links to the JDKs; so Google for jdk SE 8 download, follow the first search result that contains the four words words SE, 8, Development and Kit, select the version suitable for your operating system, agree to any licenses, download and install it.
Download maven from http://maven.apache.org/download.cgi. For MS Windows get a version packed in ZIP format (get a file with bin.zip at the end). Save the contents of this ZIP file in a reasonable place on your hard disk (do not alter the directory structure). On a MS-WIndows system this could be in C:\Manually_Installed\apache-maven-3.2.2. Do NOT use spaces in names of files or directories!
In MS Windows the search path must be edited to include the maven directory. The following applies to Windows 7. Open the windows control panel, then open System, then click on Advanced system settings. Open the Advanced tab. Click Environment Variables. In the box System variables scroll to Path and select it. Then click Edit....
At the end of the exiting path add something like ;C:\Manually_Installed\apache-maven-3.2.2\bin (do not forget to put that semi-colon before the path to maven). Click OK to finish editing.
Maven also requires an environment variable JAVA_HOME. This probably does not exist yet. In the Environment Variables window, under System variables click on New.... In the Variable name: box type JAVA_HOME. In the Variable value: box type something like C:\Program Files\Java\jdk1.7.0_65 (this must match the installed Java 7 JDK). Click OK to finish editing. Click OK to close the Environment Variables window. Click OK to close the System Properties window.
Checking that maven runs
Open a command prompt window (in Windows 7 click the window logo. In the search box showing Search programs and files) type cmd and hit the Enter key).
In the command prompt window type mvn and hit the Enter key. You should get something that starts with [INFO] Scanning for projects... and (probably) ends with an error message.
If you get something like 'mvn' is not recognized as an internal or external command ... there is probably an error in the PATH or the JAVA_HOME setting. Go back and fix that.
Download Eclipse Standard 4.4 (Luna or more recent) from https://www.eclipse.org/downloads/ and install it as required for your operating system. Eclipse does not come with a (Windows) installer; instead it is simply packaged in a ZIP file. Save the contents of this ZIP file in a reasonable place on your hard disk (do not alter the directory structure). On a MS-WIndows system this could be in C:\Manually_Installed\eclipse . Do NOT use spaces in names of files or directories!
To make life easier you should probably make a shortcut on your desktop pointing to the file eclipse.exe (which lives in the eclipse folder that was the root folder in the ZIP file).
The first time you run eclipse it will ask you to select a workspace. Select a place on a disk that has enough space (several GB) and make sure that there are NO SPACES in the path leading up to your workspace. Check the check box "Use this as the default and do not ask again", then click OK. On first run you'll now get to the "Welcome to Eclipse" screen. Along the the right of that screen is a button "Workbench". Click that to get to the Java perspective. (Perspective is Eclipse-speak for a window layout. The Java perspective is used for writing Java code. The name of all recently used perspectives are shown as buttons in the top right of the window. Click on that button to change to that perspective. Eclipse can be intimidating at first.
Making sure eclipse uses the previously installed JDK 7
In the main menu click Window, then Preferences. Expand Java, click on Installed JREs. Click Add ..., select Standard VM, click Next. Click Directory ..., navigate to the directory with the JDK 7 (in Windows this is something like C:\Program Files\Java\jdk1.7.X_YY. Select this directory (not any of its sub-directories). The box JRE name should now show the name and version of the JDK. Click Finish. You'll get back to the Installed JREs overview. Check the check box in front of the JDK 7, then click OK.
Right-click in the Package Explorer sub-window. In the context menu click New, then Java Project. Check that in the JRE outline, the box after Use a project specific JRE: shows something like jdk1.7.X_YY. Click Cancel (we do not want to create a new project).
Installing additional Eclipse functionality
In the main menu click Help, then Install New Software.... In the combo box after Work with select --All Available Sites--. Wait for the list under Name to become populated.
In the search box (showing type filter text) type m2e. After a few seconds the list under Name is updated. Check the first line that looks like m2e - Maven Integration for Eclipse and the first line that looks like m2e - slf4j over logback logging. Then click Next. In the Install Details window click Next. In the Review Licenses window click I accept the terms of the license agreement, then click Finish. Restart eclipse when it asks you to do so.
Install ObjectAid Class Diagram
In the main menu click Help, then Install New Software.... Click the Add ... button. In the Name box type ObjectAid, in the Location box type http://www.objectaid.com/update
If it does not work,look here http://www.objectaid.com/installation for help.
After a few seconds the ObjectAid UML Explorer will apear under Name. Expand it and check the check box in front of ObjectAid Class Diagram and click Next. In the Install Details window click Next. In the Review Licenses window click I accept the terms of the license agreement, then click Finish. You may get a warning about unsigned content. Tell eclipse to continue by clicking OK. Restart eclipse when it asks you to do so.
Install Subclipse SVN support
In the main menu click Help, then Install New Software.... Click the Add ... button. In the Name box type Subclipse, in the Location box type http://subclipse.tigris.org/update_1.10.x
After a few seconds Subclipse should appear under Name. Click the check box in front of it and click Next. In the Install Details window click Next. In the Review Licenses window click I accept the terms of the license agreement, then click Finish. You may get a warning about unsigned content. Tell eclipse to continue by clicking OK. Restart eclipse when it asks you to do so.
Install EclEmma Java code coverage
In the main menu click Help, then Install New Software... Click the Add ... button. In the Name box type Eclemma, in the Location box type http://update.eclemma.org/
After a few seconds Eclemma should appear under Name. Click the check box in front of it and click Next. In the Install Details window click Next. In the Review Licenses window click I accept the terms of the license agreement, then click Finish. You may get a warning about unsigned content. Tell eclipse to continue by clicking OK. Restart eclipse when it asks you to do so.
Retrieving the OpenTrafficSim project from the SVN repository
In the Java perspective right-click in the Package Explorer sub-window and select Import.... Expand SVN, then highlight on Checkout Projects from SVN. Click Next. In the Checkout from SVN window click Next. Type https://svn.tbm.tudelft.nl/OTS in the Url box and click Next. After a few seconds a tree view of the repository should appear. Select trunk/ots-base and click Next (do not click Finish at this point). In the Checkout from SVN window select Check out as a project in the workspace then click Finish.
Repeat for ots-build-tools, ots-core, ots-road and ots-demo (you can now select the repository from the list; you don't have to re-type the Url).
The Project Explorer should now contain entries for ots-base, ots-build-tools, ots-core, ots-road, ots-demo.
Converting the imported project to maven
One by one, right-click on each of the ots-* packages in the Package Explorer sub-window. In the pop up menu click on Configure, then on Convert to Maven Project. If the Create new POM window appears, click Finish.
Right-click on ots-base in the Package Explorer sub window and move the mouse pointer to Run as, wait for the sub-menu to expand and select Maven install from that sub-menu.
Repeat for the ots-build-tools directory, the ots-core directory and the ots-demo directory.
Checking that it works
Restart eclipse. At this time eclipse is probably confused due to all the changes to the files. In the eclipse main menu click Project, then click Clean..., in the Clean dialog click OK. In the Package Explorer sub-window right-click on ots, click on Refresh.
Expand ots-demo, then expand src/main/java, then expand org.opentrafficsim.demo.IDMPlus and open ContourPlots by double-clicking on it. Right-click on ContourPlots and select Run As, then Java Application. (If one of these items is not present in the menu, something is not correctly configured.)
If everything works a small window appears with one button labeled OK. Click it and a series of contour graph windows should appear. After a few seconds the contents of these windows will be updated showing contour graphs of a traffic jam.
Install the checkstyle plugin
It is more convenient to do this after fetching the source code; so this section appears here.
In the main Eclipse menu click Help, then Eclipse Marketplace..., In the Eclipse Marketplace popup type checkstyle in the Find: box, then type the Enter key. After a few seconds a list should appear containing Checkstyle Plug-in 5.7.0 (the version number may be higher). Click the Install button for that entry, click the Confirm button when that appears. Agree to the license agreement and click OK on the warning dialog about unsigned content. Let Eclipse restart when it suggest you to do so.
In the Eclipse main menu click Window, then Preferences, then select Checkstyle. Click New ..., then select Project Relative Configuration as Type:. then click Browse ... and naviate to ots-buld-tools/src/main/resources/development and select dsol-checks.xml and click the OK button. Back in the Check Configuration Properties window type dsol-checks in the Name: field, then click the OK button. Back in the Preferences window select the dsol-checks configuration and click on the Set as Default button.
Now you must enable checkstyle for each project.
In the main Eclipse window in Java Perspective right-click on the project name (ots-core) in the Package Explorer sub-window. Select Properties. Select Checkstyle in the tree view. Check the check box Checkstyle active for this project and click the OK button. Click Yes in the Rebuild suggested dialog.
Repeat for ots-demo, etc.
How to commit changes
In the sections above the code was checked out anonymously. This is possible because the source code repository is publicly readable.
In order to commit changes you will need to be registered as a user on https://svn.tbm.tudelft.nl/OTS. Contact Peter Knoppers, Yufei Yuan, or Alexander Verbraeck to get registered. On your first commit eclipse will ask you for your credentials and offer to save them.
Once you are registered the commit procedure is as follows:
Right-click on the top level entry in the Package Explorer (your source code is likely in ots-core, or ots-demo). In the context menu select Team, then Synchronize with Repository.
The first time you do this you'll get the Confirm Open Perspective dialog. Check the Remember my decision check box and click Yes. This opens the Team Synchronizing perspective. In the top-left sub-window is a tree view with your uncommited changes and any files updated on the server that you should update. If there are pending updates, you should update first. Then go back to the Java Perspective and check that everything (still) works and fix any problems. (To go back to the Java Perspective click the Java button in the top right of the eclipse main window.) If a file is changed on the SVN server as well as locally, you may have to resolve any conflicts before you can commit.
When there are no conflicts and no pending updates you should commit your changes. Right-click on the entry in the SVN sub-window and select Commit... from the context menu. In the to left box in the Commit window enter a short description of your changes, then click the OK button. If you have several unrelated changes to commit, select them one by one in the tree view and give each one a suitable description.
Commits in subversion are atomic; they either succeed completely or fail completely (leaving no trace in the repository); it is not possible that a commit succeeds partially. The most common reasons for failing a commit are conflicting changes and out of memory problems on the server.
Setting the eclipse code preferences
These are stored in the ots-build-tools tree. To activate them select in the main menu File, then click Import, expand General, select Preferences, click Next, click Browse. navigate to your workspace folder and in that folder to ots-build-tools, then src, then main, then resources, then development and select eclipse43-ots.epf. Click Open. Check the check box Import all, click Finish.
The default javadoc for a class will now contain all main contributers. This means you will have to delete all others each time you create a new class. You can edit file eclipse43-ots.epf to contain only yourself (do not commit that change).
To re-format the file you are currently editing type ctrl-shift-F. To re-format a group of source code files select the root of the group in the Package Explorer sub-window and type ctrl-shift-F. To undo an accidental re-format type ctrl-Z.)
Installing and using FindBugs (optional)
FindBugs is a tool available as plug-in for Eclipse that you can run to find (potential) bugs in java code.
In Eclipse, go to Help and Install new software…. In the new window type the following in the Work with field: http://findbugs.cs.umd.edu/eclipse/. Click Add.
In a new window, give a name in the Name field, e.g. FindBugs. Click Ok. Back in the previous window, check FindBugs in the list and click Next twice. Accept the terms and conditions with the radio-button and click Finish. You might get a security warning for unsigned content, accept with Ok. Eclipse needs to restart which you can do by clicking Yes.
Right-click on a project, package or java-file in the Package Explorer and go to the Find Bugs submenu and click Find Bugs. FindBugs will find bugs in the selected code and show the number of bugs found in the Package Explorer by appending e.g. (5) to the name in case of 5 bugs in the file/package/project. You can find individual bugs through markers shown to the left of a line of code where the bug is found. You can hover the mouse over the marker to get a message, or right-click and select Show Bug Info.
If you believe that the ‘bug’ is not a problem (FindBugs is not always correct, consider the found ‘bugs’ as warnings), you may suppress it. To suppress, add the following annotation to the method.
The error pattern can be found in the bug info and will look like the following example: RV_RETURN_VALUE_IGNORED. Note that the FindBugs warning is suppressed for the entire method, so, FindBugs will not warn you for this specific kind of bug throughout the method.
To remove all bug markers, right-click in the Package Explorer and go to the Find Bugs submenu and click Clear Bug Markers.