Development Tools

• Code/Help Repository:
  • Getting the code
  • Developing with Git
  • Merging a PR
  • Git FAQs
  • Intro to GitHub Desktop
• Building Tools:
  • Ant
  • NetBeans
  • Eclipse
  • IntelliJ IDEA

Code Structure

• Introduction
• Names and Naming
• Application Structure
• Code Structure Patterns
• Swing Structure
• External Connection Structure
• Application Preferences
• Profile Files
• Threading
• Use of XML
  • XML Schema
  • XSLT Formatting
• Web Site
• Javadocs
  • Name Index
  • Packages
  • Classes

Techniques and Standards

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

Help and Web Site

• Providing Help using JmriHelp
• The JMRI Web Site
• Updating JMRI Web and Help
• Creating Help for New Hardware
• Program Documentation Using Javadoc

How To

• Extend JMRI
• Add a New System
• Add a New Type

Functional Info

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

Background Info

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

Donate to JMRI.org

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:

• ant clean compile
• rm -rf target/classes/cats target/classes/designer
• ant -Ddeprecation="on" compile

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.

---