Skip to main content

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 scripts, application bundles or batch files that handle the details for you. Of course, you can modify these or create your own.

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

If you update 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.

Linux

 JMRI distributions for Linux contain shell (bash) scripts for each of the main applications: DecoderPro, PanelPro, etc. These are all structured the same way.

Details

In this section, we briefly describe what each section of the script does.
CLASSNAME
To make the script easier to maintain, the name of the main class is defined near the beginning.
Debug setting
If the DEBUG symbol is set to anything, the script will produce debugging output after each section.
Directory
To run, JMRI needs to be able to find things in the current directory. This step attempts to set that directory automatically.

If the JMRI_HOME environment variable is defined and pointing to a directory that contains a jmri.jar file, change the current directory to there.

Otherwise, change the current directory to where the script file is located.

Classpath
The script builds the Java classpath automatically to contain, in order:
  • class files in the current directory
  • class files in the class subdirectory of the current directory
  • class files in the java/class 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.

Configuration File
If there's an argument to the script, 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 made from the name of the script, followed by "Config2.xml". For example, the DecoderPro script uses DecoderProConfig2.xml as a preferences file. If a copy of that script is named MyJmriApp, it will use a preferences file named MyJmriAppConfig2.xml.

This lets you create as many specialized configurations you'd like by just copying and renaming a startup script.

Java options
The program sets a number of options for the JVM. This includes the necessary program settings, setting memory limits, and various symbols to control operation.

We also set some options here that are only used on MacOS X. This lets people use the the Linux scripts on MacOS X if they'd prefer shell scripts to application bundles.

Alternate port names
RXTX does not know about certain names for serial ports connected via USB. This section looks for a few known names and adds them to the program if present.
Java command
Finally, the script puts all this together into a java command, which it executes.

MacOS X

 JMRI distributions for MacOS X 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 X, they need to be copied from the distributed disk image onto the user's disk drive.

Bundle Details

JMRI has registered four application signatures:
JMRD
DecoderPro
JMRP
PanelPro
JMRI
JmriDemo
JMRL
LocoTools
JMRC
Cornwall demo

Script Details

Each bundle as a startup shell (Bash) script in the Contents/MacOSX directory what does the actual startup. In this section, we briefly describe what each section of that script does.
CLASSNAME
To make the script easier to maintain, the name of the main class is defined near the beginning.
Debug setting
If the DEBUG symbol is set to anything, the script will produce debugging output after each section.
Directory
To run, JMRI needs to be able to find things in the current directory. This step attempts to set that directory automatically.

If the JMRI_HOME environment variable is defined and pointing to a directory that contains a jmri.jar file, change the current directory to there.

Otherwise, change the current directory to where the application bundle is located.

Classpath
The script builds the Java classpath automatically to contain, in order:
  • class files in the current directory
  • class files in the class subdirectory of the current directory
  • class files in the java/class 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.

Configuration File
The configuration file name is made from the name of the application bundle, followed by "Config2.xml". For example, the DecoderPro application uses DecoderProConfig2.xml as a preferences file. If a copy of that application is named MyJmriApp, it will use a preferences file named MyJmriAppConfig2.xml.

This lets you create as many specialized configurations you'd like by just copying and renaming an application.

Java options
The program sets a number of options for the JVM. This includes the necessary program settings, setting memory limits, various symbols to control operation, and some options specific to MacOS X.
Java command
Finally, the script puts all this together into a java command, which it executes.

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 parameters.
Class Parameter
The first parameter of LaunchJMRI.exe is the name of the main class to execute.
Configuration File Parameter (Optional)
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 .bat launcher file and adding the preferences file as a parameter.

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.

(This section needs information on how icons and shortcuts work. The InstallerVISE installer does something to associate an icon and to put two shortcuts on the desktop)