JMRI: Building with Eclipse

Eclipse (available at www.eclipse.org) makes a great platform for working with JMRI.

Eclipse is a complex environment to work with. If you're already familiar with IDEs like Microsoft Visual Studio it won't be too hard to get used to, but it is definitely worth buying a textbook (e.g. The Java Developer's Guide to Eclipse).

JMRI developers use subversion (SVN) for source control as of July 2011. Previously we used CVS for source control, and using CVS is no longer supported. If you were already using Eclipse and CVS it is strongly recommended that you start fresh and download the latest version of Eclipse and create a new workspace before using SVN to get the latest files.

These instructions were developed and tested using "Eclipse IDE for Java Developers" version "Indigo Release".

Also note that at the time of writing this help document that JMRI required JAVA version 6. You must confirm that JRE 6 is the default Java Runtime Environment.

Setting up Eclipse for building JMRI using Subversion

The standard Eclipse download doesn't have the subversion plugin enabled. To install subversion do the following:

Open Eclipse.
From the main menu bar select "Help" then "Install New Software..."
Now click on the "Available Software Sites" link.
Select "http://download.eclipse.org/technology/subversive/0.7/update-site/" and then press the "Enable" button followed by "OK". This should return you to the Install window.
If the above link didn't appear in the available software sites, you can manually enter the entire site address into the "Work with" text window.
Now select "http://download.eclipse.org/technology/subversive/0.7/update-site/" in the "Work with:" selection menu, and then select all of the checkboxes, followed by pressing the "Next" button, and complete the SVN installation as prompted by the program.
You will be asked to restart the program, do so, and then complete the subversion installation by selecting a connector or connectors, and again you will be asked to restart the program when the install of the connectors is complete.

Getting the JMRI Source using Subversion

To get the source code from SourceForge using Subversion you need to do the following:

Open Eclipse.
From the main menu bar select "File" then "Import..."
Click on "SVN" then "Project from SVN" then "Next"
Now create a new repository location and enter this URL: "https://jmri.svn.sourceforge.net/svnroot/jmri/trunk/jmri"
If you have a SourceForge id and password enter that now, otherwise leave them blank. The id and password are only necessary if you're going to commit your work back to the repository.
Click "Next" then "Finish"
You should now see a window called "Check Out As", click ""Finish"
If all is well, the check out should begin. It might take a few minutes to download all of the JMRI files.

After the download is complete the Eclipse Package Explorer should look like this:

After the download is complete, Eclipse will be reporting an error: Project 'jmri' is missing required source folder: 'java/tmp'. This will be fixed by running the ant build as described below.

Building and running JMRI using Ant

We recommend that before you try and build and run one of the applications within Eclipse that you run the ant build.xml within Eclipse. This will create the necessary directories, load some resource icons, and create needed Java files using JavaCC. To run the ant build.xml you need to do the following:

Ant needs a JDK (Java Development Kit) in order to run the supplied "build.xml" file. The Eclipse download doesn't include a JDK, so you must download and install a JDK, and then configure ant to use the JDK.
Here's a link to the Oracle site that can provide you with a JDK:
http://www.oracle.com/technetwork/java/javase/downloads/index.html
Select the build.xml file using the Package Explorer, then right click, and a menu should appear.
Now select "Run As" then "2 Ant Build".
Confirm that under the menu tab JRE that you've selected a JDK.
Now press the "Run" button, this should start the ant build.

If the ant build fails, most likely it is because you need a JDK (Java Development Kit) rather than a JRE (Java Runtime Environment) which is the default. To change the JRE, select "Run As" "2 Ant Build" and a new window should appear. Select the "JRE" tab. The change the JRE, select the "Separate JRE:" radio button, and then press the "Installed JREs" button. If you don't see a JDK, you need to add one.

If the ant build succeeds, you can now launch any of the JMRI applications from ant, and create a jmri.jar file if you wish. Use the "2 Ant Build" and in the window select the "Targets" tab, and use the appropriate checkbox to generate what you want.

Building and running JMRI using Eclipse

After completing the ant build as described above, you need to refresh the jmri directory. Right click on the jmri directory name and select "Refresh". The refresh operation should trigger a build of the workspace and the build should complete without error.

As of early 2012, the JMRI build path has a library reference to "jre6" which is Java version 6. When installing your JRE be sure and name it "jre6" or you will get an error message stating that the reference to jre6 could not be found.

To run an application do the following:

You need to configure the Java complier to not scrub the output folders, otherwise some of the resources files that are loaded by the ant build will disappear. To stop the scrub, select under the main control bar "Window->Preferences". Then in the preferences window, select "Java->Complier->Building". In the building window deselect "Scrub output folders when cleaning projects", then "OK".
Then run the ant build again to load the output folders.
From the "Run" menu, select "Run Configurations..." We'll use the window that opens to configure which program(s) to run. (If the Run menu does not have a "Run Configurations..." entry, be sure you selected the java directory in the navigation pane above - Eclipse menus are context sensitive)
On the left side, highlight "Java Application", then press the "New" icon above it. The icon looks like a document with a plus sign on the upper-right.
You should now have a new "Main" tab highlighted. Above that, replace "New_configuration" with "DecoderPro". Below it, enter "jmri" (lower case important) for "Project:" and "apps.DecoderPro.DecoderPro" for "Main class:".
Select the "Arguments" tab, and under VM argments enter (You should probably cut and paste):
```
-Xms10m
-Xmx300m
-Djava.security.policy=lib/security.policy 
-Dapple.laf.useScreenMenuBar=true
```
If you're using a 32 bit windows system add the library path:
```
-Djava.library.path=.;lib;lib/windows/x86 
```
Note if you're using a 64 bit windows system change the library path to:
```
-Djava.library.path=.;lib;lib/windows/x64
```
Optional, select the "Common" tab, the section on "Display in favorites menu", check the boxes next to "Run" and "Debug"
If you'd like to create targets to make it easy to run PanelPro and AllTests, repeat the above steps to create a new "Java Application" except specifying "apps.PanelPro.PanelPro" and "apps.tests.AllTest" respectively.
Click "Apply", then "Close" (You could click "Run" at this point, but we've got a little more to do)
You should now be back to the usual Eclipse navigator view, where most development work is done. To see some particular java file, expand the "java" folder at the left, then the "src" folder, navigating down to the file you want.
To run DecoderPro, select it under "Run History" from the "Run" menu. Once you've done that once, you can just click the "Run" icon on the toolbar to rerun the last program.

JavaCC

In March of 2010 JMRI developers started using JavaCC (Java Compiler Compiler) to generate code. Currently the compiler places the output files in the "tmp" directory under "java". The easiest way to create and populate the "tmp" directory is to use the ant build.

Installing JavaCC

Instead of using the ant build to populate the "tmp" directory, you can install the JavaCC plug-in. Here's the steps:

1) Download the Eclipse JavaCC plugin following the instructions found here: http://eclipse-javacc.sourceforge.net

2) After restarting Eclipse, right click on the java directory in the Project Explorer or Navigator and select JavaCC Options.

3) On the JavaCC Options tab, enter the output directory to be java/tmp/jmri/jmris/srcp/parser

4) On the JJTree options page, enter the output directory to be java/tmp/jmri/jmris/srcp/parser

5) Confirm that the "Java Build Path" includes the tmp directory (see Project Properties).

Complier Errors and Warnings

The default Eclipse complier configuration produces many unnecessary warnings. You can adjust the warnings to match the screen shots as shown below by going to Window->Preferences and selecting "Java->Complier->Errors/Warnings"