Software documentation

Development tools

Code Structure

Techniques and Standards

How To

Functional Info

Background Info

JMRI Startup Scripts

Although JMRI itself is constructed to "run anywhere", starting a JMRI application requires commands that are specific to the particular type of computer used. With each JMRI distribution, we provide application launchers that handle the details for you.

This page provides information on the tools provided with JMRI distributions on:

If you modify any of these, please consider either making your change on the other machines (and testing it!) or at least putting a comment in the others to describe how they now differ.

During startup, JMRI pulls configuration from several sources:

Linux

JMRI distributions for Linux contain bash shell scripts for each of the main applications: DecoderPro, PanelPro, etc. These are all identical except for application name and main Java class.

Parameters

The JMRI shell scripts take the following parameters:

-c CONFIG
--config=CONFIG
Starts JMRI with the configuration named CONFIG. A configuration determines which configuration profile to use and how the configuration profile selector is displayed at application start.
--cp:a=CLASSPATH
Append the JARs and directories in CLASSPATH to the end of the standard JMRI classpath. This is the recommended way to add additional Java classes to JMRI.
--cp:p=CLASSPATH
Prepend the JARs and directories in CLASSPATH to the beginning of the standard JMRI classpath. This is the recommended way to override existing Java classes in JMRI.
-d
--debug
Print debugging statements within the launcher script itself to the console. On macOS, this is always on, and debugging output is available through the Console.app.
-DPROPERTY
Pass a Java System Property to the Java Virtual Machine. This will be available to the JMRI application while running.
-JOPTION
Pass a complete Java option to the Java Virtual Machine. The most commonly useful option is the maximum memory JMRI is allowed to use, passed as -J-Xmx2048m (in this example, set to 2 GB).
-p PROFILE
--profile=PROFILE
Start JMRI with the configuration profile PROFILE. The profile can be specified by its complete path or by its internal Id.
--serial-ports=SERIAL_PORTS
Set the names of usable serial ports to the comma separated list of ports in SERIAL_PORTS. This is ignored on macOS.
--settingsdir=SETTINGS_DIR
Set the directory that JMRI uses to find its initial configuration to the directory specified in SETTINGS_DIR. It is generally recommended not to set this manually, but to let JMRI determine this on its own. This defaults to:
Linux
${HOME}/.jmri
macOS
${HOME}/Library/Preferences/JMRI
--help
Print a consise list of all options the launcher handles.

If you need to set one or more of these parameters persistently, set them in the default_options variable in the file jmri.conf in the settings directory, with the exception of the --settingsdir=PATH parameter. An example is:

default_options="-J-Xmx2048m"

macOS

JMRI distributions for macOS contain application bundles for each of the main applications: DecoderPro, PanelPro, etc. These provide familiar application icons for the user.

To register the bundles with macOS, they need to be copied from the distributed disk image onto the user's disk drive.

Bundle Details

JMRI has registered five application signatures:
JMRD
DecoderPro
JMRP
PanelPro
JMRI
(generic JMRI, was JMRIdemo; no longer used)
JMRL
LocoTools (no longer used)
JMRC
Cornwall demo (no longer used)

Script Details

Each bundle has a startup bash shell script in the Contents/MacOSX directory what does the actual startup. This is the same script as used for Linux, see please see that section for details.

Windows

Upto and including JMRI version 2.3.2, the Windows .bat files just create a fixed java command and executed it.

From JMRI version 2.3.3, the individual Windows .bat files now call a small launcher application, LaunchJMRI.exe.

Command-line details

