JMRI: Building with Eclipse

Eclipse (available at www.eclipse.org) makes a great platform for working with JMRI, but because the repository is not set up as an Eclipse project there are a few wrinkles in getting it work. (The description below is accurate for version Eclipse 3.2.2 for MacOS X. Eclipse is supposed to be identical across platforms, but this hasn't been checked on anything else).

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).

On this page, we have our current instructions for getting JMRI working in side Eclipse, followed by older instructions. Another version is available in a JMRIusers post.

Setting up Eclipse for building JMRI

Unfortunately, we don't know how to properly put the Eclipse configuration information directly into CVS, so there are a number of manual setup steps you'll have to take.

Create an empty directory, which will be your Eclipse workspace for JMRI.
Open Eclipse. When it asks for a workspace, select the empty directory you just created.
From the "Window" menu, select "Show View", then "Other..."
In the "Show View" window that just opened, expand the "CVS" folder select "CVS Repositories", and click OK.
A "CVS Repositories" pane will open. If you have any defined already, they'll show. Right click (or CTRL-Click with a one-button mouse) on an empty part of the window, then in the pop-up menu select "New..", then "Repository Location".
Fill out the form that shows up:
- Host is "jmri.cvs.sourceforge.net"
- Repository path is "/cvsroot/jmri"
- User is "anonymous" (if you're a JMRI developer authorized to change CVS, put your sourceforge ID here)
- Leave password blank
- Leave the rest of the form at defaults (unless you're a JMRI developer, in which case select "ext" as the connection type)
- Click "Finish"
If all is well, an entry should show up in the "CVS Repositories" tab. You can close that tab now if you'd like.
From the file menu, select "Import.." In the resulting "Import" window expand the CVS folder and select "Projects from CVS". Click "Next"
Select "Use existing repository location", and highlight the repository entry you just created that refers to JMRI. Click "Next"
Select "Use specified module name" and enter "eclipse" (all lower case). Click "Finish"
If all is well, you'll see a "Checking out..." window while the files are pulled from CVS. This will take a while. When it's done, you'll have all the JMRI code in your workspace directory, and just have to configure Eclipse to run it.
From the "Window" menu, select "Show View ..." then "Navigator". You'll get a multi-pane window that shows various views of the JMRI code.
From the "Run" menu, select "Run..." We'll use the window that opens to configure which program(s) to run.
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 "java" (lower case important) for "Project:" and "apps.DecoderPro.DecoderPro" for "Main class:".
Select the "Arguments" tab, and under VM argments enter
```
-Djava.security.policy=lib/security.policy -Dpple.laf.useScreenMenuBar=true -Xms10m
```
(You should probably cut and paste that). Under working directory, select "Other:" and enter "${workspace_loc}"
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.

Older version of instructions

Checking out code

Start Eclipse - it will ask you for a workspace name. You can make up something suitable, e.g. "jmri-eclipse".
Create an empty Eclipse java project to hold the code. (File -> New -> Project, then "Java Project" on the list of options that appears). accepting all defaults. Call the project "temp" - it will eventually be deleted. Select "Create separate source and output folders".
From the Window menu, select the Show View item, and then in the cascaded menu select Other ...
A tree navigation view will appear; select (open) the CVS folder Select the 'CVS Repositories' item under the CVS folder
A Repositories View panel will open. If you have previously defined any repository locations, they will be shown; otherwise it is an empty window.
Right click within the window and select New. In the cascaded menu that then opens, select Repository Location
A dialog will open to define the new repository location. Enter:
- Host: jmri.cvs.sourceforge.net
- Repository path: /cvsroot/jmri
- Username: anonymous (or if you have a sourceforge id, you can use that)
- Leave password blank if you are using anonymous, and connection type defaulted to pserver
At this point, Eclipse will communicate with the repository, and a new item will show up in the Repository view pane, with several sub-items under it.
Click to expand the 'Head' subitem (or the 'Branches' or 'Versions' subitem if you know your way around and that is more appropriate)
Select 'all' as a target
Right-click the target and select 'Check out module'
When it finishes and displays all of the projects, you need to switch to the Navigator view: Window->Show View->Navigator
In the left-hand window (Navigator), right click on "temp" and select "delete". You don't need this any more.

Getting Ready to Build

You've now got the code, but it isn't set up for Eclipse to build it or work with it. The next step is to exit Eclipse, as you need to do a couple of things "behind its back".

Exit Eclipse
Copy the two files below (.project and .classpath) into files of the same names in the /java directory of your Eclipse workspace. (This is a bit tricky using the standard Windows editors, because they don't like files with null filetypes).
You'll also need to copy the file javax.comm.properties into the /java/lib subdirectory. If you are already running the production version of JMRI you will have this in the /lib subdirectory of your Java Runtime Environment (JRE). If not you'll need to get the javax.comm library from java.sun.com.
Restart Eclipse, using the same workspace - you're almost there, but not quite
Pick the application you want to work with - they all use the same code anyway. Open directories using the '+' sign in the order java - src - apps - DecoderPro. Right click on DecoderPro (or whatever you have chosen), select "Debug As>" then "Java Application". Eclipse will scan the sources then build the image. But it will failbecause one more change is needed...
Terminate the program (Debug perspective, Debug pane, right click to "Terminate and Remove").
Go back to the Java perspective, right click on DecoderPro, select "Debug As>" then "Debug...". This will open a dialog box. Select the Aguments pane, unclick "Use default working directory" and edit the line above to read "${workspace_loc}" . Click apply.
Now it should all work. Run the image again to be sure (you can use "Debug Last Launched" on the Run menu this time).

You can also use ant to build and run the program.

Updating the code from CVS

From time to time, you can update the code to match the current repository contents.

Select the module (folder) to update (example: java)
Right-click the folder and select the 'Team' item from the pop-up.
In the cascaded menu that appears, several CVS-related options appear:
- Commit - commit changes to repository (if you have write access)
- Update - get latest versions from repository
- Synchronize with Repository - one step does it all
There are also branch and label actions that can be performed here if you have the appropriate access and know what you're doing.

.project :

<?xml version="1.0" encoding="UTF-8"?> <projectDescription> <name>jmri</name> <comment></comment> <projects> </projects> <buildSpec> <buildCommand> <name>org.eclipse.jdt.core.javabuilder</name> <arguments> </arguments> </buildCommand> </buildSpec> <natures> <nature>org.eclipse.jdt.core.javanature</nature> </natures> </projectDescription>

.classpath :

<?xml version="1.0" encoding="UTF-8"?> <classpath> <classpathentry kind="src" path="src"/> <classpathentry kind="src" path="test"/> <classpathentry kind="lib" path="lib/collections.jar"/> <classpathentry kind="lib" path="lib/comm.jar"/> <classpathentry kind="lib" path="lib/crimson.jar"/> <classpathentry kind="lib" path="lib/jdom-jdk11.jar"/> <classpathentry kind="lib" path="lib/jh.1.1.2.jar"/> <classpathentry kind="lib" path="lib/jh.jar"/> <classpathentry kind="lib" path="lib/junit.jar"/> <classpathentry kind="lib" path="lib/jython.jar"/> <classpathentry kind="lib" path="lib/log4j.jar"/> <classpathentry kind="lib" path="lib/MRJAdapter.jar"/> <classpathentry kind="lib" path="lib/Serialio.jar"/> <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/> <classpathentry kind="output" path="classes"/> </classpath>