search JMRI:

Development tools

• Getting the code via CVS
• CVS 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

Functional Info

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

Techniques and Standards

• Recommended Practices
• Internationalization
• Logging & Error Handling
• Unit testing with JUnit
• 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

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

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

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.

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)

---