search JMRI:

Development tools

• Getting the code via SVN
• SVN FAQs
• Building with Ant
• Building with NetBeans
• Building with XCode
• Building with Eclipse
• Building with JBuilder

Structure

• Introduction
• Application Structure
• Names and Naming
• Code Structure Patterns
• Swing Structure
• External Connection Structure
• Threads
• Use of XML
• Web Site
• JavaDocs
  • Name Index
  • Packages
  • Class heirarchy

Techniques and Standards

• Recommended Practices
• Continuous Integration
• Internationalization
• Logging & Error Handling
• Unit testing with JUnit
• Documentation with JavaDoc and UML
• Run the FindBugs static analysis tool
• Providing help with JavaHelp
• Portable Filename Method
• XML Persistance

How To

• Extend with Plugins
• Add a New Type
• Add a New System

Functional Info

• Turnout Feedback
• Network Connections
• How the startup scripts work

Background Info

• Technology Roadmap
• Survey of JVM Capabilities
• Usage Poll, Spring 2007

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:

• Linux
• Mac OS X
• Windows

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.

Library Files

The RXTX Serial library requires some platform specific native libraries in order to interface to the serial port drivers. JMRI applications need to use the version of the library that is correct for the operating system and the CPU architecture.

The two most common architectures at this time are i386 and x86_64, respectively the 32 bit Intel and the 64 bit AMD/Intel systems.

The startup scripts will use some common applications (arch, uname) to determine the current operating system and architecture, and then set up the correct library paths for Java to find the right shared library files.

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.

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. If you have a device file name that JMRI cannot find, you can set the environment variable JMRI_SERIAL_PORTS to be comma-separated list of the names.

Java command

Finally, the script puts all this together into a java command, which it executes.

Mac OS X

JMRI distributions for Mac OS 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 Mac OS X, 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)

JMRL

LocoTools (no longer used)

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 Mac OS 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 options and parameters.

/debug (Optional - from JMRI 2.5.1)

If this option is set on the command line, a window is opened that displays various useful information for debugging purposes.

/noisy (Optional - from JMRI 2.5.1)

If this option is set on the command line, the launcher does not attempt to minimise the Java Console window - as from JMRI 2.5.1, the default behaviour is to minimise the Java Console window.
Starting with JMRI 2.11.1, the behaviour of this option has changed - this now determines if the Java Console window is enabled or not. System messages are now available via the 'Help > System Console ...' menu option in the main JMRI window.

/32bit (Optional - from JMRI 2.99.4)

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.

Class Parameter

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

• 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"):

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

---