Skip to main content

Code documentation
Development Tools
Code Structure
Techniques and Standards
Help and Web Site
How To
Functional Info
Background Info

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI.org

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:

Environment variables

Since JMRI version 2.11.4, it is possible to influence the settings used to launch JMRI via the use of environment variables which are interpreted by the startup scripts. These are:
JAVA_HOME
This specifies the Java Virtual Machine (JVM) that JMRI will use. This could be a Java Runtime Environment (JRE) or Java Development Kit (JDK).
  • If a JRE is present in a directory called "jre" within the JMRI program directory, it will be used regardless of the JAVA_HOME setting.
  • If JAVA_HOME is undefined and there is no local "jre" directory, the script will go through several steps to try to locate a usable JVM. If that fails, the user will be prompted to install Java.
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
JMRI_HOSTNAME
When using a network connection, this overrides the host name specified in the protocol. Note that this is true for all network connections, so if you have more than one network connection configured it's probably not what you want. This can be set as a Java system property e.g. via the -D option, see below.
JMRI_SERIALPORT
When using a serial port connection, this overrides the serial port name specified in the protocol. Note that this is true for all serial port connections, so if you have more than one serial port connection configured it's probably not what you want. This can be set as a Java system property e.g. via the -D option, see below.
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.

JMRI properties

In this section, we briefly describe some JMRI-specific Java system properties that are interpreted by the JMRI library itself. Consult the Java documentation for Java properties that JMRI will use, including os.name, user.home, etc. Note that many naming conventions have been used, but the "org.jmri...." form is now preferred.

In general, to set one of these, use the form:

      -Dorg.jmri.python.preload=true
in the JMRI_OPTIONS environment variable.
org.jmri.apps.Apps.configFilename
Usually set by the startup scripts
jmri.path.program
Current working directory by default, but can be overridden if set before startup.
jmri.prefsdir
A system-specific directory by default, but can be overridden if set before startup.
jmri_default_cachedir
A system-specific directory by default, but can be overridden if set before startup.
jmri.log
Full or partial pathname of the logging configuration file, by default "default_lcf.xml"
jmri.log.path
The directory for storing logs. If not specified, logs are stored in the JMRI preferences directory.
jmri.inset.width, jmri.inset.height
Overrides the space automatically reserved for screen insets in jmri.util.JFrame
org.jmri.python.preload
If true, JMRI will start the Python script engine during startup. If false or unspecified, the engine will be started when the first script is launched.
There are also a few that are only used during testing, i.e. in the JUnit CI tests. They're documented on the JMRI JUnit page.

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 (not the paths to) usable serial ports to the comma separated list of ports in SERIAL_PORTS.
--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
-T
-t
JMRI applications normally (-t case) configures itself to use the main menu bar on Apple Mac systems. This interferes with Jemmy screen-based tests. The -T option forces standard (on window) Java menus which allows Jemmy tests to run properly. -T is the default when running tests with ./runtest.csh or from ant.
--help
Print a concise 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, SoundPro and LccPro. These provide familiar application icons for the user.

The applications are registered with macOS when copied from the distributed disk image onto the user's disk drive, however, no mechanism within the JMRI applications takes advantage of this registration.

Script Details

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

Uniform Type Identifiers

Uniform Type Identifiers (UTIs) are a mechanism that iOS, macOS, and tvOS use to identify file and URL types to ensure that the correct application is used to open a file or handle a URL. UTIs allow these operating systems to support Packages, or directories that are represented to a user as a single file, and Bundles, which are Packages with executable content.

Application Sandboxes are a security and privacy control in iOS and macOS that limit applications to accessing data the user has explictly granted the application access to, or is contained within the sandbox. In iOS, users can only grant access to files, while in macOS, users can grant access to files and directories. When requesting access, applications request the operating system prompt the user to grant access to file types identified by UTI.

Since the JMRI applications are not subject to application sandboxes, JMRI applications do not export any UTIs that would allow other applications subject to sandboxes to request permission from the user to view or edit JMRI Configuration Profiles.

To allow other macOS applications or any iOS app to request permission from a user to view or edit a JMRI Configuration Profile if the Profile is in a directory with the .jmri extension, add the following UTI and document type to that application's Info.plist file:

        <key>UTImportedTypeDeclarations</key>
        <array>
            <dict>
                <key>UTTypeConformsTo</key>
                <array>
                    <string>com.apple.package</string>
                </array>
                <key>UTTypeIconFiles</key>
                <array/>
                <key>UTTypeIdentifier</key>
                <string>org.jmri.profile</string>
                <key>UTTypeDescription</key>
                <string>JMRI Configuration Profile</string>
                <key>UTTypeTagSpecification</key>
                <dict>
                    <key>public.filename-extension</key>
                    <string>jmri</string>
                </dict>
            </dict>
        </array>
        <key>CFBundleDocumentTypes</key>
        <array>
            <dict>
                <key>CFBundleTypeName</key>
                <string>JMRI Configuration Profile</string>
                <key>CFBundleTypeIconFiles</key>
                <array/>
                <key>LSItemContentTypes</key>
                <array>
                    <string>org.jmri.profile</string>
                </array>
            </dict>
        </array>

Note that you will want to provide icons for these documents; the example does not. Note also that if, and when, the JMRI applications include the UTIs, they need to export the UTIs instead of importing the UTIs, as other non-JMRI applications should.

Note that a UTI is only present for Configuration Profiles, not for Rosters or User Files, since most users store those within a Configuration Profile. Rosters also have a structure that is not conducive to defining a UTI for it (the roster index (roster.xml) is stored adjacent to the roster directory that contains the individual roster entries, images, and icons. User files are, if not contained within a Configuration Profile, in an arbitrary directory, and likely would need individual access from different applications for editing outside of JMRI.

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)
/noalt
If this option is set on the command line, the launcher will no longer use the alternate launching behavior of using a renamed java.exe from a temporary location and revert to the standard java.exe. This means that the launched JMRI application is no longer explicitly mentioned in Windows Task Manager. This option is the default behavior with JDK 11. (since JMRI 4.15.3)
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.

Launcher details

In this section, we briefly describe what the Windows 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 DecoderPro
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 and LccPro applications.

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