Software documentation

Development tools

Structure

Techniques and Standards

How To

Functional Info

Background Info

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 Git for source control. Source control using Git is including as part of the Eclipse "Luna" download. For more information or an alternate method for getting the JMRI source, see JMRI: Getting the Code.

These instructions were developed and tested using "Eclipse IDE for Java Developers" version "Luna Service Release 1a (4.4.1)".

Also note that at the time of writing this help document that JMRI requires JAVA version 8. You must confirm that JRE 8 is the default Java Runtime Environment. Eclipse recommends installing release Luna for Java 8, but there are workarounds described online.

Getting the JMRI Source using Git

To get the source code from GitHub using Git you need to do the following:
  1. Go to GitHub.com and create an account.
  2. Then open Eclipse.
  3. From the main menu bar select "File" then "Import..."
  4. Click on "Git" then "Project from Git" then the "Next" button.
  5. Now select the repository source by clicking on "Clone URI". The Source Git Repository screen should appear.
Eclipse Git pane
  1. Enter the URI "https://github.com/JMRI/JMRI".
  2. Enter your GitHub username and password in the authentication fields.
  3. Click the "Next" button and the Branch Selection screen should appear.
Eclipse Branch pane
  1. Select the branches you want to install. If you're not sure which branches you need, select just the "master" branch. This branch contains the latest code for JMRI.
  2. Click the "Next" button and the Local Destination screen should appear.
  3. Press the "Next" button if the local destination is acceptable to you.
  4. The download will now happen. It might take a while.

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

Eclipse Package Explorer pane

After the download is complete, Eclipse may 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:
  1. 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.
  2. 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

  3. Select the build.xml file using the Package Explorer, then right click, and a menu should appear.
  4. Now select "Run As" then "2 Ant Build".
  5. Confirm under the menu tab "JRE" that you've selected a JDK, not a JRE.
  6. 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 (from site above).
A new JMRI checkout should build cleanly. If not, please check with the JMRIusers or jmri-developers mailings lists for help.

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.

To run an application do the following:

  1. You need to verify the compiler compliance level is set to java 1.8. Select under the main control bar "Window->Preferences", then select "Java->Compiler".
  2. 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)
  3. 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.
  4. 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:".
  5. Select the "Arguments" tab, and under VM arguments 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 
    
    If you're using a 64 bit windows system add the library path:
    -Djava.library.path=.;lib;lib/windows/x64
    
    If you're using a Mac OS X (macOS) system add the library path:
    -Djava.library.path=.:lib:lib/macosx
    
  6. Optional, select the "Common" tab, the section on "Display in favorites menu", check the boxes next to "Run" and "Debug"
  7. 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.
  8. Click "Apply", then "Close" (You could click "Run" at this point, but we've got a little more to do)
  9. 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.
  10. 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.

Installing JavaCC Plugin (alternative to Run As Ant Build method above)

Instead of using the ant build to populate the "tmp" directory, you can install the JavaCC plugin. 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).

Pushing changes to your GitHub branch

The standard practice for getting your changes included in main JMRI code repository is to commit them to your local repository periodically, then when ready to publish "push" an entire set of changes to a repository belonging to you on GitHub, and then finally making a request for somebody to "pull" your changes into the main JMRI repository. See JMRI: Git FAQ "Setting up a Git environment for JMRI Developers" for more information.

It is also good practice to "pull" all of the recent changes from the main JMRI repository before performing your commits. After a "pull" your workspace and eventually your remote GitHub repository will be in synch with the main JMRI repository. To perform a "pull" select your project, then "Team" then "Pull" from the menu.

If you want to see which files are going to be modified before the "Pull", you can use the "Team Synchronizing" feature. To do so, right click on your project, the "Team" then "Synchronize Workspace"

Pushing to your GitHub branch:

Compiler Errors and Warnings

The default Eclipse compiler 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 -> Compiler -> Errors/Warnings".

Eclipse Error pane

Eclipse Error pane

Eclipse Error pane

Eclipse Error pane

Eclipse Error pane