In this section, we briefly describe the launcher application command-line options and parameters.
/debug
If this option is set on the command line, a window is opened that displays various useful information for debugging purposes. (since JMRI 2.5.1)
/noisy
Set this option to enable the Java Console window. System messages are now available via the 'Help > System Console ...' menu option in the main JMRI window. (since JMRI 2.5.1)
/32bit
If this option is set on the command line, the launcher will force the use of a 32-bit Java Runtime Environment on 64-bit machines. This option has no effect on 32-bit machines. (since JMRI 2.99.4)
/profile PROFILEID
If this option is set on the command line, the launcher will use profile PROFILEID as the JMRI configuration profile to use instead of the default one. (since JMRI 3.7.1)
--cp:a=CLASSPATH
Append the JARs and directories in CLASSPATH to the end of the standard JMRI classpath. This is the recommended way to add additional Java classes to JMRI. (since JMRI 4.5.7)
--cp:p=CLASSPATH
Prepend the JARs and directories in CLASSPATH to the beginning of the standard JMRI classpath. This is the recommended way to override existing Java classes in JMRI. (since JMRI 4.5.7)
Class Parameter (Required)
The first parameter of LaunchJMRI.exe, after any of the above options, is the name of the main class to execute.
An example to launch DecoderPro would be "apps.DecoderPro.DecoderPro"
Configuration File Parameter
If there's a second argument to the launcher, it will be used as the name of the preferences file used to configure the program at startup. If the user saves the preferences from the program, they'll go to this file too.
If no argument is provided, the configuration file name is defaulted in the application. For example, the DecoderPro application uses DecoderProConfig2.xml as a preferences file. If the launcher is called by 'LaunchJMRI.exe apps.DecoderPro.DecoderPro MyJmriAppConfig2.xml', it will use a preferences file named MyJmriAppConfig2.xml.
This allows you to create as many specialized configurations you'd like by creating a new Start Menu and/or Desktop shortcut to 'LaunchJMRI.exe' file and adding the preferences file as a parameter.

Environment variables

As from JMRI version 2.11.4, it is possible to influence the settings used to launch JMRI via the use of Environment Variables. The Environment Variables used are:
JMRI_HOME
This determines the program location
JMRI_OPTIONS
This specifies additional JVM options
JMRI_PREFSDIR
This specifies the location of an alternative preferences directory
JMRI_USERHOME
This specifies the location of an alternative user home directory
If both JMRI_PREFSDIR and JMRI_USERHOME are defined, the location defined by JMRI_PREFSDIR will take precedence over the location defined by JMRI_USERHOME for determining the location of the preferences file.

Launcher details

In this section, we briefly describe what the launcher application does.
Directory
To run, JMRI needs to be able to find things in the current directory. This step changes the current directory to where the launcher is located.
Java options
The launcher sets a number of options for the JVM. This includes the necessary program settings, setting memory limits, and various symbols to control operation.
Classpath
The script builds the Java classpath automatically to contain, in order:
  • class files in the current directory
  • class files in the classes subdirectory of the current directory
  • all jar files in the current directory, except jmri.jar
  • jmri.jar in the current directory
  • all jar files in the lib subdirectory of the current directory
This allows you to drop jar files into the JMRI install directory for the JMRI plug-in mechanism.
Java command
Finally, the launcher puts all this together into a java command, which it executes.

Start Menu shortcuts and Desktop icons

In a default JMRI installation, a number of shortcuts are created in the Start Menu, along with Desktop Icons for DecoderPro and PanelPro.

Start Menu shortcuts

All JMRI Start Menu shortcuts are placed in the "JMRI" start menu folder (or sub-folders) in the following structure: Additional icons may be placed within this structure depending on the options chosen during installation and the version of JMRI being installed.

Start Menu shortcut example for DecoderPro (assuming JMRI is installed in the default location "C:\Program Files\JMRI"):

Important note: in the following, replace "C:\Program Files\JMRI" by "C:\Program Files (x86)\JMRI" if your Windows is a 64bits version.

