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 Donate to

JMRI Code: Integration with CATS

The Crandic Automated Traffic System (CATS) is a JMRI-based application by Rodney Black for controlling and operating a model railroad. There's more information on the CATS website.

JMRI is a library, and CATS is a large, separately maintained application that uses the library. As such, CATS provides an important reference case for JMRI developers as they extend and adapt their code. CATS should continue to work for it's users, with a minimum of extraneous effort for the CATS developers, even as JMRI changes!

Integration for testing

CATS has two package trees, "cats.*" and "developer.*", roughly corresponding to the two CATS applications.

CATS development does not use a public code repository, and the code is not generally available while it's being developed. Rodney Black periodically makes releases available, including source code, as zip-file archives at the CATS website, see the download links at the bottom of the CATS license page.

As of early 2016, the current CATS distribution (2038) works with JMRI 4.0.1 through to the current (4.3) test versions. From this baseline, we want to keep CATS compiling during ongoing JMRI development. Changes that break CATS should be handled through deprecation, at least for one JMRI production release.

Compiling CATS with JMRI

Download the CATS source and unpack. You'll get a "cats" and "designer" directory. (Designer is meant to be independent of JMRI, but we compile it together just in case) Depending on how you unpacked, you might find those duplicated: cats/cats. Take the lowest level "cats" and "designer" directory and move them directly under JMRI's java/src directory, i.e. alongside the existing apps and jmri directories:

% ls java/src/
META-INF apps cats designer jmri

CATS doesn't have any unit tests, so there's nothing to go in the "test" source tree.

The Ant compilation rules will then compile CATS every time you compile JMRI itself. This will show you errors, deprecation warnings, etc.

To simplify JMRI repository work, the two CATS-related directories are ignored when doing repository operations.

Note that this does include the CATS source within the build, so any jar files you create will also include CATS. Don't use jar files from a build like this for JMRI-only purposes.

JMRI itself has lots of deprecation warnings, so if you want to see just the CATS ones:

The first compilation will compile everything. The second one will only compile the CATS source, so will only give you warnings from those classes.

Running CATS from a local JMRI build

Download the most recent CATS release from the bottom of the CATS license page. As of this writing (Feb 2016), that was the "CATS and designer package (compatible with JMRI 4.0.1 to latest - 2.53 MB)" link which gives version 2038 of CATS.

Move the contents, including the startup scripts "cats.csh" (Linux, Mac OS X) and "cats.bat" (Windows) and other related files, into your top-level JMRI directory.

If you've compiled CATS locally, you don't need the cats.jar or designer.jar files.

Then just execute the appropriate "cats.csh" (Linux, Mac OS X) and "cats.bat" (Windows) script.