JMRI Code: Building with IntelliJ IDEA
IntelliJ IDEA Community Edition (available from www.jetbrains.com/idea/)
makes a great platform for working with JMRI and Java on OS
X, Windows and *nix.
Here we describe working with version 2018.1 and up.
JMRI developers use Git for source control. Source control using Git is including as part of the IntelliJ IDEA download. For more information for getting the JMRI source, see JMRI: Getting the Code.
These instructions were developed and tested using IntelliJ IDEA 15 and 16 Community Edition (free).
Installing IntelliJ IDEA
- Go to GitHub.com and create an account.
- In GitHub web, go to the JMRI/JMRI repo and "Fork" the JMRI repository to your own remote copy. To do this, log on to your account at GitHub.com and navigate to the JMRI repository https://github.com/JMRI/JMRI In the upper right hand corner of the page you will find a button labeled "Fork". Press the "Fork" button to create your own repository of the JMRI source. (see Getting the Code).
After downloading and running the installer for your OS,
configure the IntelliJ application as follows:
On OS X
- Open IntelliJ
- From the Help menu, select "Edit Custom VM
- In the dialog, answer "Yes" to create a copy of the
application's vmoptions file:
- Add the line "-Didea.native2ascii.lowercase=true" to
the contents of this file and select Save All from the File
- IntelliJ 2016 and up are now ready to use for development with
JMRI. The vmoptions file is store in
But in version 15, IntelliJ on OS X did not correctly name this vmoptions file ( read more).
To correct this, close IntelliJ 15 and in Finder go to the
Rename the newly created file
idea.vmoptions(effectively removing the "64" part).
On Windows and *nix
- From the Help menu, select "Edit Custom VM Options".
- Add the line "-Didea.native2ascii.lowercase=true" to
the contents of this file and select Save All from the File
It will be saved into the location under user home. That's
$HOME/.IdeaICXX/idea$BITS.vmoptionsfor *nix and
%USERPROFILE%\.IdeaICXX\idea%BITS%.exe.vmoptionsfor Windows (XX = the version number, BITS = the chip version installed).
If the IDEA_VM_OPTIONS environment variable is defined, or a *.vmoptions file exists, then this file is used instead of the file located in the IntelliJ IDEA installation folder.
More info on setting these important vmoptions is
available on the
Idea web site.
Note: If you have a hint how to set this at the Project level instead of tinkering with local application settings, please tell JMRI users at Groups.io.
Start IntelliJ and choose "Preferences" from the application menu (OS X) or Edit menu (Win).
- From the Editor -> File Encodings tab, check
"Transparent native-to-ascii conversion":
- From the Version Control -> GitHub tab, enter
"github.com" as the Host and enter your Login
- From the Build, Execution, Deployment -> Java
Compiler tab, select "1.8" as the Project bytecode
- Click OK to close the Preferences.
Getting the JMRI Source using Git
To get the source code from GitHub into IntelliJ, follow these steps:
- Open IntelliJ.
- From the main menu bar select File -> New ->
Project from Version Control -> GitHub
- If prompted, enter your GitHub username (Login) and
Password in the authentication fields and click
- The Clone Repository pane should now appear. Select a
Git Repository URL from your account and point to your
local repo folder as "Parent Directory":
Optionally click "Test" at top right to check your connection:
- Click "Clone" and follow progress in the indicator at
the bottom of the Project window:
- In the pane that opens after download is complete,
check the location on disk,
confirm the project name (like the original i.e. "JMRI") and click "Next":
- Select "Create project from existing sources" and click
- Click "Mark all" and then "Finish":
This will add JMRI to the IntelliJ Project window.
The Project window
Along the edges of the window are several groups of tools, often used are:
- the Project tab on the left
- the JMRI directory in the left half
- the Ant Build tab on the right and
- the Version Control tab at the bottom.
- the Git: master at the bottom righthand corner, showing the current Branch ("master") with a menu to change to another Branch.
To work on the JMRI code, always start a new Branch off
from master, so your own "master" will stay intact.
To create a new Branch in IntelliJ, check out master, VCS > Git > Pull... from JMRI-master, VCS > Git > Push... to create a current base.
Now then from the Git Branches pane, select "+ New Branch":
Supply a name i.e.
my-dialog-2 and click OK.
Note: Starting your Branch name with a unique two letter combination will make it stand out from the long list much better than a name like
Building and running JMRI using Ant
We recommend that before you try to build and run one of
the applications within IntelliJ, you run the Ant Build ->
<Default target> first. This will create the necessary
working directories, load some resource icons, and create
needed Java files. To run the
ant build.xml do
- Ant needs a JDK (Java Development Kit) in order to run
the supplied "build.xml" file. The IntelliJ IDEA
download comes with a JDK, but you have to configure ant to
use the right JDK.
To verify the JDK is set to java 1.8, open the Ant Build tab  and select the Properties button  at the top right of the pane.
As "Run under JDK:" select 1.8 (java version 1.8.xxx) if not already set:
Click "OK" and save your JMRI Project (Cmd-S/Ctrl-S).
- Select a file in one of the JMRI ant folders in the Ant Build list, right click, and select "Run Target", simply double-click or press the green triangle "Run" button at the top of the pane. This should start the ant build. Follow any messages in the Event Log that pops up from the bottom edge of the Project window.
- A new JMRI checkout should build cleanly. If not, do ant clean (meaning: double-click the clean item on the Ant Built list before contacting the jmri-developers.groups.io for assistance.
If the ant build is successful, you can launch any of the JMRI applications from the Ant Build tab.
Building and running JMRI using IntelliJ
To run an application, either:
- From the main menubar open the "Build" menu and select
a JMRI package like
- Open the Ant Build tab and from the "Ant Build" list,
right click the desired package i.e.
decoderproand select "> Run Target".
Note: The first two "JMRI" sets will build the English and French JHelpDev TOC & Index files respectively. Hover your mouse over them and read the tooltip to learn which is which.
The Messages Center Console will list all steps of the build process, after which a Java icon will open with the application running including all your new edits.
Pushing changes to your GitHub branch
The standard practice for getting your changes included in
the main JMRI code repository is to Commit them to your local
repository periodically and, when ready to publish
everything, "Push" an entire set of Commits to your own
remote repository on GitHub, and finally make a Pull Request
for the maintainers to "Pull" your changes into the main JMRI
When working on more than one computer or different IDEs, Committing and Pushing makes your new edit available on the other computers.
See the 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 and you will see recent work by others. To perform a "Pull":
- Select your project i.e. JMRI in the
Project tab, right click and select "Git" ->
"Repository" -> "Pull..." from the context menu:
or from the VCS menu select "Git" -> "Pull..."
- You may be asked first to confirm the origin of your
remote repo, in our case "JMRI/JMRI":
- The Pull Changes dialog opens:
 Select a remote repository (depending on the way you want to manage that, either your own repo or JMRI's as in the example).
 From the displayed list, select the appropriate Branch to merge (you might also Pull an extra Branch to switch to later).
If what you expect is not in the list, click the Refres button .
- To conclude, click "Pull" and answer how you would like
to combine the new data into the existing local repo:
Pushing to your GitHub Branch:
- First, commit your changes to the local repository on
To commit a set of changes, choose "Save All" from the Edit menu, select your project i.e. JMRI in the Project tab, right click and select "Git" -> "Commit Directory..." from the context menu:
- In the Commit Changes pane, enter a Commit Message 
describing your changes/fix (line 1 will be used as the
short title, add more detail from line 2).
Select the files  you wish to commit and deselect files you don't.
Choose your name from the list as Author :
- Click the "Commit" button  to add your saved edits to the local GitHub Branch...
- Or hover over the Commit button and choose "Commit and
Push..." to continue to Push this set of changes from your
local repository to your remote repository on GitHub right
after the Commit (so others can access it and study it for
inclusion into JMRI).
- In the Push Commits pane, review your description and click "Push".
- To push to your GitHub repository after a local Commit,
just select "Push..." from the "VCS" -> Git menu:
- If this went fine, a confirmation will appear at bottom
left over the Version Control tab:
Check that the class and output paths have been set up correctly for the compiler. This should happen
automatically as part of the JMRI GitHub repository you copied at the start (stored in the
.iml file, see the IntelliJ Compilation Settings
- In IntelliJ, select the File > Project Structure... menu item.
- Select Modules under Project Settings on the left.
- Select the Sources tab on the right.
- In the file tree, select the JMRI > java > src folder icon and click on Mark as:
Sources (the blue icon).
- Repeat for the test classes by selecting JMRI > java > test and clicking on the green
Mark as: Tests icon.
- In the column to the right both choices will be visible.
From now on you will also see these special icons in the Project file listing:
- From the Build menu select Build Project or Build Module 'JMRI' (and wait for up to 20 minutes, do some stretch exercises etc).
We've documented the following steps to help you get started using the built-in Debug tool. We tested the JMRI project with the JAR, Application and JUnit (test) Templates.
- In IntelliJ, start by opening Preferences > Build, Execution, Deployment
and check "Generate debugging info":
- Choose "Debug..." from the Run menu:
On the small "Debug" pane that appears, click "Edit Configurations..."
Alternatively, on the top right, click on "Add Configuration...":
- On the top left of the new pane that appears, click the + sign (Add New Configuration).
Or simply type Command + N.
Select "JAR Application" in the list.
- This opens the "Run/Debug Configurations" pane:
- As the Name of this Configuration, enter somethong like "JMRI DP debug".
- Make sure "Build" is visible in the "Before launch:" table, select "Run Ant target" and choose
"jar" from the build.xml list
In case of a JUnit template, opt for "build" instead.
- Check "Activate tool window" near the bottom of the pane.
- Enter "jmri.jar" as the "Path to JAR" or use the "..." button to navigate to the freshly built
jmri.jarin your Project.
- Make sure the prefilled "Working directory:" is showing your local path to JMRI (see example).
As the "JRE:" choice set "Default (1.8)".
- Select "JMRI" using the "Search sources using module's classpath:" drop down.
- Click "OK" to complete the configuration setup.
- To run a debug session, start by opening a .java file and set a Breakpoint on a line in your
code by clicking in the left margin of the central edit pane:
- We're now ready to start a Debug session by clicking the Bug button at the top right, making sure our
"JMRI DP debug" configuration is selected in the drop down to the left of it:
- After a while, at the bottom of the main IntelliJ IDE interface, the Debug pane appears, stopping
just before your Breakpoint or an Exception:
- Inspect the current values of the active variables, and click the Step Into button to execute 1 line of
A further explanation of this pane and debugging in general can be found in the
IntelliJ Online Help.
If your code was not compiled just before debugging, the source and class files might be out of sync, so be sure to build first. As described above, you could add that to your Debug Configuration too, but it does take extra time before each run.
Testing with IntelliJ
Besides Debug, there's also a "Run ... with Coverage" option available in the Run menu and tool bar.
When you create or edit a test
(located in your Project at JMRI.java.test etc.) you can
test it either as part of the
alltest Ant Build
(double click in the IntelliJ Ant Build right hand
column to run), run it on its own using the
test-single Ant Task
or create a JUnit type Debug Configuration with optional Coverage reporting.
To use test-single, enter the path of your test in the Ant Build Properties by either clicking the Properties button at the top or right-clicking on any line in the Ant Build column, choosing "Properties". Open the "Properties" tab, click the + (Add) sign at lower left and enter
in the Name column and the path to your test under Value,
starting with either
jmri. as shown:
The Code Coverage of your test can be checked by running Debug With Coverage. Unless you install the Jacoco
application, IntelliJ runs its own coverage scheme:
After tests have completed the Coverage pane opens. Double-click a class line to open the code page. In the left margin coverage is marked:
- Confirm that the class and output paths have been set up correctly for the compiler.
- An IntelliJ SpotBugs plug-in is not yet available, so you run it as an Ant Build task and study the .html
To add the path to SpotBugs for Ant in your
local.propertiesfile to match the place where the SpotBugs application is located on your computer add these lines:
# configure SpotBugs
See the JMRI SpotBugs help.
- Next, from the Ant Build tab select the spotbugs ant task, wait for up to 20 minutes (do some stretch exercises etc), followed by SpotBugs doings its duty. The analysis results show up as an htnl page called spotbugs.html that is placed in the root of the JMRI Module. Right click to open it with your favorite browser.
For additional resources check the official SpotBugs Help
Making a Pull Request
When your contribution is ready, submit a "Pull Request" to the main JMRI code repository on the GitHub website so the maintainers of JMRI can study your proposed changes and merge them into the master JMRI repo.
To make a PR from within IntelliJ IDEA, select "Create
Pull Request" from the "VCS" -> Git menu (it's the one but
last item, supported by the Git plug in).
Note: Be sure to select your own repository if you see multiple options to choose from in this submenu:
To create a PR from GitHub web - outside IntelliJ - start by signing on to the GitHub web site, selecting your repository & branch and clicking the Pull Request button. For more info, see the Git Developer Help page.
Edit .properties files
Before you start, make sure you have set up IntelliJ to
convert special characters using lower case
encoding strings, as only then will your changes be accepted
for merging into JMRI.
The instructions to set this via
at the top of this page.
In addition, check that in the IntelliJ Preferences > Editor > Code Style > Properties you checked "Insert space around key-value delimiter", or your edits will mess up the work already in place.
To easily edit Resource Bundle
.properties files, containing translations in different languages,
select a closed 'Bundle' folder in the Project file list and type Cmd + arrow down key, or double click one
of the language files. This will open a window with a list of coded keywords on
the left and a text box for every translation to the right:
When you open a specific language file, at the bottom of the screen you can switch views by clicking the
Resource Bundle or the Text tab:
When in testing your app you conclude that you would like
to remove your last couple of Commits, IntelliJ gives you the
option to graphically Reset your HEAD.
To do this, open the "Version Control" -> "Log" tab at the lower left of the Project window to view a "Track Plan" of the history of your Branch, all the way back to the different parts that made JMRI:
Click on any line to view the changes that were Committed
at that point in time (listed to the right).
To reset your repo (HEAD) back to a certain point, right click on the corresponding line and select "Reset Current Branch to Here..." (and confirm).
Confirm the way you want to save or discard your Commits after that point in the dialog:
Error: Can't start Git
- Quit and restart IntelliJ
- If that does not fix it, quit IntelliJ and start the Apple Xcode application.
You will be asked to agree with its licence agreement, and that will reenable the Git installation to be used inside IntelliJ as well as Xcode.
When you click Debug with a configuration selected (at top right) you might see a path not
found. name: com.intellij.rt.debugger.agent.CaptureAgent with the Debug Variables pane showing: "Frame
is not available". This is caused by an accidental exception breakpoint on ClassNotFoundException. Open
View Breakpoints... from the Run menu and uncheck the breakpoint under "Java Exception Breakpoints".
We fixed it by unchecking the red lightning symbol in the margin of the
loadClass code listing.