Code 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:

Linux
macOS and OS X
Windows

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:

If you're building and running the program locally, the release.properties and local.properties files set the context.
The file jmri.conf in the system-specific settings directory is used by the startup scripts to set values.
JMRI code reads system properties that were set before JMRI started.
The active configuration profiles are read and processed.
The file python.properties is used to configure the Jython interpreter when it's launched.

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:

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.

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 control file, by default "default.lcf"
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 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 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, and SoundPro. 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:

JMRI
- DecoderPro - launch DecoderPro application
- PanelPro - launch PanelPro application
- SoundPro - launch SoundPro application
- Uninstall - remove entire JMRI suite
- Tools and Demos
  - InstallTest - launch InstallTest application
  - Preferences - open user preferences folder

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:

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