Shortcut name
'All Users' on Windows 2000 and XP - C:\Documents and Settings\All Users\Start Menu\Programs\JMRI\DecoderPro.lnk
'All Users' on Windows Vista and 7 - C:\ProgramData\Microsoft\Windows\Start Menu\Programs\JMRI\DecoderPro.lnk
'Current User' on Windows 2000 and XP - C:\Documents and Settings\[username]\Start Menu\Programs\JMRI\DecoderPro.lnk
'Current User' on Windows Vista and 7 - C:\Users\[username]\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\JMRI\DecoderPro.lnk
Target
"C:\Program Files\JMRI\LaunchJMRI.exe" apps.gui3.dp3.DecoderPro3
(up to version 3.11.x was: "C:\Program Files\JMRI\LaunchJMRI.exe" apps.DecoderPro.DecoderPro)
Start In
"C:\Program Files\JMRI"
Shortcut Key
None
Run
Normal window
Comment
Start Decoder Pro
Icon
"C:\Program Files\JMRI\decpro5.ico"

Desktop Icons

Desktop Icons for DecoderPro and PanelPro are created in the default installation - at installation time an optional desktop icon can also be created for the SoundPro application.

The structure of Desktop Icon creation is similar to that of the Start Menu shortcuts above - example Desktop Icon for DecoderPro (again assuming JMRI is installed in the default location "C:\Program Files\JMRI"):

Shortcut name
'All Users' on Windows 2000 and XP - C:\Documents and Settings\All Users\Desktop\DecoderPro.lnk
'All Users' on Windows Vista and 7 - C:\Users\Public\Desktop\DecoderPro.lnk
'Current User' on Windows 2000 and XP - C:\Documents and Settings\[username]\Desktop\DecoderPro.lnk
'Current User' on Windows Vista and 7 - C:\Users\[username]\Desktop\DecoderPro.lnk
Target
"C:\Program Files\JMRI\LaunchJMRI.exe" apps.gui3.dp3.DecoderPro3
(up to version 3.11.x was: "C:\Program Files\JMRI\LaunchJMRI.exe" apps.DecoderPro.DecoderPro)
Start In
"C:\Program Files\JMRI"
Shortcut Key
None
Run
Normal window
Comment
Start Decoder Pro
Icon
"C:\Program Files\JMRI\decpro5.ico"

Retrieving "legacy" DecoderPro from versions prior to 4.0.x

The "legacy" DecoderPro that was existing prior to version 4.0.x has been removed from the distribution package and the former "DecoderPro 3" has been promoted to be the only available DecoderPro version.

If you absolutely cannot use the new DecoderPro user interface (roster view), we suggest one of the following methods:

  1. Using PanelPro with script: With the exception of a different icon and different fixed buttons on the main window, PanelPro has an identical user interface to the legacy DecoderPro.
    • You can add the 3 fixed buttons (Open Roster, Service Mode, Operations Mode) that used to be on the legacy DecoderPro by adding a script at start-up.
    • Go to Edit > Preferences > Start-up > Scripts > Add Script. Select file "C:\Program Files\JMRI\jython\jython/MakeOriginalDecoderPro.py"
    • Then, save and restart.
  2. Using PanelPro with buttons:
    • You can add several fixed buttons of your choice on the PanelPro interface.
    • Go to Edit > Preferences > Start-up > Buttons > Add Button. Select the action of your choice. Repeat for as many buttons as you wish.
    • For same buttons as on legacy DecoderPro, select "Open Roster", "DecoderPro service programmer" and "DecoderPro ops-mode programmer"
    • Then, save and restart.
  3. Adding a custom shortcut to legacy DecoderPro:
    • Copy and Paste the "DecoderPro" shortcut (on your desktop or in the start menu)
    • Rename the copy to "DecoderPro legacy" (or anything else of your choice, but not "DecoderPro")
    • On the new shortcut, right-click > Properties
    • In target, replace existing one by: "C:\Program Files\JMRI\LaunchJMRI.exe" apps.DecoderPro.DecoderPro
    • This will launch the legacy DecoderPro interface.